ファサード

Laravel のドキュメントには、Route::get() や Cache::get() のように、クラス名と :: で機能を呼ぶコードがたくさん出てきます。これが「ファサード」です。ファサードは、アプリのサービスコンテナ（クラスを作って渡してくれる、道具箱のようなしくみ）にある道具を使うための窓口です。インスタンスを作らずに、クラス名と :: で呼ぶ形（静的な形）で使えます。Laravel にはたくさんのファサードがあり、ほとんどの機能をこの形で呼べます。

ファサードは、サービスコンテナの中のクラスの「静的な代理（プロキシ）」として働きます。短くて読みやすい書き方で呼べます。しかも、ふつうの静的メソッドよりテストしやすく、融通もききます。しくみが全部分からなくても、気にせず先へ進んで大丈夫です。

Laravel のファサードは、すべて Illuminate\Support\Facades という名前空間（クラスの名前の住所）にあります。次のように使います。

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Route;

Route::get('/cache', function () {
    return Cache::get('key');
});

Laravel のドキュメントの例は、ファサードを使って機能を見せているものが多くあります。

ヘルパー関数#

ファサードを補うために、Laravel には、どこからでも呼べる「ヘルパー関数」がたくさんあります。Laravel のよく使う機能を、さらに手軽に呼べます。よく使うのは、view・response・url・config などです。各ヘルパー関数は、対応する機能のページで説明していますが、一覧はヘルパー関数のページにあります。

たとえば、JSON のレスポンスを作るのに、Illuminate\Support\Facades\Response ファサードの代わりに、response 関数が使えます。ヘルパー関数はどこからでも呼べるので、クラスを読みこむ（use する）必要はありません。

use Illuminate\Support\Facades\Response;

Route::get('/users', function () {
    return Response::json([
        // ...
    ]);
});

Route::get('/users', function () {
    return response()->json([
        // ...
    ]);
});

ファサードを使うとき#

ファサードには、たくさんのよい点があります。短くて覚えやすい書き方で、長いクラス名を覚えたり、自分で渡したり設定したりしなくても、Laravel の機能を使えます。また、PHP の動的なメソッド（呼ばれたメソッドの名前を、あとから受け取って処理するしくみ）を使っているおかげで、テストもしやすくなっています。

ただし、気をつけたいこともあります。ファサードは手軽で、外から渡してもらう（注入する）必要もないので、1つのクラスでたくさんのファサードを使ううちに、クラスがどんどん大きくなりがちです。依存性の注入なら、渡すものが増えるとコンストラクタ（クラスを作るときに動くメソッド）の引数が長くなるので、「大きくなりすぎた」と目で気づけます。ファサードではその手がかりが無いぶん、自分で気をつける必要があります。

ファサードを使うときは、クラスの大きさに気をつけて、役目を狭く保ってください。大きくなりすぎたら、小さなクラスに分けることを考えましょう。

ファサードと依存性の注入#

依存性の注入のいちばんの利点は、渡すクラスの実装を入れ替えられることです。テストのとき、モック（本物の代わりに置く、にせものの部品）やスタブ（決まった値を返すだけの部品）を渡して、そのメソッドが呼ばれたかを確かめられるので、便利です。

本当の静的メソッドは、ふつう、モックにもスタブにもできません。ところが、ファサードは中で動的なメソッドを使い、呼び出しを、サービスコンテナから取り出したオブジェクトへ渡しています。そのため、注入で受け取ったインスタンスと同じように、ファサードもテストできます。たとえば、次のルートがあるとします。

use Illuminate\Support\Facades\Cache;

Route::get('/cache', function () {
    return Cache::get('key');
});

Laravel のファサードのテスト用のメソッドを使うと、Cache::get が、期待した引数で呼ばれたかを、次のテストで確かめられます。

Pest の場合です。

use Illuminate\Support\Facades\Cache;

test('basic example', function () {
    Cache::shouldReceive('get')
        ->with('key')
        ->andReturn('value');

    $response = $this->get('/cache');

    $response->assertSee('value');
});

PHPUnit の場合です。

use Illuminate\Support\Facades\Cache;

/**
 * A basic functional test example.
 */
public function test_basic_example(): void
{
    Cache::shouldReceive('get')
        ->with('key')
        ->andReturn('value');

    $response = $this->get('/cache');

    $response->assertSee('value');
}

ファサードとヘルパー関数#

ファサードのほかに、Laravel には、ビューを作る・イベントを出す・ジョブ（時間のかかる仕事）を出す・HTTP のレスポンスを送るなど、よくある仕事をする「ヘルパー」関数がたくさんあります。その多くは、対応するファサードと、同じ働きをします。たとえば、次のファサードの呼び出しとヘルパーの呼び出しは、同じです。

return Illuminate\Support\Facades\View::make('profile');

return view('profile');

ファサードとヘルパー関数のあいだに、実際の違いはまったくありません。ヘルパー関数を使っても、対応するファサードとまったく同じようにテストできます。たとえば、次のルートがあるとします。

Route::get('/cache', function () {
    return cache('key');
});

cache ヘルパーは、Cache ファサードの元のクラスの get メソッドを呼びます。つまり、ヘルパー関数を使っていても、期待した引数でメソッドが呼ばれたかを、次のテストで確かめられます。

use Illuminate\Support\Facades\Cache;

/**
 * A basic functional test example.
 */
public function test_basic_example(): void
{
    Cache::shouldReceive('get')
        ->with('key')
        ->andReturn('value');

    $response = $this->get('/cache');

    $response->assertSee('value');
}

ファサードのしくみ#

Laravel のアプリでは、ファサードは、コンテナの中のオブジェクトに触れるための窓口になるクラスです。そのしくみは、Facade クラスの中にあります。Laravel のファサードも、自分で作るファサードも、基本の Illuminate\Support\Facades\Facade クラスを受け継ぎます。

基本の Facade クラスは、__callStatic() という PHP の特別なメソッド（マジックメソッド）を使って、ファサードへの呼び出しを、コンテナから取り出したオブジェクトに渡します。次の例では、Laravel のキャッシュを呼んでいます。コードを見ると、Cache クラスの静的な get メソッドを呼んでいるように見えます。

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Cache;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * Show the profile for the given user.
     */
    public function showProfile(string $id): View
    {
        $user = Cache::get('user:'.$id);

        return view('profile', ['user' => $user]);
    }
}

ファイルの上のほうで、Cache ファサードを「読みこんで」います。このファサードは、Illuminate\Contracts\Cache\Factory インターフェースの実装に届くための、代理です。ファサードを通した呼び出しは、すべて、Laravel のキャッシュのサービスのインスタンスに渡されます。

Illuminate\Support\Facades\Cache クラスを見ると、静的な get メソッドはありません。

class Cache extends Facade
{
    /**
     * Get the registered name of the component.
     */
    protected static function getFacadeAccessor(): string
    {
        return 'cache';
    }
}

代わりに、Cache ファサードは、基本の Facade クラスを受け継いで、getFacadeAccessor() メソッドを持っています。このメソッドの役目は、サービスコンテナに登録したときの名前を返すことです。Cache ファサードの静的メソッドが呼ばれると、Laravel は、サービスコンテナから cache という名前で登録したオブジェクトを取り出します。そして、そのオブジェクトの、呼ばれたメソッド（この例では get）を動かします。

リアルタイムファサード#

リアルタイムファサードを使うと、アプリのどのクラスでも、ファサードのように使えます。使い方を見るために、まず、リアルタイムファサードを使わないコードを見ます。Podcast モデルに publish メソッドがあり、ポッドキャストを公開するのに、Publisher のインスタンスを渡す必要があるとします。

<?php

namespace App\Models;

use App\Contracts\Publisher;
use Illuminate\Database\Eloquent\Model;

class Podcast extends Model
{
    /**
     * Publish the podcast.
     */
    public function publish(Publisher $publisher): void
    {
        $this->update(['publishing' => now()]);

        $publisher->publish($this);
    }
}

このように公開の係（Publisher）を引数で渡すと、テストのときに、それをモックに入れかえられます。メソッドだけを切り離してテストしやすくなります。ただ、publish を呼ぶたびに、公開の係を渡さなければなりません。リアルタイムファサードなら、テストのしやすさはそのままで、Publisher のインスタンスを自分で渡さなくて済みます。リアルタイムファサードにするには、use で読みこむクラスの名前空間の前に Facades を付けます。

<?php

namespace App\Models;

use Facades\App\Contracts\Publisher;
use Illuminate\Database\Eloquent\Model;

class Podcast extends Model
{
    /**
     * Publish the podcast.
     */
    public function publish(): void
    {
        $this->update(['publishing' => now()]);

        Publisher::publish($this);
    }
}

元のコードは、use App\Contracts\Publisher; と、引数つきの publish(Publisher $publisher)、$publisher->publish($this); でした。リアルタイムファサードでは、それぞれ、上のように変わります。

リアルタイムファサードを使うと、公開の係は、Facades の後ろに書いたインターフェースかクラスの名前で、サービスコンテナから取り出されます。テストのときは、Laravel に入っているファサードのテスト用のヘルパーで、このメソッドの呼び出しをモックにできます。

Pest の場合です。

<?php

use App\Models\Podcast;
use Facades\App\Contracts\Publisher;
use Illuminate\Foundation\Testing\RefreshDatabase;

pest()->use(RefreshDatabase::class);

test('podcast can be published', function () {
    $podcast = Podcast::factory()->create();

    Publisher::shouldReceive('publish')->once()->with($podcast);

    $podcast->publish();
});

PHPUnit の場合です。

<?php

namespace Tests\Feature;

use App\Models\Podcast;
use Facades\App\Contracts\Publisher;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class PodcastTest extends TestCase
{
    use RefreshDatabase;

    /**
     * A test example.
     */
    public function test_podcast_can_be_published(): void
    {
        $podcast = Podcast::factory()->create();

        Publisher::shouldReceive('publish')->once()->with($podcast);

        $podcast->publish();
    }
}

ファサードの一覧#

次の表は、すべてのファサードと、その元になるクラスの対応です。ファサードの元のクラスを、くわしい説明（API のドキュメント）にすばやくたどるのに役立ちます。サービスコンテナに登録した名前（キー）があるものは、それも書いています。「（インスタンス）」と付いた行は、ファサードの元のクラスそのものではなく、そこから作られる1つ1つのインスタンスのクラスです。

関連するページ#

• サービスコンテナ
• コントラクト
• ヘルパー関数
• モック（にせものに置きかえる）