Laravel 11.x 契約

イントロダクションIntroduction

Laravelの「契約」は、フレームワークが提供するコアサービスを定義する一連のインターフェイスです。たとえば、Illuminate\Contracts\Queue\Queue契約は、ジョブのキューイングに必要なメソッドを定義し、Illuminate\Contracts\Mail\Mailer契約は、メールの送信に必要なメソッドを定義します。Laravel's "contracts" are a set of interfaces that define the core services provided by the framework. For example, an Illuminate\Contracts\Queue\Queue contract defines the methods needed for queueing jobs, while the Illuminate\Contracts\Mail\Mailer contract defines the methods needed for sending e-mail.

各契約にはフレームワークが提供している、対応する実装があります。例えば、Laravelは様々なドライバを持つキューの実装と、Symfony Mailerが提供しているメーラーの実装を提供しています。Each contract has a corresponding implementation provided by the framework. For example, Laravel provides a queue implementation with a variety of drivers, and a mailer implementation that is powered by Symfony Mailer[https://symfony.com/doc/7.0/mailer.html].

すべてのLaravel契約は、独自のGitHubリポジトリにあります。これは、利用可能なすべての契約のクイックリファレンスポイントと、Laravelサービスと相互関係するパッケージを構築するときに利用できる単一の分離されたパッケージを提供しています。All of the Laravel contracts live in their own GitHub repository[https://github.com/illuminate/contracts]. This provides a quick reference point for all available contracts, as well as a single, decoupled package that may be utilized when building packages that interact with Laravel services.

契約対ファサードContracts vs. Facades

Laravelのファサードとヘルパ関数は、サービスコンテナで契約をタイプヒントして依存解決する必要なしに、Laravelのサービスを利用する簡単な方法を提供します。ほとんどの場合、各ファサードには同等の契約があります。Laravel's facades[/docs/{{version}}/facades] and helper functions provide a simple way of utilizing Laravel's services without needing to type-hint and resolve contracts out of the service container. In most cases, each facade has an equivalent contract.

ファサードとは異なり、契約はクラスのコンストラクターでタイプヒントによる依存解決が必要なため、契約を使用すると、クラスの明示的な依存関係を定義できます。一部の開発者は、この方法で依存関係を明示的に定義することを好み、したがって契約を使用することを好みますが、他の開発者はファサードの便利さを楽しんでいます。一般に、ほとんどのアプリケーションは開発中に問題なくファサードを使用できます。Unlike facades, which do not require you to require them in your class' constructor, contracts allow you to define explicit dependencies for your classes. Some developers prefer to explicitly define their dependencies in this way and therefore prefer to use contracts, while other developers enjoy the convenience of facades. In general, most applications can use facades without issue during development.

契約を使うときWhen to Use Contracts

契約またはファサードを使用するかどうかの決定は、個人的な好みと開発チームの好みに依存します。契約とファサードの両方を使用して、堅牢で十分にテストされたLaravelアプリケーションを作成できます。契約とファサードは相互に排他的ではありません。アプリケーションの一部はファサードを使用し、他の部分は契約に依存できます。クラスの責任を集中させている限り、契約とファサードの使用の実際的な違いはほとんどありません。The decision to use contracts or facades will come down to personal taste and the tastes of your development team. Both contracts and facades can be used to create robust, well-tested Laravel applications. Contracts and facades are not mutually exclusive. Some parts of your applications may use facades while others depend on contracts. As long as you are keeping your class' responsibilities focused, you will notice very few practical differences between using contracts and facades.

一般に、ほとんどのアプリケーションは、開発中に問題なくファサードを使用できます。複数のPHPフレームワークと統合するパッケージを構築している場合は、パッケージのcomposer.jsonファイルにLaravelの具体的な実装をリクエストすることなく、illuminate/contractsパッケージを使用してLaravelのサービスとの統合を定義することをお勧めします。In general, most applications can use facades without issue during development. If you are building a package that integrates with multiple PHP frameworks you may wish to use the illuminate/contracts package to define your integration with Laravel's services without the need to require Laravel's concrete implementations in your package's composer.json file.

契約の使用法How to Use Contracts

では、どのようにして契約を実装するのでしょう？本当にとても簡単です。So, how do you get an implementation of a contract? It's actually quite simple.

Laravelの多種のクラスは、サービスコンテナを介して解決されます。これには、コントローラ、イベントリスナ、ミドルウェア、キュー投入するジョブ、さらにルートクロージャまでも含みます。したがって、契約の実装を取得するには、解決されるクラスのコンストラクターでインターフェイスを「タイプヒント」するだけです。Many types of classes in Laravel are resolved through the service container[/docs/{{version}}/container], including controllers, event listeners, middleware, queued jobs, and even route closures. So, to get an implementation of a contract, you can just "type-hint" the interface in the constructor of the class being resolved.

たとえば、以下のイベントリスナを見てください。For example, take a look at this event listener:

<?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
    {
        // ...
    }
}

このイベントリスナが依存解決されるとき、サービスコンテナはクラスコンストラクタのタイプヒントを読み取り、適切な値を依存注入します。サービスコンテナへの登録の詳細は、ドキュメントをご覧ください。When the event listener is resolved, the service container will read the type-hints on the constructor of the class, and inject the appropriate value. To learn more about registering things in the service container, check out its documentation[/docs/{{version}}/container].

契約リファレンスContract Reference

この一覧表は、すべてのLaravel契約とそれに該当するファサードのクイックリファレンスです。This table provides a quick reference to all of the Laravel contracts and their equivalent facades: