Контракты

Статистика: Символов — 8 589/7 387 без пробелов (5 969/5 209 без кода):, слов — 761
Разметка: 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}}

== Введение ==
Контракты в Laravel - это набор интерфейсов, которые описывают основной функционал, предоставляемый фреймворком. Например, контракт %%(t)Illuminate\Contracts\Queue\Queue%% определяет методы, необходимые для организации очередей, в то время как контракт %%(t)Illuminate\Contracts\Mail\Mailer%% определяет методы, необходимые для отправки электронной почты.

Каждый контракт имеет свою реализацию во фреймворке. Например, Laravel предоставляет реализацию %%Queue%% с различными драйверами и реализацию %%Mailer%%, использующую ((http://swiftmailer.org/ SwiftMailer)).

Все контракты Laravel живут в ((https://github.com/illuminate/contracts своих собственных репозиториях GitHub)). Эта ссылка ведёт на все доступные контракты, а также на один отдельный пакет, который может быть использован разработчиками пакетов.

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

В отличие от фасадов, которые не требуют того, чтобы вы запрашивали их в конструкторе вашего класса, контракты позволяют вам определить конкретные зависимости для ваших классов. Некоторые разработчики предпочитают именно так явно определять свои зависимости, поэтому предпочитают использовать контракты, а другие разработчики наслаждаются удобством фасадов.

.(alert)
Для большинства приложений неважно, что вы выберете - фасады или контракты. Но если вы создаёте пакет, то вам надо использовать контракты, так как в этом случае их проще тестировать.

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

Однако, у вас по-прежнему могут остаться некоторые вопросы о контрактах. Например, зачем вообще нужны интерфейсы? Разве их использование делает жизнь проще? Определим причины использования интерфейсов как следующие: это слабая связанность (loose coupling) и упрощение кода.

=== Слабая связанность ===
Но для начала рассмотрим код с сильной связанностью с реализацией кэша. Рассмотрите следующее:
%%
  <?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))  {
        //
      }
    }

  }
%%

В этом классе код сильно связан с реализацией кэша, потому что мы зависим от конкретного класса Cache данного пакета. Если API этого пакета изменится, наш код  должен также измениться.

Аналогично, если мы хотим заменить нашу базовую технологию кэша (Memcached) другой технологией (Redis), нам придётся вносить изменения в наш репозиторий. А наш репозиторий не должен задумываться о том, кто именно предоставляет данные или как он это делает.

**Вместо такого подхода, мы можем улучшить наш код, добавив зависимость от простого интерфейса, которой не зависит от поставщика:**
%%
  <?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. Контракт не содержит никакой конкретной реализации и никаких зависимостей. Вы можете легко написать свою реализацию любого контракта, что позволяет вам заменить реализацию работы с кэшем, не изменяя ни одной строчки вашего кода, работающего с кэшем.

=== Упрощение кода ===
Когда все сервисы Laravel аккуратно определены в простых интерфейсах, очень легко определить функциональность, предлагаемую данными сервисами. **Фактически, контракты являются краткой документацией для функций Laravel.**

Кроме того, когда в своём приложении вы внедряете в классы зависимости от простых интерфейсов, в вашем коде легче разобраться и его проще поддерживать. Вместо того, чтобы искать методы в большом и сложном классе, вы можете обратиться к простому и понятному интерфейсу.

== Как использовать контракты ==
Как получить реализацию контракта? Это довольно просто. Множество типов классов в Laravel регистрируются в ((/docs/v5/container сервис-контейнере)), включая контроллеры, слушатели событий, посредники, очереди и даже замыкания. Поэтому, чтобы получить реализацию контракта, вам достаточно указать тип интерфейса в конструкторе необходимого класса. Например, посмотрите на этот обработчик событий:
%%
<?php

namespace App\Listeners;

use App\User;
use App\Events\OrderWasPlaced;
use Illuminate\Contracts\Redis\Database;

class CacheOrderInformation
{
  /**
   * Реализация базы данных Redis.
   */
  protected $redis;
 
  /**
   * Создание нового экземпляра обработчика событий.
   *
   * @param  Database  $redis
   * @return void
   */
  public function __construct(Database $redis)
  {
    $this->redis = $redis;
  }

  /**
   * Обработка события.
   *
   * @param  OrderWasPlaced  $event
   * @return void
   */
  public function handle(OrderWasPlaced $event)
  {
    //
  }
}
%%

