Laravel 11.x ファサード

イントロダクションIntroduction

Laravelのドキュメント全体を通して、「ファサード」を介してLaravelの機能を操作するコード例を紹介しています。ファサードは、アプリケーションのサービスコンテナで使用可能なクラスに対して「静的な」インターフェイスを提供します。Laravelは、Laravelのほとんどすべての機能へのアクセスを提供する多くのファサードを提供しています。Throughout the Laravel documentation, you will see examples of code that interacts with Laravel's features via "facades". Facades provide a "static" interface to classes that are available in the application's service container[/docs/{{version}}/container]. Laravel ships with many facades which provide access to almost all of Laravel's features.

Laravelファサードは、サービスコンテナ内の基礎となるクラスへの「静的プロキシ」として機能し、従来の静的メソッドよりもテスト容易性と柔軟性を維持しながら、簡潔で表現力豊かな構文という利点を提供しています。ファサードがどのように機能するかを完全に理解していなくても、まったく問題ありません。流れに沿って、Laravelについて学び続けてください。Laravel facades serve as "static proxies" to underlying classes in the service container, providing the benefit of a terse, expressive syntax while maintaining more testability and flexibility than traditional static methods. It's perfectly fine if you don't totally understand how facades work - just go with the flow and continue learning about Laravel.

Laravelのファサードはすべて、Illuminate\Support\Facades名前空間で定義します。したがって、次のようなファサードに簡単にアクセスできます。All of Laravel's facades are defined in the Illuminate\Support\Facades namespace. So, we can easily access a facade like so:

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

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

Laravelのドキュメント全体を通じ、コード例の多くでファサードを使用して、フレームワークのさまざまな機能を紹介しています。Throughout the Laravel documentation, many of the examples will use facades to demonstrate various features of the framework.

ヘルパ関数Helper Functions

ファサードを補完するため、Laravelはさまざまなグローバルな「ヘルパ機能」を提供し、Laravel機能の一般的な操作をより簡単にしています。使用する可能性のある一般的なヘルパ関数には、view、response、url、configなどがあります。Laravelが提供する各ヘルパ機能は、対応する機能とともにドキュメント化しています。関数の完全なリストは、専用のヘルパドキュメント内にあります。To complement facades, Laravel offers a variety of global "helper functions" that make it even easier to interact with common Laravel features. Some of the common helper functions you may interact with are view, response, url, config, and more. Each helper function offered by Laravel is documented with their corresponding feature; however, a complete list is available within the dedicated helper documentation[/docs/{{version}}/helpers].

たとえば、Illuminate\Support\Facades\Responseファサードを使用してJSONレスポンスを生成する代わりに、単にresponse関数を使用することもできます。ヘルパ関数はグローバルに利用できるため、使用するためにクラスをインポートする必要はありません。For example, instead of using the Illuminate\Support\Facades\Response facade to generate a JSON response, we may simply use the response function. Because helper functions are globally available, you do not need to import any classes in order to use them:

use Illuminate\Support\Facades\Response;

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

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

いつファサードを使うかWhen to Utilize Facades

ファサードには多くの利点があります。これらは、手作業で挿入または設定する必要のある長いクラス名を覚えていなくても、Laravelの機能を使用できるようにする簡潔で覚えやすい構文を提供しています。さらに、PHPの動的メソッドを独自に使用しているため、テストが簡単です。Facades have many benefits. They provide a terse, memorable syntax that allows you to use Laravel's features without remembering long class names that must be injected or configured manually. Furthermore, because of their unique usage of PHP's dynamic methods, they are easy to test.

ただし、ファサードを使用する場合は注意が必要です。ファサードの主な危険性は、クラスの「スコープクリープ」です。ファサードは非常に使いやすく、依存注入を必要としないため、１つのクラスで多くのファサードを使用するのは簡単で、クラスを成長させ続けてしまいがちです。依存注入を使用していれば、大きなコンストラクタによりクラスが大きくなりすぎていることを示す視覚的なフィードバックにより、これが起きる可能性は低減されます。したがって、ファサードを使用するときは、クラスのサイズに特に注意して、クラスの責任範囲が狭くなるようにしてください。クラスが大きくなりすぎている場合は、クラスを複数の小さなクラスに分割することを検討してください。However, some care must be taken when using facades. The primary danger of facades is class "scope creep". Since facades are so easy to use and do not require injection, it can be easy to let your classes continue to grow and use many facades in a single class. Using dependency injection, this potential is mitigated by the visual feedback a large constructor gives you that your class is growing too large. So, when using facades, pay special attention to the size of your class so that its scope of responsibility stays narrow. If your class is getting too large, consider splitting it into multiple smaller classes.

ファサード対依存注入Facades vs. Dependency Injection

依存注入の主な利点の１つは、注入するクラスの実装を交換できることです。これは、モックまたはスタブを挿入して、さまざまなメソッドがスタブで呼び出されたことを表明できるため、テスト中に役立ちます。One of the primary benefits of dependency injection is the ability to swap implementations of the injected class. This is useful during testing since you can inject a mock or stub and assert that various methods were called on the stub.

通常、真に静的なクラスメソッドをモックまたはスタブすることはできません。ただし、ファサードは動的メソッドを使用して、サービスコンテナが解決するオブジェクトへのメソッド呼び出しをプロキシするため、挿入するクラスインスタンスをテストするのと同様に、実際にはファサードをテストできます。たとえば、次のルートがあるとします。Typically, it would not be possible to mock or stub a truly static class method. However, since facades use dynamic methods to proxy method calls to objects resolved from the service container, we actually can test facades just as we would test an injected class instance. For example, given the following route:

use Illuminate\Support\Facades\Cache;

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

Laravelのファサードテストメソッドを使用して、次のテストを記述し、期待する引数でCache::getメソッドを呼び出すことを確認できます。Using Laravel's facade testing methods, we can write the following test to verify that the Cache::get method was called with the argument we expected:

use Illuminate\Support\Facades\Cache;

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

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

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

use Illuminate\Support\Facades\Cache;

/**
 * 基本的な機能テストの例
 */
public function test_basic_example(): void
{
    Cache::shouldReceive('get')
         ->with('key')
         ->andReturn('value');

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

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

ファサード対ヘルパ関数Facades vs. Helper Functions

Laravelには、ファサードに加えて、ビューの生成、イベントの発生、ジョブのディスパッチ、HTTP応答の送信などの一般的なタスクを実行できるさまざまな「ヘルパ」関数が含まれています。これらのヘルパ関数の多くは、対応するファサードと同じ機能を実行します。たとえば、このファサード呼び出しとヘルパ呼び出しは同等です。In addition to facades, Laravel includes a variety of "helper" functions which can perform common tasks like generating views, firing events, dispatching jobs, or sending HTTP responses. Many of these helper functions perform the same function as a corresponding facade. For example, this facade call and helper call are equivalent:

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

return view('profile');

ファサードとヘルパ機能の間に実際的な違いはまったくありません。ヘルパ関数を使用する場合でも、対応するファサードとまったく同じようにテストできます。たとえば、次のルートがあるとします。There is absolutely no practical difference between facades and helper functions. When using helper functions, you may still test them exactly as you would the corresponding facade. For example, given the following route:

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

cacheヘルパはCacheファサードの基礎となるクラスでgetメソッドを呼び出します。したがって、ヘルパ関数を使用している場合でも、次のテストを記述して、期待した引数でメソッドが呼び出されたことを確認できます。The cache helper is going to call the get method on the class underlying the Cache facade. So, even though we are using the helper function, we can write the following test to verify that the method was called with the argument we expected:

use Illuminate\Support\Facades\Cache;

/**
 * 基本的な機能テストの例
 */
public function test_basic_example(): void
{
    Cache::shouldReceive('get')
         ->with('key')
         ->andReturn('value');

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

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

ファサードの仕組みHow Facades Work

Laravelアプリケーションのファサードは、コンテナからのオブジェクトに対するアクセスを提供するクラスです。この作業を行うメカニズムは、Facadeクラスにあります。Laravelのファサード、および作成したカスタムファサードは、基本のIlluminate\Support\Facades\Facadeクラスを拡張します。In 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 Illuminate\Support\Facades\Facade class.

Facade基本クラスは__callStatic()マジックメソッドを利用して、ファサードへの呼び出しをコンテナが解決するオブジェクトへの呼び出しへと延期します。下の例では、Laravelキャッシュシステムが呼び出されます。このコードを一瞥すると、静的なgetメソッドがCacheクラスで呼び出されていると思われるかもしれません。The Facade base class makes use of the __callStatic() magic-method to defer calls from your facade to an object resolved from the container. In the example below, a call is made to the Laravel cache system. By glancing at this code, one might assume that the static get method is being called on the Cache class:

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use Illuminate\Support\Facades\Cache;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * 特定のユーザーのプロファイルを表示
     */
    public function showProfile(string $id): View
    {
        $user = Cache::get('user:'.$id);

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

ファイルの上部近くで、Cacheファサードを「インポート」していることに注意してください。このファサードは、Illuminate\Contracts\Cache\Factoryインターフェイスの基盤となる実装にアクセスするためのプロキシとして機能します。ファサードを使用して行う呼び出しはすべて、Laravelのキャッシュサービスの基盤となるインスタンスに渡されます。Notice that near the top of the file we are "importing" the Cache facade. This facade serves as a proxy for accessing the underlying implementation of the Illuminate\Contracts\Cache\Factory interface. Any calls we make using the facade will be passed to the underlying instance of Laravel's cache service.

そのIlluminate\Support\Facades\Cacheクラスを見ると、静的メソッドgetがないことがわかります。If we look at that Illuminate\Support\Facades\Cache class, you'll see that there is no static method get:

class Cache extends Facade
{
    /**
     * コンポーネントの登録名を取得
     */
    protected static function getFacadeAccessor(): string
    {
        return 'cache';
    }
}

代わりに、Cacheファサードは基本のFacadeクラスを拡張し、メソッドgetFacadeAccessor()を定義します。このメソッドの仕事は、サービスコンテナ結合名を返すことです。ユーザーがCacheファサードの静的メソッドを参照すると、Laravelはサービスコンテナでcache結合を依存解決し、リクエストされたメソッド(この場合はget)をそのオブジェクトに対して実行します。Instead, the Cache facade extends the base Facade class and defines the method getFacadeAccessor(). This method's job is to return the name of a service container binding. When a user references any static method on the Cache facade, Laravel resolves the cache binding from the service container[/docs/{{version}}/container] and runs the requested method (in this case, get) against that object.

リアルタイムファサードReal-Time Facades

リアルタイムファサードを使用すると、アプリケーション内の任意のクラスをファサードであるかのように扱うことができます。これをどのように使用できるかを説明するために、最初にリアルタイムファサードを使用しないコードを調べてみましょう。たとえば、Podcastモデルにpublishメソッドがあるとしましょう。ただし、ポッドキャストを公開するには、Publisherインスタンスを挿入する必要があります。Using real-time facades, you may treat any class in your application as if it was a facade. To illustrate how this can be used, let's first examine some code that does not use real-time facades. For example, let's assume our Podcast model has a publish method. However, in order to publish the podcast, we need to inject a Publisher instance:

<?php

namespace App\Models;

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

class Podcast extends Model
{
    /**
     * ポッドキャストを公開
     */
    public function publish(Publisher $publisher): void
    {
        $this->update(['publishing' => now()]);

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

パブリッシャーの実装をメソッドに注入すると、注入されたパブリッシャーをモックできるため、メソッドを分離して簡単にテストできます。ただし、publishメソッドを呼び出すたびに、常にパブリッシャーインスタンスを渡す必要があります。リアルタイムのファサードを使用すると、Publisherインスタンスを明示的に渡す必要がなく、同じテスト容易性を維持できます。リアルタイムのファサードを生成するには、インポートするクラスの名前空間の前にFacadesを付けます。Injecting a publisher implementation into the method allows us to easily test the method in isolation since we can mock the injected publisher. However, it requires us to always pass a publisher instance each time we call the publish method. Using real-time facades, we can maintain the same testability while not being required to explicitly pass a Publisher instance. To generate a real-time facade, prefix the namespace of the imported class with Facades:

<?php

namespace App\Models;

use App\Contracts\Publisher; // [tl! remove]
use Facades\App\Contracts\Publisher; // [tl! add]
use Illuminate\Database\Eloquent\Model;

class Podcast extends Model
{
    /**
     * ポッドキャストを公開
     */
    public function publish(Publisher $publisher): void // [tl! remove]
    public function publish(): void // [tl! add]
    {
        $this->update(['publishing' => now()]);

        $publisher->publish($this); // [tl! remove]
        Publisher::publish($this); // [tl! add]
    }
}

リアルタイムファサードを使用する場合、パブリッシャーの実装はFacadesプレフィックスの後に表示されるインターフェイスまたはクラス名の部分を使用してサービスコンテナが依存解決します。テスト時には、Laravelの組み込みファサードテストヘルパを使用して、このメソッド呼び出しをモックできます。When the real-time facade is used, the publisher implementation will be resolved out of the service container using the portion of the interface or class name that appears after the Facades prefix. When testing, we can use Laravel's built-in facade testing helpers to mock this method call:

<?php

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

uses(RefreshDatabase::class);

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

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

    $podcast->publish();
});

<?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();
    }
}

ファサードクラスリファレンスFacade Class Reference

以下に、すべてのファサードとその基礎となるクラスを示します。これは、特定のファサードルートのAPIドキュメントをすばやく掘り下げるための便利なツールです。該当するサービスコンテナ結合キーがある場合は内容に含めています。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 service container binding[/docs/{{version}}/container] key is also included where applicable.