Контракты

Введение

«Контракты» Laravel – это набор интерфейсов, которые определяют основные службы фреймворка. Например, контракт Illuminate\Contracts\Queue\Queue определяет методы, необходимые для отправки заданий в очередь, а контракт Illuminate\Contracts\Mail\Mailer – для отправки электронной почты.

Каждый контракт имеет соответствующую реализацию, предоставляемую фреймворком. Например, Laravel предлагает реализацию очереди с множеством драйверов и реализацию компонента для отправки почты, который работает на базе Symfony Mailer.

Все контракты Laravel хранятся в собственном репозитории GitHub. Это обеспечивает быстрый доступ к списку всех доступных контрактов, а также единый, отдельный пакет, который используется разработчиками пакетов, взаимодействующих со службами Laravel.

Контракты против Фасадов

Фасады и глобальные хелперы Laravel обеспечивают простой способ использования сервисов Laravel без необходимости объявления типа зависимости(Type Hinting) и извлечения контракта из сервис-контейнера. В большинстве случаев каждый фасад имеет эквивалентный контракт.

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

Когда использовать контракты

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

При разработке большинства приложений можно без проблем использовать фасады. Если вы создаете пакет, который будет интегрирован с несколькими PHP-фреймворками, вы можете указать пакет illuminate/contracts в файле composer.json вашего пакета для определения вашей интеграции со службами Laravel без необходимости требовать конкретную реализацию для Laravel.

Как использовать контракты

Как получить реализацию контракта? На самом деле это довольно просто.

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

Например, взгляните на этот слушатель:

<?php

namespace App\Listeners;

use App\Events\OrderWasPlaced;
use App\Models\User;
use Illuminate\Contracts\Redis\Factory;

class CacheOrderInformation
{
    /**
     * Создать новый экземпляр обработчика события.
     */
    public function __construct(
        protected Factory $redis,
    ) {}

    /**
     * Обработать событие.
     */
    public function handle(OrderWasPlaced $event) : void
    {
       // ...
    }
}

Когда слушатель события будет извлечен, сервис-контейнер, используя инициализацию типов в конструкторе класса, внедрит соответствующую зависимость. Чтобы узнать больше о регистрации в сервис-контейнере, ознакомьтесь с его документацией.

Справочник контрактов

В этой таблице содержится краткий справочник контрактов и эквивалентных им фасадов Laravel: