Контракты

• Введение
  • Контракты против фасадов
• Когда использовать контракты
• Как использовать контракты
• Справочник контрактов

Введение

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

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

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

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

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

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

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

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

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

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

Итак, как получить реализацию контракта? Это довольно просто.

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

Например, взгляните на этот обработчик событий:

<?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
    {
        // ...
    }
}

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

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

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