계약(Contracts)
번역일: 2026년 6월 20일
계약(Contracts)
소개
Laravel의 "Contracts"는 프레임워크가 제공하는 핵심 서비스들을 정의한 인터페이스 모음입니다. 예를 들어 Illuminate\Contracts\Queue\Queue는 Job을 큐에 넣을 때 필요한 메서드를, Illuminate\Contracts\Mail\Mailer는 이메일을 전송할 때 필요한 메서드를 정의합니다.
각 Contract에는 프레임워크가 제공하는 구체적인 구현체가 대응됩니다. 예를 들어 Laravel은 다양한 드라이버를 지원하는 큐 구현체와, Symfony Mailer 기반의 메일 구현체를 제공합니다.
Laravel의 모든 Contract는 별도의 GitHub 저장소에서 관리됩니다. 사용 가능한 Contract 목록을 한눈에 확인할 수 있으며, Laravel 서비스와 연동하는 패키지를 만들 때 독립적인 패키지로 활용하기에도 좋습니다.
Contracts vs. Facades
Laravel의 Facades와 헬퍼 함수는 서비스 컨테이너에서 Contract를 직접 꺼내거나 타입 힌트를 작성하지 않아도 Laravel 서비스를 간편하게 사용할 수 있게 해줍니다. 대부분의 Facade에는 대응하는 Contract가 존재합니다.
Facade는 클래스 생성자에 별도로 주입하지 않아도 바로 사용할 수 있는 반면, Contract를 사용하면 클래스가 의존하는 대상을 생성자에 명시적으로 선언하게 됩니다. 명시적인 의존성 선언을 선호하는 개발자는 Contract를, 편의성을 중시하는 개발자는 Facade를 선호하는 경향이 있습니다. 일반적인 애플리케이션 개발에서는 Facade를 사용해도 전혀 문제 없습니다.
언제 Contracts를 사용할까
Contracts와 Facades 중 어떤 것을 쓸지는 결국 개인 또는 팀의 취향에 달려 있습니다. 둘 다 견고하고 테스트하기 좋은 Laravel 애플리케이션을 만드는 데 충분히 활용할 수 있으며, 상호 배타적이지도 않습니다. 한 프로젝트 안에서 일부는 Facade를, 다른 부분은 Contract를 사용하는 것도 자연스럽습니다. 클래스의 역할이 잘 분리되어 있다면 어느 쪽을 쓰든 실질적인 차이는 크지 않습니다.
다만 여러 PHP 프레임워크와 함께 동작하는 패키지를 개발할 때는 Contract 사용을 적극 고려해볼 만합니다. illuminate/contracts 패키지를 이용하면 Laravel의 구체적인 구현체를 composer.json에 포함시키지 않고도 Laravel 서비스와의 연동 인터페이스를 정의할 수 있습니다.
Contracts 사용 방법
Contract의 구현체를 얻는 방법은 매우 간단합니다.
Laravel에서는 컨트롤러, 이벤트 리스너, 미들웨어, 큐 Job, 라우트 클로저 등 다양한 클래스가 서비스 컨테이너를 통해 생성됩니다. 따라서 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
{
// ...
}
}이 리스너가 생성될 때 서비스 컨테이너가 생성자의 타입 힌트를 확인하고, Illuminate\Contracts\Redis\Factory에 바인딩된 구현체를 자동으로 주입합니다. 서비스 컨테이너에 바인딩을 등록하는 방법은 서비스 컨테이너 문서를 참고하세요.
Contract 레퍼런스
아래 표는 Laravel의 모든 Contract와 대응하는 Facade를 정리한 것입니다.