Laravel 5.dev ファサード

イントロダクションIntroduction

ファサードはアプリケーションのIoCコンテナに用意したクラスに「静的」なインターフェイスを提供してくれます。Laravelは多くのファサードを使用していますが、多分皆さんはご存じないまま使用されていることでしょう！Laravelの「ファサード(facade)」は、IoCコンテナー下で動作しているクラスに対し、"static proxies"として動作しています。これにより伝統的な静的メソッドよりも、簡潔で、テストの行いやすさと柔軟性を保ちながらも、記述的な書き方が行えます。Facades provide a "static" interface to classes that are available in the application's IoC container[/docs/ioc]. Laravel ships with many facades, and you have probably been using them without even knowing it! Laravel "facades" serve as "static proxies" to underlying classes in the IoC container, providing the benefit of a terse, expressive syntax while maintaining more testability and flexibility than traditional static methods.

自分のアプリケーションやパッケージでも時々ファサードを作成したくなると思います。ですからコンセプトと、開発方法、クラスの使い方を説明していきます。Occasionally, You may wish to create your own facades for your applications and packages, so let's explore the concept, development and usage of these classes.

**注目：**ファサードを学び始める前に、LaravelのIocコンテナに親しんでおくことを強くおすすめします。Note: Before digging into facades, it is strongly recommended that you become very familiar with the Laravel IoC container[/docs/ioc].

解説Explanation

Laravelアプリケーションに関する文脈では、ファサードはコンテナを通じてオブジェクトにアクセス方法を提供するクラスのことです。Facadeクラス中のメカニズムでこれを行なっています。Laravelのファサードと皆さんが作成したカスタムファサードは、Facadeクラスを拡張します。In the context of a Laravel application, a facade is a class that provides access to an object from the container. The machinery that makes this work is in the Facade class. Laravel's facades, and any custom facades you create, will extend the base Facade class.

ファサードクラスで実装する必要があるのはgetFacadeAccessorだけです。getFacadeAccessorメソッドの役目はコンテナを通じたインスタンスの依存解決に何を使用するかを定義することです。Facade基本クラスは__callStatic()マジックメソッドを使用し、あなたのファサードからの呼び出しをインスタンス化を依存解決したオブジェクトへと届けます。Your facade class only needs to implement a single method: getFacadeAccessor. It's the getFacadeAccessor method's job to define what to resolve from the container. The Facade base class makes use of the __callStatic() magic-method to defer calls from your facade to the resolved object.

Cache::getのようにファサードの呼び出しが行われると、LaravelはIoCコンテナでCacheマネージャーを依存解決し、そのクラスのgetメソッドを呼び出します。技術的な言い方をすれば、Laravelのファサードは、サービスローケーターとしてのLaravelのIoCコンテナを使用した、使いやすい記法のことです。So, when you make a facade call like Cache::get, Laravel resolves the Cache manager class out of the IoC container and calls the get method on the class. In technical terms, Laravel Facades are a convenient syntax for using the Laravel IoC container as a service locator.

実際の使用Practical Usage

下の例では、Laravelのキャッシュシステムを呼び出しています。これを読むと、一見Cacheクラスのstaticなgetメソッドが呼び出されていのだと考えてしまうことでしょう。In the example below, a call is made to the Laravel cache system. By glancing at this code, one might assume that the static method get is being called on the Cache class.

$value = Cache::get('key');

ところが、Illuminate\Support\Facades\Cacheクラスを見てもらえば、staticのgetメソッドは存在していないことが分かります。However, if we look at that Illuminate\Support\Facades\Cache class, you'll see that there is no static method get:

class Cache extends Facade {

	/**
	 * コンポーネントの登録名を取得する
	 *
	 * @return string
	 */
	protected static function getFacadeAccessor() { return 'cache'; }

}

Cacheクラスは基本のFacadeクラスを拡張し、getFacadeAccessor()メソッドを定義しています。思い出してください。このメソッドの仕事はIoCで結合した名前をリターンすることでした。The Cache class extends the base Facade class and defines a method getFacadeAccessor(). Remember, this method's job is to return the name of an IoC binding.

ユーザーがCacheファサードのどのstaticメソッドを利用しようと、LaravelはIoCコンテナからcacheに結び付けられたインスタンスを依存解決し、要求されたメソッドを（この場合はgetです）そのオブジェクトに対し実行します。When a user references any static method on the Cache facade, Laravel resolves the cache binding from the IoC container and runs the requested method (in this case, get) against that object.

ですから、Cache::getの呼び出しは以下のように書き直すこともできます。So, our Cache::get call could be re-written like so:

$value = $app->make('cache')->get('key');