Когда будет получен слушатель события, сервис-контейнер прочитает указание типа в конструкторе класса и внедрит нужное значение. Узнать больше о регистрации в сервис-контейнере можно в ((/docs/v5/container документации)).

== Список контрактов ==
В этой таблице приведены ссылки на все контракты Laravel, а также эквивалентные им фасады:
%%(hvlraw)
  <table>
   <tr>
    <th>Контракт</th>
    <th>Соответствующий фасад</th>
   </tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Auth/Factory.php>Illuminate\Contracts\Auth\Factory</a> для 5.2+<br><a href=https://github.com/illuminate/contracts/blob/master/Auth/Guard.php>Illuminate\Contracts\Auth\Guard</a> для 5.1-</td><td>Auth</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Auth/PasswordBroker.php>Illuminate\Contracts\Auth\PasswordBroker</a></td><td>Password</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Bus/Dispatcher.php>Illuminate\Contracts\Bus\Dispatcher</a></td><td>Bus</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Broadcasting/Broadcaster.php>Illuminate\Contracts\Broadcasting\Broadcaster</a></td><td>&nbsp;</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Cache/Repository.php>Illuminate\Contracts\Cache\Repository</a></td><td>Cache</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Cache/Factory.php>Illuminate\Contracts\Cache\Factory</a></td><td>Cache::driver()</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Config/Repository.php>Illuminate\Contracts\Config\Repository</a></td><td>Config</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Container/Container.php>Illuminate\Contracts\Container\Container</a></td><td>App</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Cookie/Factory.php>Illuminate\Contracts\Cookie\Factory</a></td><td>Cookie</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Cookie/QueueingFactory.php>Illuminate\Contracts\Cookie\QueueingFactory</a></td><td>Cookie::queue()</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Encryption/Encrypter.php>Illuminate\Contracts\Encryption\Encrypter</a></td><td>Crypt</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Events/Dispatcher.php>Illuminate\Contracts\Events\Dispatcher</a></td><td>Event</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Filesystem/Cloud.php>Illuminate\Contracts\Filesystem\Cloud</a></td><td>&nbsp;</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Filesystem/Factory.php>Illuminate\Contracts\Filesystem\Factory</a></td><td>File</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Filesystem/Filesystem.php>Illuminate\Contracts\Filesystem\Filesystem</a></td><td>File</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Foundation/Application.php>Illuminate\Contracts\Foundation\Application</a></td><td>App</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Hashing/Hasher.php>Illuminate\Contracts\Hashing\Hasher</a></td><td>Hash</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Logging/Log.php>Illuminate\Contracts\Logging\Log</a></td><td>Log</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Mail/MailQueue.php>Illuminate\Contracts\Mail\MailQueue</a></td><td>Mail::queue()</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Mail/Mailer.php>Illuminate\Contracts\Mail\Mailer</a></td><td>Mail</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Queue/Factory.php>Illuminate\Contracts\Queue\Factory</a></td><td>Queue::driver()</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Queue/Queue.php>Illuminate\Contracts\Queue\Queue</a></td><td>Queue</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Redis/Database.php>Illuminate\Contracts\Redis\Database</a></td><td>Redis</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Routing/Registrar.php>Illuminate\Contracts\Routing\Registrar</a></td><td>Route</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Routing/ResponseFactory.php>Illuminate\Contracts\Routing\ResponseFactory</a></td><td>Response</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Routing/UrlGenerator.php>Illuminate\Contracts\Routing\UrlGenerator</a></td><td>URL</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Support/Arrayable.php>Illuminate\Contracts\Support\Arrayable</a></td><td>&nbsp;</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Support/Jsonable.php>Illuminate\Contracts\Support\Jsonable</a></td><td>&nbsp;</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Support/Renderable.php>Illuminate\Contracts\Support\Renderable</a></td><td>&nbsp;</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Validation/Factory.php>Illuminate\Contracts\Validation\Factory</a></td><td>Validator::make()</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/Validation/Validator.php>Illuminate\Contracts\Validation\Validator</a></td><td>&nbsp;</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/View/Factory.php>Illuminate\Contracts\View\Factory</a></td><td>View::make()</td></tr>
   <tr><td><a href=https://github.com/illuminate/contracts/blob/master/View/View.php>Illuminate\Contracts\View\View</a></td><td>&nbsp;</td></tr>
  </table>
%%