コントラクト

Laravel の「コントラクト」は、フレームワークが持つ主な機能の約束事を決めた、インターフェース（クラスが守る約束事）の集まりです。たとえば、Illuminate\Contracts\Queue\Queue は、ジョブ（時間のかかる仕事）をキューに入れるために必要なメソッドを決めています。Illuminate\Contracts\Mail\Mailer は、メールを送るために必要なメソッドを決めています。

それぞれのコントラクトには、フレームワークが用意した、実際に動くクラス（実装）があります。たとえば、いろいろなドライバー（使う方式）に対応したキューの実装や、Symfony Mailer で動くメールの実装があります。

Laravel のコントラクトは、すべて、専用の GitHub のリポジトリ（illuminate/contracts）にまとまっています。使えるコントラクトを手早く調べたいときは、ここを見ます。また、このリポジトリは、それだけで使える1つのパッケージにもなっています。Laravel の機能とやり取りするパッケージを作るときに使えます。

コントラクトとファサードの違い#

ファサード（Route::get() のようにクラス名と :: で機能を呼べる窓口）やヘルパー関数を使えば、コントラクトの型を書いてサービスコンテナから取り出さなくても、Laravel の機能を使えます。たいていのファサードには、対応するコントラクトがあります。

ファサードは、クラスのコンストラクタに書かなくても使えます。それに対して、コントラクトを使うと、「このクラスは何の道具を使うか」をはっきり書けます。はっきり書くのが好きな人はコントラクトを、手軽さが好きな人はファサードを選びます。たいていのアプリは、開発のあいだずっとファサードを使っても困りません。

コントラクトを使うとき#

どちらを使うかは、自分とチームの好みで決めます。どちらでも、しっかりしたアプリを作れます。両方を混ぜてもかまいません。クラスの役目を絞ってあれば、どちらを使っても違いはほとんど出ません。

いくつもの PHP のフレームワークで使うパッケージを作るなら、illuminate/contracts パッケージが役に立ちます。Laravel の機能とのつなぎ方を、インターフェースだけで決められるからです。パッケージの composer.json に、Laravel の実装（中身のあるクラス）を入れなくて済みます。

コントラクトの使い方#

では、コントラクトの実装は、どうやって手に入れるのでしょうか。じつは、とても簡単です。

Laravel では、いろいろな種類のクラスがサービスコンテナを通して作られます。コントローラー・イベントのリスナー・ミドルウェア・キューのジョブ、ルートのクロージャ（名前のない関数）まで、そうです。だから、コントラクトの実装がほしいときは、そのクラスのコンストラクタに、インターフェースの型を書くだけで済みます。

たとえば、次のイベントのリスナーを見てください。

<?php

namespace App\Listeners;

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

class CacheOrderInformation
{
    /**
     * Create the event listener.
     */
    public function __construct(
        protected Factory $redis,
    ) {}

    /**
     * Handle the event.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}

リスナーが作られるとき、サービスコンテナは、コンストラクタに書かれた型を読み取って、ふさわしい値を渡します。サービスコンテナへの登録のしかたは、サービスコンテナのページにあります。

コントラクトの一覧#

次の表は、Laravel のコントラクトと、同じ役目のファサードの対応です。コントラクトの名前は、Illuminate\Contracts\ より後ろの部分だけを書いています。たとえば Auth\Guard は Illuminate\Contracts\Auth\Guard です。ファサードが「なし」のものは、対応するファサードがありません。

関連するページ#

• ファサード
• サービスコンテナ
• サービスプロバイダ