Contracts

Introduction

Laravel の contracts は、フレームワークによって提供されるコアの services を定義する一連のインターフェースです。 例えば、Illuminate\Contracts\Queue\Queue コントラクトは、 jobs をキューイングするために必要なメソッドを定義します。一方、Illuminate\Contracts\Mail\Mailer コントラクトは、E メールを送信するために必要なメソッドを定義します。

各契約には、フレームワークが提供する対応する実装があります。例えば、 Laravel は、さまざまなドライバーを備えた queue 実装と、Symfony Mailer によって提供される mailer 実装を提供します。

すべての Laravel contracts は、それ自体が GitHub リポジトリ に存在します。これにより、利用可能なすべての contracts に対する迅速な参照ポイントが提供されるとともに、 Laravel services と対話するパッケージを作成する際に利用できる single 、デカップリングされたパッケージが提供されます。

Contracts 対 Facades

Laravel のfacadesとヘルパー関数は、型ヒントを指定したり、 service container から contracts を解決することなく、Laravel の services を利用する簡単な方法を提供します。ほとんどの場合、各 facade には同等の契約があります。

クラスのコンストラクタでそれらを要求する必要がない facades とは異なり、 contracts ではクラスの明示的な依存関係を定義できます。一部の開発者はこのように依存関係を明示的に定義することを好み、したがって contracts を使用することを好む一方、他の開発者は facades の便利さを楽しんでいます。 一般的に、ほとんどのアプリケーションは開発中に問題なく facades を使用できます。

When to Use Contracts

Contracts または facades を使用するか否かは、あなた自身の好みや開発チームの嗜好に左右されます。 contracts と facades のどちらも、堅牢で、良くテストされた Laravel アプリケーションを作成するために使用することができます。 contracts と facades は排他的なものではありません。あなたのアプリケーションの一部は facades を使用し、他の部分は contracts に依存するかもしれません。あなたがあなたのクラスの役割を集中して保つ限り、 contracts と facades を使用する間に実際的な違いはほとんど気付かないでしょう。

一般的に、ほとんどのアプリケーションは開発中に facades を問題なく使用できます。複数の PHP フレームワークと統合するパッケージを構築している場合、illuminate/contractsパッケージを使用して、パッケージのcomposer.jsonファイルに Laravel の具体的な実装を必要とせずに、Laravel の services との統合を定義することをお勧めします。

How to Use Contracts

では、契約の実装をどのように取得しますか？実はとても簡単です。

Laravel には様々な種類のクラスが存在し、それらはservice containerを通じて解決されます。これにはコントローラー、 event listeners ， middleware ，キューに追加された jobs 、さらには route closures が含まれます。したがって、契約の実装を取得するためには、解決される class のコンストラクタでインターフェイスに対して"type-hint"するだけで済みます。

例えば、この event リスナーを見てみましょう：

<?php

namespace App\Listeners;

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

class CacheOrderInformation
{
    /**
     * Create a new event handler instance.
     */
    public function __construct(
        protected Factory $redis,
    ) {}

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

event リスナーが解決されると、 service container は class のコンストラクタに対するタイプヒントを読み込み、適切な value を注入します。 service container に登録する方法について詳しく知りたい場合は、そのドキュメンテーションをご覧ください。

Contract Reference

このテーブルは、すべての Laravel contracts とそれに対応する facades を迅速に参照するためのものです：