Contracts

소개

Laravel의 "contracts"는 프레임워크가 제공하는 핵심 서비스들을 정의하는 일련의 인터페이스입니다. 예를 들어, Illuminate\Contracts\Queue\Queue contract는 작업을 큐잉하기 위해 필요한 메서드들을 정의하고, Illuminate\Contracts\Mail\Mailer contract는 이메일을 전송하기 위해 필요한 메서드들을 정의합니다.

각 contract에는 프레임워크에서 제공하는 해당 구현체가 존재합니다. 예를 들어, Laravel은 다양한 드라이버를 지원하는 큐 구현체와 Symfony Mailer 기반의 메일러 구현체를 제공합니다.

모든 Laravel contract는 별도의 GitHub 저장소에 존재합니다. 이를 통해 사용 가능한 모든 contract를 빠르게 참조할 수 있으며, Laravel 서비스와 상호작용하는 패키지를 만들 때 활용할 수 있는 단일, 분리된 패키지로 사용할 수 있습니다.

Contracts와 Facades의 차이

Laravel의 facade와 헬퍼 함수는 서비스 컨테이너에서 contract를 타입힌트하고 해석할 필요 없이 Laravel의 서비스를 간단하게 사용할 수 있는 방법을 제공합니다. 대부분의 경우, 각 facade는 동등한 contract를 가지고 있습니다.

facade는 클래스의 생성자에서 명시적으로 요구하지 않아도 되지만, contract를 사용하면 클래스의 의존성을 명확하게 정의할 수 있습니다. 일부 개발자는 이런 방식으로 의존성을 명확하게 정의하는 것을 선호하여 contract를 사용하고, 다른 개발자는 facade의 편리함을 선호합니다. 일반적으로 대부분의 애플리케이션은 개발 중에 facade를 사용해도 문제가 없습니다.

Contracts를 언제 사용해야 할까

contract와 facade 중 무엇을 사용할지는 개인의 취향과 개발팀의 취향에 따라 달라집니다. contract와 facade 모두 견고하고 테스트 가능한 Laravel 애플리케이션을 만드는 데 사용할 수 있습니다. contract와 facade는 상호 배타적이지 않습니다. 애플리케이션의 일부는 facade를, 다른 부분은 contract에 의존할 수 있습니다. 클래스의 책임을 명확히 유지한다면, contract와 facade를 사용하는 데 있어 실질적인 차이는 거의 없습니다.

일반적으로 대부분의 애플리케이션은 개발 중에 facade를 사용해도 문제가 없습니다. 여러 PHP 프레임워크와 통합되는 패키지를 개발하는 경우, illuminate/contracts 패키지를 사용하여 Laravel의 구체적인 구현체를 패키지의 composer.json에 명시하지 않고도 Laravel 서비스와의 통합을 정의할 수 있습니다.

Contracts 사용 방법

그렇다면 contract의 구현체를 어떻게 얻을 수 있을까요? 사실 매우 간단합니다.

Laravel의 많은 종류의 클래스는 서비스 컨테이너를 통해 해석됩니다. 여기에는 컨트롤러, 이벤트 리스너, 미들웨어, 큐 작업, 라우트 클로저 등이 포함됩니다. 따라서 contract의 구현체를 얻으려면, 해석되는 클래스의 생성자에서 인터페이스를 "타입힌트"하면 됩니다.

예를 들어, 아래의 이벤트 리스너를 살펴보세요:

<?php

namespace App\Listeners;

use App\Events\OrderWasPlaced;
use App\Models\User;
use Illuminate\Contracts\Redis\Factory;

class CacheOrderInformation
{
    /**
     * 이벤트 리스너 생성자.
     */
    public function __construct(
        protected Factory $redis,
    ) {}

