Поддержите проект сделав пожертвование.
Поддержите нас - каждый вклад важен!
Поддержите нас - каждый вклад важен!

Контракты

Введение

«Контракты» 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:

Контракт Фасад
Illuminate\Contracts\Auth\Access\Authorizable  
Illuminate\Contracts\Auth\Access\Gate Gate
Illuminate\Contracts\Auth\Authenticatable  
Illuminate\Contracts\Auth\CanResetPassword  
Illuminate\Contracts\Auth\Factory Auth
Illuminate\Contracts\Auth\Guard Auth::guard()
Illuminate\Contracts\Auth\PasswordBroker Password::broker()
Illuminate\Contracts\Auth\PasswordBrokerFactory Password
Illuminate\Contracts\Auth\StatefulGuard  
Illuminate\Contracts\Auth\SupportsBasicAuth  
Illuminate\Contracts\Auth\UserProvider  
Illuminate\Contracts\Broadcasting\Broadcaster Broadcast::connection()
Illuminate\Contracts\Broadcasting\Factory Broadcast
Illuminate\Contracts\Broadcasting\ShouldBroadcast  
Illuminate\Contracts\Broadcasting\ShouldBroadcastNow  
Illuminate\Contracts\Bus\Dispatcher Bus
Illuminate\Contracts\Bus\QueueingDispatcher Bus::dispatchToQueue()
Illuminate\Contracts\Cache\Factory Cache
Illuminate\Contracts\Cache\Lock  
Illuminate\Contracts\Cache\LockProvider  
Illuminate\Contracts\Cache\Repository Cache::driver()
Illuminate\Contracts\Cache\Store  
Illuminate\Contracts\Config\Repository Config
Illuminate\Contracts\Console\Application  
Illuminate\Contracts\Console\Kernel Artisan
Illuminate\Contracts\Container\Container App
Illuminate\Contracts\Cookie\Factory Cookie
Illuminate\Contracts\Cookie\QueueingFactory Cookie::queue()
Illuminate\Contracts\Database\ModelIdentifier  
Illuminate\Contracts\Debug\ExceptionHandler  
Illuminate\Contracts\Encryption\Encrypter Crypt
Illuminate\Contracts\Events\Dispatcher Event
Illuminate\Contracts\Filesystem\Cloud Storage::cloud()
Illuminate\Contracts\Filesystem\Factory Storage
Illuminate\Contracts\Filesystem\Filesystem Storage::disk()
Illuminate\Contracts\Foundation\Application App
Illuminate\Contracts\Hashing\Hasher Hash
Illuminate\Contracts\Http\Kernel  
Illuminate\Contracts\Mail\Mailable  
Illuminate\Contracts\Mail\Mailer Mail
Illuminate\Contracts\Mail\MailQueue Mail::queue()
Illuminate\Contracts\Notifications\Dispatcher Notification
Illuminate\Contracts\Notifications\Factory Notification
Illuminate\Contracts\Pagination\LengthAwarePaginator  
Illuminate\Contracts\Pagination\Paginator  
Illuminate\Contracts\Pipeline\Hub  
Illuminate\Contracts\Pipeline\Pipeline Pipeline;
Illuminate\Contracts\Queue\EntityResolver  
Illuminate\Contracts\Queue\Factory Queue
Illuminate\Contracts\Queue\Job  
Illuminate\Contracts\Queue\Monitor Queue
Illuminate\Contracts\Queue\Queue Queue::connection()
Illuminate\Contracts\Queue\QueueableCollection  
Illuminate\Contracts\Queue\QueueableEntity  
Illuminate\Contracts\Queue\ShouldQueue  
Illuminate\Contracts\Redis\Factory Redis
Illuminate\Contracts\Routing\BindingRegistrar Route
Illuminate\Contracts\Routing\Registrar Route
Illuminate\Contracts\Routing\ResponseFactory Response
Illuminate\Contracts\Routing\UrlGenerator URL
Illuminate\Contracts\Routing\UrlRoutable  
Illuminate\Contracts\Session\Session Session::driver()
Illuminate\Contracts\Support\Arrayable  
Illuminate\Contracts\Support\Htmlable  
Illuminate\Contracts\Support\Jsonable  
Illuminate\Contracts\Support\MessageBag  
Illuminate\Contracts\Support\MessageProvider  
Illuminate\Contracts\Support\Renderable  
Illuminate\Contracts\Support\Responsable  
Illuminate\Contracts\Translation\Loader  
Illuminate\Contracts\Translation\Translator Lang
Illuminate\Contracts\Validation\Factory Validator
Illuminate\Contracts\Validation\ValidatesWhenResolved  
Illuminate\Contracts\Validation\ValidationRule  
Illuminate\Contracts\Validation\Validator Validator::make()
Illuminate\Contracts\View\Engine  
Illuminate\Contracts\View\Factory View
Illuminate\Contracts\View\View View::make()