> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Contracts (contratti)

> Il ruolo dei Contracts di Laravel, la differenza con le facade, come iniettarli tramite type hint e come creare Contract personalizzati.

## Cos'è un Contract

I "Contracts" di Laravel sono un insieme di interfacce che definiscono i servizi principali offerti dal framework. Ad esempio, il Contract `Illuminate\Contracts\Queue\Queue` definisce i metodi necessari a mettere in coda i job, mentre il Contract `Illuminate\Contracts\Mail\Mailer` definisce i metodi necessari per l'invio di email.

Per ogni Contract il framework fornisce un'implementazione corrispondente. Laravel offre ad esempio implementazioni di code con vari driver e un mailer basato su [Symfony Mailer](https://symfony.com/doc/current/mailer.html).

Tutti i Contracts di Laravel si trovano nel loro [repository GitHub dedicato](https://github.com/illuminate/contracts). Costituisce un riferimento rapido a tutti i Contract disponibili ed è un pacchetto isolato che puoi usare quando costruisci pacchetti che si integrano con i servizi Laravel.

<Info>
  Un Contract è semplicemente un'interfaccia. Funziona esattamente come le interfacce di PHP. Laravel fornisce le implementazioni di queste interfacce e le inietta tramite il service container.
</Info>

## Differenza tra Contract e Facade

Le [facade](/it/facades) e le funzioni helper offrono un modo semplice per usare i servizi di Laravel senza dover risolvere i Contract con un type hint dal service container. Nella maggior parte dei casi, ciascuna facade ha un Contract corrispondente.

Le differenze principali tra facade e Contract sono le seguenti.

| Aspetto                        | Facade                                    | Contract                                                   |
| ------------------------------ | ----------------------------------------- | ---------------------------------------------------------- |
| Dichiarazione della dipendenza | Non necessaria (richiamabile ovunque)     | Dichiarata esplicitamente nel costruttore                  |
| Test                           | Mock con `shouldReceive()`                | Sostituzione tramite una libreria di mock standard         |
| Uso principale                 | Uso agevole all'interno dell'applicazione | Sviluppo di pacchetti, gestione esplicita delle dipendenze |
| Leggibilità del codice         | Basta una singola riga di import          | Le dipendenze sono immediatamente visibili nel costruttore |

<Tip>
  Le facade non richiedono di dichiararle nel costruttore della classe, mentre i Contract puoi definirli come dipendenze esplicite nel costruttore. Alcuni sviluppatori preferiscono questa esplicitezza e usano i Contract; altri preferiscono la comodità delle facade. **In generale, la maggior parte delle applicazioni può usare le facade senza problemi durante lo sviluppo.**
</Tip>

## Quando usare i Contract

Scegliere tra Contract e Facade dipende dalle preferenze personali o del team. Entrambi permettono di creare applicazioni Laravel robuste e testabili. Non si escludono a vicenda: in una parte dell'applicazione puoi usare le Facade e in un'altra affidarti ai Contract.

I Contract sono particolarmente utili nelle seguenti situazioni:

* **Quando costruisci pacchetti che si integrano con più framework PHP** — Usando il pacchetto `illuminate/contracts` per definire l'integrazione con i servizi Laravel, non devi richiedere l'implementazione concreta di Laravel nel `composer.json`.
* **Quando vuoi rendere esplicite le dipendenze** — Guardando il costruttore capisci a colpo d'occhio da cosa dipende la classe.
* **Quando vuoi sostituire l'implementazione** — Diventa facile sostituire l'implementazione tramite il service container.

## Come usare i Contract

Come si ottiene l'implementazione di un Contract? È molto semplice.

Molti tipi di classi di Laravel — controller, listener di eventi, middleware, job in coda, closure di route e altre — vengono risolti tramite il service container. Per ottenere l'implementazione di un Contract basta "type-hintare" l'interfaccia nel costruttore della classe risolta.

```mermaid theme={null}
flowchart LR
    A["Service provider<br>bind(Interface, Impl)"] --> B["Service container<br>Registrazione del binding"]
    C["Costruttore<br>type hint: Interface"] --> B
    B --> D["Iniezione automatica<br>Risoluzione dell'implementazione dell'interfaccia"]
    D --> E["Istanza concreta<br>sostituibile liberamente"]
```

Ad esempio, guarda il seguente event listener.

```php theme={null}
<?php

namespace App\Listeners;

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

class CacheOrderInformation
{
    /**
     * Crea l'event listener
     */
    public function __construct(
        protected Factory $redis,
    ) {}

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

Quando l'event listener viene risolto, il service container legge il type hint del costruttore e inietta il valore appropriato.

## Creazione di Contract personalizzati

Creare i propri Contract permette di rendere chiare le dipendenze tra i componenti dell'applicazione.

<Steps>
  <Step title="Definisci l'interfaccia">
    Crea l'interfaccia nella directory `app/Contracts`.

    ```php theme={null}
    <?php

    namespace App\Contracts;

    interface PaymentGateway
    {
        /**
         * Effettua un pagamento dell'importo specificato
         */
        public function charge(int $amount, string $token): bool;

        /**
         * Rimborsa un pagamento
         */
        public function refund(string $transactionId): bool;
    }
    ```
  </Step>

  <Step title="Crea la classe di implementazione">
    Crea la classe che implementa il Contract.

    ```php theme={null}
    <?php

    namespace App\Services;

    use App\Contracts\PaymentGateway;

    class StripePaymentGateway implements PaymentGateway
    {
        public function charge(int $amount, string $token): bool
        {
            // Logica di pagamento tramite l'API di Stripe...
            return true;
        }

        public function refund(string $transactionId): bool
        {
            // Logica di rimborso tramite l'API di Stripe...
            return true;
        }
    }
    ```
  </Step>

  <Step title="Collega Contract e implementazione in un service provider">
    Effettua il binding tra Contract e implementazione in un [service provider](/it/service-providers).

    ```php theme={null}
    use App\Contracts\PaymentGateway;
    use App\Services\StripePaymentGateway;

    $this->app->singleton(PaymentGateway::class, StripePaymentGateway::class);
    ```
  </Step>

  <Step title="Ricevi l'iniezione tramite type hint">
    Fai il type hint nel costruttore del controller o di altre classi.

    ```php theme={null}
    <?php

    namespace App\Http\Controllers;

    use App\Contracts\PaymentGateway;
    use Illuminate\Http\Request;

    class OrderController extends Controller
    {
        public function __construct(
            protected PaymentGateway $payment,
        ) {}

        public function store(Request $request)
        {
            $this->payment->charge(
                $request->amount,
                $request->payment_token
            );

            // ...
        }
    }
    ```
  </Step>
</Steps>

Con questo pattern, se in futuro cambi il servizio di pagamento da `Stripe` a un altro provider, ti basta modificare il binding in un solo punto senza toccare il codice del controller.

## Elenco dei Contract principali

Tabella di corrispondenza tra i Contract più usati e le rispettive facade (estratto).

| Contract                                        | Facade corrispondente |
| ----------------------------------------------- | --------------------- |
| `Illuminate\Contracts\Auth\Access\Gate`         | `Gate`                |
| `Illuminate\Contracts\Auth\Factory`             | `Auth`                |
| `Illuminate\Contracts\Bus\Dispatcher`           | `Bus`                 |
| `Illuminate\Contracts\Cache\Factory`            | `Cache`               |
| `Illuminate\Contracts\Cache\Repository`         | `Cache::driver()`     |
| `Illuminate\Contracts\Config\Repository`        | `Config`              |
| `Illuminate\Contracts\Console\Kernel`           | `Artisan`             |
| `Illuminate\Contracts\Container\Container`      | `App`                 |
| `Illuminate\Contracts\Encryption\Encrypter`     | `Crypt`               |
| `Illuminate\Contracts\Events\Dispatcher`        | `Event`               |
| `Illuminate\Contracts\Filesystem\Factory`       | `Storage`             |
| `Illuminate\Contracts\Filesystem\Filesystem`    | `Storage::disk()`     |
| `Illuminate\Contracts\Hashing\Hasher`           | `Hash`                |
| `Illuminate\Contracts\Mail\Mailer`              | `Mail`                |
| `Illuminate\Contracts\Notifications\Dispatcher` | `Notification`        |
| `Illuminate\Contracts\Queue\Factory`            | `Queue`               |
| `Illuminate\Contracts\Queue\Queue`              | `Queue::connection()` |
| `Illuminate\Contracts\Queue\ShouldQueue`        | —                     |
| `Illuminate\Contracts\Redis\Factory`            | `Redis`               |
| `Illuminate\Contracts\Routing\ResponseFactory`  | `Response`            |
| `Illuminate\Contracts\Routing\UrlGenerator`     | `URL`                 |
| `Illuminate\Contracts\Session\Session`          | `Session::driver()`   |
| `Illuminate\Contracts\Translation\Translator`   | `Lang`                |
| `Illuminate\Contracts\Validation\Factory`       | `Validator`           |
| `Illuminate\Contracts\View\Factory`             | `View`                |

Puoi trovare la lista completa dei Contract nel repository [illuminate/contracts](https://github.com/illuminate/contracts).

## Prossimi passi

<Card title="Facade" icon="layer-group" href="/it/facades">
  Approfondisci il funzionamento delle facade e i loro metodi di test.
</Card>


## Related topics

- [Facade](/it/facades.md)
- [Riepilogo delle novità di Laravel 13](/it/blog/laravel-13-new-features.md)
- [Aggiornamenti Laravel di aprile 2026](/it/blog/changelog/202604.md)
- [Support Contracts (Arrayable / Jsonable / Htmlable / Responsable)](/it/advanced/support-contracts.md)
- [Creare un provider personalizzato per l'AI SDK](/it/advanced/ai-sdk-custom-provider.md)