Laravel 5.1 契約

イントロダクション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, a 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は多様なドライバーと共に、キューの実装を提供しており、メーラーの実装は、SwiftMailerです。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 SwiftMailer[http://swiftmailer.org/].

Laravelの全契約はGitHubのリポジトリーで参照できます。これは全契約を素早く参照する方法であり、同時にパッケージ開発者は個別に独立したパッケージを利用する際、参考にできるでしょう。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 by package developers.

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

Laravelのファサードはサービスコンテナをタイプヒントや契約の解決を必要とせず、Laravelのサービスを簡単に使用してもらう手段を提供しています。しかし、契約を使うことでクラスの依存を明確に定義することができます。ほとんどのアプリケーションではファサードの使用は問題になりません。でももし、とても緩い結合が本当に必要であれば契約が役に立ちます。続けて読み進めてください！Laravel's facades[/docs/{{version}}/facades] provide a simple way of utilizing Laravel's services without needing to type-hint and resolve contracts out of the service container. However, using contracts allows you to define explicit dependencies for your classes. For most applications, using a facade is just fine. However, if you really need the extra loose coupling that contracts can provide, keep reading!

なぜ契約？Why Contracts?

契約については皆さん多くの質問をお持ちでしょう。なんでインターフェイスを使うんだ？　インターフェイスを使えばもっと複雑になるんじゃないか？　インターフェイスを利用する理由を突き詰めれば次の２つになります。緩い結合と単純さです。You may have several questions regarding contracts. Why use interfaces at all? Isn't using interfaces more complicated? Let's distil the reasons for using interfaces to the following headings: loose coupling and simplicity.

緩い結合Loose Coupling

最初にキャッシュの実装とがっちり結合したコードをレビューしてみましょう。次のコードをご覧ください。First, let's review some code that is tightly coupled to a cache implementation. Consider the following:

<?php

namespace App\Orders;

class Repository
{
    /**
     * キャッシュインスタンス
     */
    protected $cache;

    /**
     * 新しいインスタンスの生成
     *
     * @param  \SomePackage\Cache\Memcached  $cache
     * @return void
     */
    public function __construct(\SomePackage\Cache\Memcached $cache)
    {
        $this->cache = $cache;
    }

    /**
     * IDにより注文を取得
     *
     * @param  int  $id
     * @return Order
     */
    public function find($id)
    {
        if ($this->cache->has($id))    {
            //
        }
    }
}

このクラスにおけるコードは使用しているキャッシュの実装ときつく結合しています。つまりパッケージベンダーの具象キャッシュクラスに依存しているために、結合が強くなっています。パッケージのAPIが変更されたら、同時にこのコードも変更しなくてはなりません。In this class, the code is tightly coupled to a given cache implementation. It is tightly coupled because we are depending on a concrete Cache class from a package vendor. If the API of that package changes our code must change as well.

キャッシュの裏で動作している技術(Memcached)を別のもの(Redis)へ置き換えたくなれば、リポジトリーを修正する必要があるというのは起こり得ます。リポジトリーは誰がデータを提供しているかとか、どのように提供しているかという知識を沢山持っていてはいけません。Likewise, if we want to replace our underlying cache technology (Memcached) with another technology (Redis), we again will have to modify our repository. Our repository should not have so much knowledge regarding who is providing them data or how they are providing it.

このようなアプローチを取る代わりに、ベンダーと関連がないシンプルなインターフェイスへ依存するコードにより向上できます。Instead of this approach, we can improve our code by depending on a simple, vendor agnostic interface:

<?php

namespace App\Orders;

use Illuminate\Contracts\Cache\Repository as Cache;

class Repository
{
    /**
     * キャッシュインスタンス
     */
    protected $cache;

    /**
     * 新しいリポジトリーインスタンスの生成
     *
     * @param  Cache  $cache
     * @return void
     */
    public function __construct(Cache $cache)
    {
        $this->cache = $cache;
    }
}

これでコードは特定のベンダー、しかもLaravelにさえ依存しなくなりました。契約パッケージは実装も依存も含んでいないため、与えられた契約の異なった実装を簡単に記述できます。キャッシュを使用するコードを変更することなく、キャッシュ実装を置き換えることができるようになりました。Now the code is not coupled to any specific vendor, or even Laravel. Since the contracts package contains no implementation and no dependencies, you may easily write an alternative implementation of any given contract, allowing you to replace your cache implementation without modifying any of your cache consuming code.

単純さSimplicity

Laravelのサービスは全てシンプルなインターフェイスの中で適切に定義されているので、サービスが提供する機能も簡単に定義できています。 契約はフレームワークの機能の簡単なドキュメントとして使えます。When all of Laravel's services are neatly defined within simple interfaces, it is very easy to determine the functionality offered by a given service. The contracts serve as succinct documentation to the framework's features.

それに加え、シンプルなインターフェイスに基づけばあなたのコードは簡単に理解でき、メンテナンスできるようにもなります。大きくて複雑なクラスの中でどのメソッドが使用可能かを探し求めるよりも、シンプルでクリーンなインターフェイスを参照できます。In addition, when you depend on simple interfaces, your code is easier to understand and maintain. Rather than tracking down which methods are available to you within a large, complicated class, you can refer to a simple, clean interface.

契約リファレンスContract Reference

Laravelのほぼ全ての契約と、Laravelファサードとの比較一覧です。This is a reference to most Laravel Contracts, as well as their Laravel "facade" counterparts:

契約使用法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\User;
use App\Events\NewUserRegistered;
use Illuminate\Contracts\Redis\Database;

class CacheUserInformation
{
    /**
     * Redisデータベース実装
     */
    protected $redis;

    /**
     * 新しいイベンハンドラーインスタンスの生成
     *
     * @param  Database  $redis
     * @return void
     */
    public function __construct(Database $redis)
    {
        $this->redis = $redis;
    }

    /**
     * イベント処理
     *
     * @param  NewUserRegistered  $event
     * @return void
     */
    public function handle(NewUserRegistered $event)
    {
        //
    }
}

イベントリスナーの依存解決時に、サービスコンテナはクラスのコンストラクターで指定されているタイプヒントを読み取り、適切な値を注入します。サービスコンテナへ何かを登録する方法を学ぶには、ドキュメントを参照してください。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].