    /**
     * 이벤트 처리.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}

이벤트 리스너가 해석될 때, 서비스 컨테이너는 클래스 생성자의 타입힌트를 읽고 적절한 값을 주입합니다. 서비스 컨테이너에 등록하는 방법에 대해 더 알고 싶다면 관련 문서를 참고하세요.

Contract 참조

아래 표는 모든 Laravel contract와 그에 상응하는 facade를 빠르게 참조할 수 있도록 제공합니다:

Contract	참조 Facade
Illuminate\Contracts\Auth\Access\Authorizable
Illuminate\Contracts\Auth\Access\Gate	Gate
Illuminate\Contracts\Auth\Authenticatable
Illuminate\Contracts\Auth\CanResetPassword
Illuminate\Contracts\Auth\Factory	Auth
Illuminate\Contracts\Auth\Guard	Auth::guard()
Illuminate\Contracts\Auth\PasswordBroker	Password::broker()
Illuminate\Contracts\Auth\PasswordBrokerFactory	Password
Illuminate\Contracts\Auth\StatefulGuard
Illuminate\Contracts\Auth\SupportsBasicAuth
Illuminate\Contracts\Auth\UserProvider
Illuminate\Contracts\Broadcasting\Broadcaster	Broadcast::connection()
Illuminate\Contracts\Broadcasting\Factory	Broadcast
Illuminate\Contracts\Broadcasting\ShouldBroadcast
Illuminate\Contracts\Broadcasting\ShouldBroadcastNow
Illuminate\Contracts\Bus\Dispatcher	Bus
Illuminate\Contracts\Bus\QueueingDispatcher	Bus::dispatchToQueue()
Illuminate\Contracts\Cache\Factory	Cache
Illuminate\Contracts\Cache\Lock
Illuminate\Contracts\Cache\LockProvider
Illuminate\Contracts\Cache\Repository	Cache::driver()
Illuminate\Contracts\Cache\Store
Illuminate\Contracts\Config\Repository	Config
Illuminate\Contracts\Console\Application
Illuminate\Contracts\Console\Kernel	Artisan
Illuminate\Contracts\Container\Container	App
Illuminate\Contracts\Cookie\Factory	Cookie
Illuminate\Contracts\Cookie\QueueingFactory	Cookie::queue()
Illuminate\Contracts\Database\ModelIdentifier
Illuminate\Contracts\Debug\ExceptionHandler
Illuminate\Contracts\Encryption\Encrypter	Crypt
Illuminate\Contracts\Events\Dispatcher	Event
Illuminate\Contracts\Filesystem\Cloud	Storage::cloud()
Illuminate\Contracts\Filesystem\Factory	Storage
Illuminate\Contracts\Filesystem\Filesystem	Storage::disk()
Illuminate\Contracts\Foundation\Application	App
Illuminate\Contracts\Hashing\Hasher	Hash
Illuminate\Contracts\Http\Kernel
Illuminate\Contracts\Mail\Mailable
Illuminate\Contracts\Mail\Mailer	Mail
Illuminate\Contracts\Mail\MailQueue	Mail::queue()
Illuminate\Contracts\Notifications\Dispatcher	Notification
Illuminate\Contracts\Notifications\Factory	Notification
Illuminate\Contracts\Pagination\LengthAwarePaginator
Illuminate\Contracts\Pagination\Paginator
Illuminate\Contracts\Pipeline\Hub
Illuminate\Contracts\Pipeline\Pipeline	Pipeline
Illuminate\Contracts\Queue\EntityResolver
Illuminate\Contracts\Queue\Factory	Queue
Illuminate\Contracts\Queue\Job
Illuminate\Contracts\Queue\Monitor	Queue
Illuminate\Contracts\Queue\Queue	Queue::connection()
Illuminate\Contracts\Queue\QueueableCollection
Illuminate\Contracts\Queue\QueueableEntity
Illuminate\Contracts\Queue\ShouldQueue
Illuminate\Contracts\Redis\Factory	Redis
Illuminate\Contracts\Routing\BindingRegistrar	Route
Illuminate\Contracts\Routing\Registrar	Route
Illuminate\Contracts\Routing\ResponseFactory	Response
Illuminate\Contracts\Routing\UrlGenerator	URL
Illuminate\Contracts\Routing\UrlRoutable
Illuminate\Contracts\Session\Session	Session::driver()
Illuminate\Contracts\Support\Arrayable
Illuminate\Contracts\Support\Htmlable
Illuminate\Contracts\Support\Jsonable
Illuminate\Contracts\Support\MessageBag
Illuminate\Contracts\Support\MessageProvider
Illuminate\Contracts\Support\Renderable
Illuminate\Contracts\Support\Responsable
Illuminate\Contracts\Translation\Loader
Illuminate\Contracts\Translation\Translator	Lang
Illuminate\Contracts\Validation\Factory	Validator
Illuminate\Contracts\Validation\ValidatesWhenResolved
Illuminate\Contracts\Validation\ValidationRule
Illuminate\Contracts\Validation\Validator	Validator::make()
Illuminate\Contracts\View\Engine
Illuminate\Contracts\View\Factory	View
Illuminate\Contracts\View\View	View::make()