계약(Contracts)
업데이트됨번역일: 2026년 6월 20일
이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.
- 원문 수정
- 2026년 6월 20일
- 번역 갱신
- 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의 파사드(Facades)와 헬퍼 함수는 서비스 컨테이너에서 직접 의존성을 해결하거나 타입 힌트를 작성하지 않아도 Laravel 서비스를 간편하게 사용할 수 있게 해줍니다. 대부분의 Facade에는 동등한 Contract가 존재합니다.
Facade와 Contract의 가장 큰 차이는 의존성을 명시하는 방식입니다. Facade는 클래스 생성자에 별도로 선언하지 않아도 사용할 수 있지만, Contract를 사용하면 클래스가 어떤 의존성을 필요로 하는지 생성자에 명확하게 드러납니다. 의존성을 명시적으로 관리하는 것을 선호하는 개발자는 Contract를, 편의성을 중시하는 개발자는 Facade를 선택하는 경향이 있습니다. 일반적인 애플리케이션 개발에서는 Facade를 사용해도 아무런 문제가 없습니다.
언제 Contracts를 사용할까
Contracts와 Facade 중 무엇을 선택할지는 팀의 성향과 개인 취향에 달려 있습니다. 두 방식 모두 견고하고 테스트하기 좋은 Laravel 애플리케이션을 만드는 데 충분합니다. 또한 둘은 상호 배타적이지 않습니다. 한 애플리케이션 안에서 어떤 부분은 Facade를, 다른 부분은 Contract를 사용해도 됩니다. 클래스의 책임 범위를 명확하게 유지한다면 실질적인 차이는 크지 않습니다.
다만, 여러 PHP 프레임워크와 연동하는 패키지를 개발하는 경우에는 Contract 사용을 권장합니다. illuminate/contracts 패키지만 composer.json에 추가하면 Laravel의 구체적인 구현체에 의존하지 않고도 Laravel 서비스와의 연동 인터페이스를 정의할 수 있습니다.
Contracts 사용 방법
Contract의 구현체는 어떻게 얻을까요? 방법은 매우 간단합니다.
Laravel에서는 컨트롤러, 이벤트 리스너, 미들웨어, 큐 Job, 라우트 클로저 등 다양한 클래스가 서비스 컨테이너를 통해 resolve됩니다. 따라서 Contract의 구현체를 얻으려면, resolve되는 클래스의 생성자에 해당 인터페이스를 타입 힌트로 선언하기만 하면 됩니다.
아래 이벤트 리스너 예시를 살펴보세요:
<?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
{
// ...
}
}이 리스너가 resolve될 때, 서비스 컨테이너는 생성자의 타입 힌트를 읽고 적절한 구현체를 자동으로 주입합니다. 서비스 컨테이너에 바인딩을 등록하는 방법은 서비스 컨테이너 문서를 참고하세요.
Contract 레퍼런스
아래 표는 Laravel의 모든 Contract와 그에 대응하는 Facade를 빠르게 참조할 수 있도록 정리한 목록입니다.