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