ファサードのインポートImporting Facades

コントローラーが名前空間下にあるときにファサードを利用するには、その名前空間へファサードクラスをインポートする必要があることを覚えておいてください。全てのファサードはグローバル名前空間にあります。Remember, if you are using a facade when a controller that is namespaced, you will need to import the facade class into the namespace. All facades live in the global namespace:

<?php namespace App\Http\Controllers;

use Cache;

class PhotosController extends Controller {

	/**
	 * 写真を全て取得する
	 *
	 * @return Response
	 */
	public function index()
	{
		$photos = Cache::get('photos');

		//
	}

}

ファサードの作成Creating Facades

ファサードを作成するとアプリケーションやパッケージをシンプルにすることができます。必要なのは３つだけです。Creating a facade for your own application or package is simple. You only need 3 things:

• IoCでのバインディングAn IoC binding.
• ファサードクラスA facade class.
• ファサードエイリアスの設定A facade alias configuration.

例を見てください。PaymentGateway\Paymentクラスを定義しています。Let's look at an example. Here, we have a class defined as PaymentGateway\Payment.

namespace PaymentGateway;

class Payment {

	public function process()
	{
		//
	}

}

このクラスをIoCコンテナで依存解決できるようにする必要があります。そのため、サービスプロバイダーに結合を追加しましょう。We need to be able to resolve this class from the IoC container. So, let's add a binding to a service provider:

App::bind('payment', function()
{
	return new \PaymentGateway\Payment;
});

この結合を設置する良い方法は、PaymentServiceProviderという名前の新しいサービスプロバイダーを追加し、registerメソッドへ追加することでしょう。次にconfig/app.php設定ファイルで、このサービスプロバイダーがロードされるように指定しましょう。A great place to register this binding would be to create a new service provider[/docs/ioc#service-providers] named PaymentServiceProvider, and add this binding to the register method. You can then configure Laravel to load your service provider from the config/app.php configuration file.

次に、ファサードクラスを作成しましょう。Next, we can create our own facade class:

use Illuminate\Support\Facades\Facade;

class Payment extends Facade {

	protected static function getFacadeAccessor() { return 'payment'; }

}

最後にお望みであれば、config/app.php設定ファイルのaliases配列に、このファサードのエイリアスを付け加えることもできます。これで、Paymentクラスインスタンスのprocessメソッドを呼び出すことができるようになりました。Finally, if we wish, we can add an alias for our facade to the aliases array in the config/app.php configuration file. Now, we can call the process method on an instance of the Payment class.

Payment::process();

オートローディングエイリアスの注意点A Note On Auto-Loading Aliases

PHPが未定義のタイプヒントをオートロードしないため、aliases配列にインスタンスが指定できない場合があります。もし、＼ServiceWrapper＼ApiTimeoutExceptionをApiTimeoutExceptionというエイリアス名で定義し、＼ServiceWrapper外の名前空間でcatch(ApiTimeoutException $e)しても、投げられたその例外は捕捉されません。似たような問題は、エイリアスされたクラスへのタイプヒントを持つモデルでも、見かけられます。唯一の依存解決法は、そのようなエイリアスの参照に先立ち、それぞれのファイルの先頭で、必要なタイプヒントをuseで指定しておく方法しかありません。Classes in the aliases array are not available in some instances because PHP will not attempt to autoload undefined type-hinted classes[https://bugs.php.net/bug.php?id=39003]. If \ServiceWrapper\ApiTimeoutException is aliased to ApiTimeoutException, a catch(ApiTimeoutException $e) outside of the namespace \ServiceWrapper will never catch the exception, even if one is thrown. A similar problem is found in classes which have type hints to aliased classes. The only workaround is to forego aliasing and use the classes you wish to type hint at the top of each file which requires them.

ファサードのモックMocking Facades

ファサードがどうしてこのように動作するのか、その理由の重要な一面がユニットテストです。実際、ファサードが存在している一番大きな理由がテストの行いやすさです。詳細はドキュメントのファサードのモックの章をご覧ください。Unit testing is an important aspect of why facades work the way that they do. In fact, testability is the primary reason for facades to even exist. For more information, check out the mocking facades[/docs/testing#mocking-facades] section of the documentation.

ファサードクラス一覧Facade Class Reference

以下は全ファサードと、実際のクラスの一覧です。これは特定のファサードを元にし、APIドキュメントを素早く探したい場合に便利な道具になります。IoC結合キーも含んでいますので、応用して下さい。Below you will find every facade and its underlying class. This is a useful tool for quickly digging into the API documentation for a given facade root. The IoC binding[/docs/ioc] key is also included where applicable.