Контракти

Вступ

«Контракти» Laravel - це набір інтерфейсів, що визначають основні сервіси фреймворку. Наприклад, контракт Illuminate\Contracts\Queue\Queue визначає методи, потрібні для постановки завдань у чергу, а контракт Illuminate\Contracts\Mail\Mailer - методи, потрібні для надсилання електронної пошти.

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

Усі контракти Laravel живуть у власному репозиторії на GitHub. Це дає швидкий довідник усіх доступних контрактів, а також єдиний незалежний пакет, який можна використовувати, створюючи пакети, що взаємодіють із сервісами Laravel.

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

Фасади та функції-хелпери Laravel дають простий спосіб користуватися сервісами Laravel, не вказуючи типів і не розв'язуючи контракти із сервіс-контейнера. У більшості випадків кожен фасад має рівнозначний контракт.

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

Коли використовувати контракти

Вибір між контрактами й фасадами залежить від особистих уподобань ваших і вашої команди розробки. І контракти, і фасади дозволяють створювати надійні, добре протестовані застосунки Laravel. Вони не є взаємовиключними. Одні частини вашого застосунку можуть використовувати фасади, тоді як інші залежатимуть від контрактів. Доки ви тримаєте відповідальність класів зосередженою, практичної різниці між контрактами й фасадами майже не помітите.

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

Як використовувати контракти

Отже, як отримати реалізацію контракту? Насправді це доволі просто.

Багато типів класів у Laravel розв'язуються через сервіс-контейнер - зокрема контролери, слухачі подій, middleware, завдання в чергах і навіть замикання маршрутів. Тож щоб отримати реалізацію контракту, достатньо вказати тип інтерфейсу в конструкторі класу, який розв'язується.

Наприклад, погляньте на цей слухач подій:

<?php

namespace App\Listeners;

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

class CacheOrderInformation
{
    /**
     * Create the event listener.
     */
    public function __construct(
        protected Factory $redis,
    ) {}

    /**
     * Handle the event.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}

Коли слухач подій розв'язується, сервіс-контейнер читає вказані типи в конструкторі класу й впроваджує відповідне значення. Щоб дізнатися більше про реєстрацію в сервіс-контейнері, перегляньте його документацію.

Довідник контрактів

Ця таблиця дає швидкий довідник усіх контрактів Laravel та рівнозначних їм фасадів: