Фасады

Статистика: Символов — 12 403/10 708 без пробелов (8 723/7 593 без кода):, слов — 1 131
Разметка: Wiki
{{TOC}}

{{DOCVER 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11}}

== Введение ==
Фасады предоставляют "статический" интерфейс к классам, доступным в ((docs/v5/container сервис-контейнере)). Laravel поставляется со множеством фасадов, предоставляющих доступ почти ко всем возможностям Laravel. Фасады Laravel служат "статическими прокси" для классов в сервис-контейнере, обеспечивая преимущества краткого выразительного синтаксиса, и поддерживая большую тестируемость и гибкость, чем традиционные статические методы.

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
Все фасады Laravel определены в пространстве имён %%(t)Illuminate\Support\Facades%%. Поэтому мы можем легко обратиться к фасаду таким образом:
~%%
use Illuminate\Support\Facades\Cache;

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

Во многих примерах в документации по Laravel используются фасады для демонстрации различных возможностей фреймворка.

== Когда стоит использовать фасады ==
Фасады имеют много преимуществ. Они обеспечивают лаконичный, запоминающийся синтаксис, который позволяет вам использовать возможности Laravel, не запоминая длинные имена классов, которые должны внедряться или настраиваться вручную. Более того, благодаря уникальному использованию динамических методов PHP они легко тестируются.

Тем не менее, при использовании фасадов необходимо соблюдать некоторые предосторожности. Основная опасность фасадов - разрастание границ класса. Поскольку фасады так просты в использовании и не требуют внедрения, становится очень вероятна ситуация, когда ваши классы постоянно продолжают расти, и когда в одном классе используется множество фасадов. При использовании внедрения зависимостей риск возникновения такой ситуации снижается за счёт того, что при виде большого конструктора вы можете визуально оценить увеличение размера вашего класса. Поэтому при использовании фасадов обратите особое внимание на размер вашего класса, чтобы границы его ответственности оставались узкими.

.(alert)
При создании стороннего пакета, взаимодействующего с Laravel, лучше внедрять ((//docs/v5/contracts контракты Laravel)) вместо использования фасадов. Поскольку пакеты создаются вне самого Laravel, у вас не будет доступа к вспомогательным функциям тестирования фасадов.

=== Фасады или внедрение зависимостей ===
Одно из основных преимуществ внедрения зависимостей - возможность подменить реализацию внедрённого класса. Это полезно при тестировании, потому что вы можете внедрить макет или заглушку, в которой якобы будут вызываться различные методы.

Обычно невозможно сделать макет или заглушку метода настоящего статического класса. Но поскольку фасады используют динамические методы для передачи вызовов к объектам, извлекаемым из сервис-контейнера, мы можем тестировать фасад точно так же, как тестировали бы внедрённый экземпляр класса. Например, возьмём следующий маршрут:
~%%
use Illuminate\Support\Facades\Cache;

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

Мы можем написать следующий тест, чтобы проверить, что метод %%Cache::get()%% был вызван с ожидаемым нами аргументом:
~%%
use Illuminate\Support\Facades\Cache;

/**
 * Пример базового функционального теста.
 *
 * @return void
 */
public function testBasicExample()
{
  Cache::shouldReceive('get')
       ->with('key')
       ->andReturn('value');

  $this->visit('/cache')
       ->see('value');
}
~%%

=== Фасады или вспомогательные функции ===
Кроме фасадов в Laravel есть множество "вспомогательных" функций, которые могут выполнять общие задачи, такие как генерация представлений, запуск событий, постановка задач и отправка HTTP-откликов. Многие из этих вспомогательных функций выполняют те же задачи, что и соответствующий фасад. Например, эти вызовы фасада и вспомогательной функции эквивалентны:
~%%
return View::make('profile');

return view('profile');
~%%

Нет абсолютно никакой фактической разницы между фасадами и вспомогательными функциями. При использовании вспомогательных функций вы можете тестировать их точно так же, как тестировали бы соответствующий фасад. Например, возьмём следующий маршрут:
~%%
Route::get('/cache', function () {
  return cache('key');
});
~%%

При этом вспомогательная функция %%cache()%% вызовет метод %%get()%% на классе, лежащем в основе фасада %%Cache%%. Поэтому несмотря на то, что мы используем вспомогательную функцию, мы можем написать следующий тест, чтобы проверить, что метод был вызван с ожидаемым нами аргументом:
~%%
use Illuminate\Support\Facades\Cache;

/**
 * Пример базового функционального теста.
 *
 * @return void
 */
public function testBasicExample()
{
  Cache::shouldReceive('get')
       ->with('key')
       ->andReturn('value');

  $this->visit('/cache')
       ->see('value');
}
~%%
%%

== Как работают фасады ==
В Laravel-приложении фасад - это класс, который предоставляет доступ к объекту в контейнере. Весь этот механизм реализован в классе %%Facade%%. И фасады Laravel, и ваши собственные, наследуют базовый класс %%(t)Illuminate\Support\Facades\Facade%%.


Базовый класс %%Facade%% использует ((phpdoc:language.oop5.overloading магический метод PHP)) %%__callStatic()%% для перенаправления вызовов методов с вашего фасада на полученный объект. В примере ниже делается обращение к механизму кэширования Laravel. На первый взгляд может показаться, что метод %%get()%% принадлежит классу %%Cache%%:
%%
<?php

namespace App\Http\Controllers;

use Cache;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
  /**
   * Показать профиль данного пользователя.
   *
   * @param  int  $id
   * @return Response
   */
  public function showProfile($id)
  {
    $user = Cache::get('user:'.$id);

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

Обратите внимание, в начале мы "импортируем" фасад %%(t)Cache%%. Этот фасад служит переходником для доступа к лежащей в основе реализации интерфейса %%(t)Illuminate\Contracts\Cache\Factory%%. Все выполняемые через этот фасад вызовы передаются ниже - в экземпляр кэш-сервиса Laravel.

Если вы посмотрите в исходный код класса %%(t)Illuminate\Support\Facades\Cache%%, то увидите, что он не содержит метода %%get()%%:
%%
class Cache extends Facade
{
  /**
   * Получить зарегистрированное имя компонента.
   *
   * @return string
   */
  protected static function getFacadeAccessor() { return 'cache'; }
}
%%

Вместо этого, фасад %%(t)Cache%% наследует базовый класс %%Facade%% и определяет метод %%getFacadeAccessor()%%. Его задача - вернуть имя //привязки// в сервис-контейнере. Когда вы обращаетесь к любому статическому методу фасада %%(t)Cache%%, Laravel получает по привязке объект %%(t)cache%% из ((/docs/v5/container сервис-контейнера)) и вызывает на нём требуемый метод (в этом случае - %%get()%%).

%%(DOCNEW 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
Таким образом, вызов %%Cache::get()%% может быть переписан так:
~%%
$value = $app->make('cache')->get('key');
~%%

**Импорт фасадов**

Помните, если вы используете фасад в контроллере, который находится в пространстве имён, то вам надо импортировать класс фасада в пространство имён. Все фасады живут в глобальном пространстве имён:
~%%
<?php namespace App\Http\Controllers;

use Cache;

class PhotosController extends Controller {

  /**
   * Получить все фотографии приложения.
   *
   * @return Response
   */
  public function index()
  {
    $photos = Cache::get('photos');

    //
  }

}
~%%

== Создание фасадов ==
Создать фасад в вашем приложении или пакете довольно просто. Вам нужны только три вещи:
  1. Привязка в сервис-контейнере.
  1. Класс-фасад.
  1. Настройка для псевдонима фасада.

Посмотрим на следующий пример. Здесь определён класс %%PaymentGateway\Payment%%:
~%%
namespace PaymentGateway;

class Payment {

  public function process()
  {
    //
  }

}
~%%

Нам нужно, чтобы этот класс извлекался из сервис-контейнера, поэтому давайте добавим для него привязку (//binding//):
~%%
App::bind('payment', function()
{
  return new \PaymentGateway\Payment;
});
~%%

Самое лучшее место для регистрации этой привязки - новый ((docs/v5/providers поставщик услуг)), который мы назовём %%PaymentServiceProvider%% и в котором мы создадим метод %%register()%%, содержащий представленный выше код. После этого вы можете настроить Laravel для загрузки этого поставщика в файле %%(t)config/app.php%%.

Дальше мы можем создать класс нашего фасада:
~%%
use Illuminate\Support\Facades\Facade;

class Payment extends Facade {

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

}
~%%

Наконец, по желанию можно добавить псевдоним (//alias//) для этого фасада в массив %%(t)aliases%% файла настроек %%(t)config/app.php%%. Тогда мы сможем вызывать метод %%process()%% на экземпляре класса %%Payment%%:
~%%
Payment::process();
~%%

=== Об автозагрузке псевдонимов ===
В некоторых случаях классы в массиве %%(t)aliases%% не доступны из-за того, что ((https://bugs.php.net/bug.php?id=39003 PHP не загружает неопределённые классы при указании их типов)). Если %%\ServiceWrapper\ApiTimeoutException%% имеет псевдоним %%ApiTimeoutException%%, то %%catch (ApiTimeoutException $e)%%, помещённый в любое пространство имён, кроме %%ServiceWrapper%%, никогда не "поймает" исключение, даже когда оно возникнет. Аналогичная проблема возникает в классах, которые содержат указания типов на классы с псевдонимами. Единственное решение - не использовать псевдонимы и вместо них в начале каждого файла, где это необходимо, писать %%use%% для тех классов, типы которых вы хотите указать.

== Фасады-заглушки ==
Юнит-тесты играют важную роль в том, как именно работают фасады. На самом деле возможность тестирования - основная причина, по которой фасады вообще существуют. Эта тема подробнее раскрыта в разделе документации о ((docs/v5/testing#заглушки_фасадов фасадах-заглушках)).
%%

== Соответствие фасадов и классов ==
В таблице ниже перечислены все фасады и соответствующие им классы. Это полезный инструмент для быстрого начала работы с документацией по API данного корня фасадов. Также указаны ключи ((/docs/v5/container привязок в сервис-контейнере)), где это нужно.

%%(hvlraw)
  <table>
   <tr>
    <th>Фасад</th>
    <th>Класс</th>
    <th>Привязка в сервис-контейнере</th>
   </tr>
   <tr><td>App</td><td><a href=https://laravel.com/api/5.3/Illuminate/Foundation/Application.html>Illuminate\Foundation\Application</a></td><td>app</td></tr>
   <tr><td>Artisan</td><td>5.3, 5.2 и 5.1 <a href=https://laravel.com/api/5.3/Illuminate/Contracts/Console/Kernel.html>Illuminate\Contracts\Console\Kernel</a><br>5.0 <a href=http://laravel.com/api/5.0/Illuminate/Console/Application.html>Illuminate\Console\Application</a></td><td>artisan</td></tr>
   <tr><td>Auth</td><td><a href=https://laravel.com/api/5.3/Illuminate/Auth/AuthManager.html>Illuminate\Auth\AuthManager</a></td><td>auth</td></tr>
   <tr><td>Auth (экземпляр)</td><td><a href=http://laravel.com/api/5.1/Illuminate/Auth/Guard.html>Illuminate\Auth\Guard</a> только для 5.1 и ранее</td><td></td></tr>
   <tr><td>Blade</td><td><a href=https://laravel.com/api/5.3/Illuminate/View/Compilers/BladeCompiler.html>Illuminate\View\Compilers\BladeCompiler</a></td><td>blade.compiler</td></tr>
   <tr><td>Bus</td><td><a href=https://laravel.com/api/5.3/Illuminate/Contracts/Bus/Dispatcher.html>Illuminate\Contracts\Bus\Dispatcher</a></td><td></td></tr>
   <tr><td>Cache</td><td>5.3, 5.2 и 5.1 <a href=https://laravel.com/api/5.3/Illuminate/Cache/Repository.html>Illuminate\Cache\Repository</a><br>5.0 <a href=http://laravel.com/api/5.0/Illuminate/Cache/Repository.html>Illuminate\Cache\CacheManager</a></td><td>cache</td></tr>
   <tr><td>Config</td><td><a href=https://laravel.com/api/5.3/Illuminate/Config/Repository.html>Illuminate\Config\Repository</a></td><td>config</td></tr>
   <tr><td>Cookie</td><td><a href=https://laravel.com/api/5.3/Illuminate/Cookie/CookieJar.html>Illuminate\Cookie\CookieJar</a></td><td>cookie</td></tr>
   <tr><td>Crypt</td><td><a href=https://laravel.com/api/5.3/Illuminate/Encryption/Encrypter.html>Illuminate\Encryption\Encrypter</a></td><td>encrypter</td></tr>
   <tr><td>DB</td><td><a href=https://laravel.com/api/5.3/Illuminate/Database/DatabaseManager.html>Illuminate\Database\DatabaseManager</a></td><td>db</td></tr>
   <tr><td>DB (экземпляр)</td><td><a href=https://laravel.com/api/5.3/Illuminate/Database/Connection.html>Illuminate\Database\Connection</a></td><td></td></tr>
   <tr><td>Event</td><td><a href=https://laravel.com/api/5.3/Illuminate/Events/Dispatcher.html>Illuminate\Events\Dispatcher</a></td><td>events</td></tr>
   <tr><td>File</td><td><a href=https://laravel.com/api/5.3/Illuminate/Filesystem/Filesystem.html>Illuminate\Filesystem\Filesystem</a></td><td>files</td></tr>
   <tr><td>Form</td><td>5.0 <a href=http://laravel.com/api/5.0/Illuminate/Html/FormBuilder.html>Illuminate\Html\FormBuilder</a></td><td>form</td></tr>
   <tr><td>Gate</td><td><a href=https://laravel.com/api/5.3/Illuminate/Contracts/Auth/Access/Gate.html>Illuminate\Contracts\Auth\Access\Gate</a></td><td></td></tr>
   <tr><td>Hash</td><td><a href=https://laravel.com/api/5.3/Illuminate/Contracts/Hashing/Hasher.html>Illuminate\Contracts\Hashing\Hasher</a></td><td>hash</td></tr>
   <tr><td>Input</td><td><a href=https://laravel.com/api/5.1/Illuminate/Http/Request.html>Illuminate\Http\Request</a> только для 5.1 и ранее</td><td>request</td></tr>
   <tr><td>Lang</td><td><a href=https://laravel.com/api/5.3/Illuminate/Translation/Translator.html>Illuminate\Translation\Translator</a></td><td>translator</td></tr>
   <tr><td>Log</td><td><a href=https://laravel.com/api/5.3/Illuminate/Log/Writer.html>Illuminate\Log\Writer</a></td><td>log</td></tr>
   <tr><td>Mail</td><td><a href=https://laravel.com/api/5.3/Illuminate/Mail/Mailer.html>Illuminate\Mail\Mailer</a></td><td>mailer</td></tr>
   <tr><td>Notification</td><td><a href=https://laravel.com/api/5.3/Illuminate/Notifications/ChannelManager.html>Illuminate\Notifications\ChannelManager</a> для 5.3 и выше</td><td></td></tr>
   <tr><td>Password</td><td>5.3, 5.2 и 5.1 <a href=https://laravel.com/api/5.3/Illuminate/Auth/Passwords/PasswordBroker.html>Illuminate\Auth\Passwords\PasswordBroker</a><br>5.0 <a href=http://laravel.com/api/5.0/Illuminate/Auth/Reminders/PasswordBroker.html>Illuminate\Auth\Reminders\PasswordBroker</a></td><td>auth.password<br>auth.reminder</td></tr>
   <tr><td>Queue</td><td><a href=https://laravel.com/api/5.3/Illuminate/Queue/QueueManager.html>Illuminate\Queue\QueueManager</a></td><td>queue</td></tr>
   <tr><td>Queue (экземпляр)</td><td><a href=https://laravel.com/api/5.1/Illuminate/Queue/QueueInterface.html>Illuminate\Queue\QueueInterface</a> для 5.1 и ранее<br><a href=https://laravel.com/api/5.3/Illuminate/Contracts/Queue/Queue.html>Illuminate\Contracts\Queue\Queue</a> для 5.2 и выше</td><td><br>queue</td></tr>
   <tr><td>Queue (базовый класс)</td><td><a href=https://laravel.com/api/5.3/Illuminate/Queue/Queue.html>Illuminate\Queue\Queue</a></td><td></td></tr>
   <tr><td>Redirect</td><td><a href=https://laravel.com/api/5.3/Illuminate/Routing/Redirector.html>Illuminate\Routing\Redirector</a></td><td>redirect</td></tr>
   <tr><td>Redis</td><td><a href=https://laravel.com/api/5.3/Illuminate/Redis/Database.html>Illuminate\Redis\Database</a></td><td>redis</td></tr>
   <tr><td>Request</td><td><a href=https://laravel.com/api/5.3/Illuminate/Http/Request.html>Illuminate\Http\Request</a></td><td>request</td></tr>
   <tr><td>Response</td><td><a href=https://laravel.com/api/5.3/Illuminate/Contracts/Routing/ResponseFactory.html>Illuminate\Contracts\Routing\ResponseFactory</a></td><td></td></tr>
   <tr><td>Route</td><td><a href=https://laravel.com/api/5.3/Illuminate/Routing/Router.html>Illuminate\Routing\Router</a></td><td>router</td></tr>
   <tr><td>Schema</td><td><a href=https://laravel.com/api/5.3/Illuminate/Database/Schema/Blueprint.html>Illuminate\Database\Schema\Blueprint</a></td><td></td></tr>
   <tr><td>Session</td><td><a href=https://laravel.com/api/5.3/Illuminate/Session/SessionManager.html>Illuminate\Session\SessionManager</a></td><td>session</td></tr>
   <tr><td>Session (экземпляр)</td><td><a href=https://laravel.com/api/5.3/Illuminate/Session/Store.html>Illuminate\Session\Store</a></td><td></td></tr>
   <tr><td>Storage</td><td><a href=https://laravel.com/api/5.3/Illuminate/Contracts/Filesystem/Factory.html>Illuminate\Contracts\Filesystem\Factory</a></td><td>filesystem</td></tr>
   <tr><td>URL</td><td><a href=https://laravel.com/api/5.3/Illuminate/Routing/UrlGenerator.html>Illuminate\Routing\UrlGenerator</a></td><td>url</td></tr>
   <tr><td>Validator</td><td><a href=https://laravel.com/api/5.3/Illuminate/Validation/Factory.html>Illuminate\Validation\Factory</a></td><td>validator</td></tr>
   <tr><td>Validator (экземпляр)</td><td><a href=https://laravel.com/api/5.3/Illuminate/Validation/Validator.html>Illuminate\Validation\Validator</a></td><td></td></tr>
   <tr><td>View</td><td><a href=https://laravel.com/api/5.3/Illuminate/View/Factory.html>Illuminate\View\Factory</a></td><td>view</td></tr>
   <tr><td>View (экземпляр)</td><td><a href=https://laravel.com/api/5.3/Illuminate/View/View.html>Illuminate\View\View</a></td><td></td></tr>
  </table>
%%