Contratti

• Introduzione
• Quando Usare i Contracts
• Come Usare i Contracts
• Riferimento Contratti

Introduzione

I "contracts" di Laravel sono un insieme di interfacce che definiscono i servizi principali forniti dal framework. Ad esempio, il contratto Illuminate\Contracts\Queue\Queue definisce i metodi necessari per accodare i job, mentre il contratto Illuminate\Contracts\Mail\Mailer definisce i metodi necessari per inviare email.

Ogni contratto ha una corrispondente implementazione fornita dal framework. Per esempio, Laravel offre un’implementazione della queue con diversi driver e un’implementazione del mailer alimentata da Symfony Mailer.

Tutti i contracts di Laravel si trovano nel loro repository GitHub. Questo fornisce un punto di riferimento rapido per tutti i contracts disponibili, oltre a un pacchetto unico e decoupled che può essere utilizzato nella creazione di pacchetti che interagiscono con i servizi Laravel.

Contratti vs. Facades

Le facades e le funzioni helper di Laravel offrono un modo semplice per utilizzare i servizi di Laravel senza dover dichiarare il tipo e risolvere i contratti dal service container. Nella maggior parte dei casi, ogni facade ha un contratto equivalente.

A differenza delle facades, che non richiedono di essere incluse nel costruttore della tua classe, i contratti permettono di definire dipendenze esplicite per le tue classi. Alcuni sviluppatori preferiscono definire esplicitamente le dipendenze in questo modo e quindi usano i contratti, mentre altri apprezzano la comodità delle facades. In generale, la maggior parte delle applicazioni può usare le facades senza problemi durante lo sviluppo.

Quando Usare i Contracts

La scelta di utilizzare contracts o facades dipenderà dal gusto personale e da quello del tuo team di sviluppo. Sia i contracts che le facades possono essere usati per creare applicazioni Laravel robuste e ben testate. Contracts e facades non si escludono a vicenda. Alcune parti delle tue applicazioni possono usare facades mentre altre dipendono dai contracts. Finché mantieni le responsabilità delle tue classi focalizzate, noterai poche differenze pratiche tra l’uso di contracts e facades.

In generale, la maggior parte delle applicazioni può usare facades senza problemi durante lo sviluppo. Se stai creando un package che si integra con più framework PHP, potresti voler usare il package illuminate/contracts per definire la tua integrazione con i servizi di Laravel senza dover richiedere le implementazioni concrete di Laravel nel file composer.json del tuo package.

Come Usare i Contracts

Allora, come si ottiene un’implementazione di un contract? In realtà è abbastanza semplice.

Molti tipi di classi in Laravel vengono risolti attraverso il service container, inclusi controller, event listeners, middleware, job in coda e persino closure delle route. Quindi, per ottenere un’implementazione di un contract, puoi semplicemente "type-hintare" l’interfaccia nel costruttore della classe che viene risolta.

Per esempio, guarda questo event listener:

<?php

namespace App\Listeners;

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

class CacheOrderInformation
{
    /**
     * Crea una nuova istanza del gestore degli eventi.
     */
    public function __construct(
        protected Factory $redis,
    ) {}

    /**
     * Gestisce l'evento.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}

Quando l’event listener viene risolto, il service container leggerà i type-hint nel costruttore della classe e inietterà il valore appropriato. Per saperne di più su come registrare le cose nel service container, consulta la sua documentazione.

Riferimento Contratti

Questa tabella fornisce un riferimento rapido a tutti i contratti di Laravel e le loro facciate equivalenti: