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

# Support Contracts (Arrayable / Jsonable / Htmlable / Responsable)

> Guida ai quattro principali contract di Illuminate\Contracts\Support, basata sul codice sorgente ufficiale di Laravel 13.

## Cosa sono i Support Contracts

`Illuminate\Contracts\Support` raccoglie interfacce piccole ma importanti, usate in tutto Laravel.\
In particolare `Arrayable` / `Jsonable` / `Htmlable` / `Responsable` sono i pattern di base per far integrare naturalmente Value Object, DTO e response object nel flusso esistente di Laravel.

```mermaid theme={null}
flowchart TD
    A["Value Object / DTO"] --> B["Arrayable<br>toArray()"]
    A --> C["Jsonable<br>toJson($options = 0)"]
    A --> D["Htmlable<br>toHtml()"]
    A --> E["Responsable<br>toResponse($request)"]
    B --> F["JsonResponse / Eloquent / Collection"]
    C --> F
    D --> G["helper e() / output Blade"]
    E --> H["return del controller / Router::toResponse()"]
```

<Info>
  Le firme mostrate qui fanno riferimento al codice sorgente ufficiale di Laravel 13.x (`laravel/framework`).
</Info>

## 1) Arrayable

### Definizione dell'interfaccia

```php theme={null}
interface Arrayable
{
    public function toArray();
}
```

### Esempio di implementazione

```php theme={null}
use Illuminate\Contracts\Support\Arrayable;

final class Money implements Arrayable
{
    public function __construct(
        public readonly int $amount,
        public readonly string $currency,
    ) {}

    public function toArray(): array
    {
        return [
            'amount' => $this->amount,
            'currency' => $this->currency,
        ];
    }
}
```

### Utilizzo nel core di Laravel

* `Illuminate\Database\Eloquent\Model` implementa `Arrayable` e fornisce `toArray()`
* `Illuminate\Http\JsonResponse::setData()`, se rileva un `Arrayable`, serializza con `json_encode($data->toArray(), ...)`

### Aspetti utili nello sviluppo di pacchetti

* Puoi uniformare il formato di DTO e Value Object in controller, resource e log
* Concentri sull'oggetto stesso la responsabilità della conversione in `array`

## 2) Jsonable

### Definizione dell'interfaccia

```php theme={null}
interface Jsonable
{
    public function toJson($options = 0);
}
```

### Esempio di implementazione

```php theme={null}
use Illuminate\Contracts\Support\Jsonable;

final class ApiPayload implements Jsonable
{
    public function __construct(
        private array $data,
    ) {}

    public function toJson($options = 0): string
    {
        return json_encode([
            'data' => $this->data,
            'generated_at' => now()->toIso8601String(),
        ], $options | JSON_THROW_ON_ERROR);
    }
}
```

### Utilizzo nel core di Laravel

* `Model` implementa anche `Jsonable` e fornisce `toJson($options = 0)`
* `JsonResponse::setData()` privilegia il controllo di `Jsonable` e usa `toJson()`

### Aspetti utili nello sviluppo di pacchetti

* Puoi fissare in modo rigoroso la struttura JSON per audit log e invii webhook
* Puoi esplicitare la rappresentazione JSON che serve al dominio, senza affidarti a `json_encode()`

## 3) Htmlable

### Definizione dell'interfaccia

```php theme={null}
interface Htmlable
{
    public function toHtml();
}
```

### Esempio di implementazione

```php theme={null}
use Illuminate\Contracts\Support\Htmlable;

final class BadgeHtml implements Htmlable
{
    public function __construct(
        private string $label,
    ) {}

    public function toHtml(): string
    {
        $escaped = e($this->label);

        return "<span class=\"badge\">{$escaped}</span>";
    }
}
```

### Utilizzo nel core di Laravel

* `Illuminate\Support\HtmlString` implementa `Htmlable`
* L'helper `e()`, se l'argomento è `Htmlable`, restituisce il risultato di `toHtml()` (senza rieseguire l'escape)

### Aspetti utili nello sviluppo di pacchetti

* Chiarisci il confine di responsabilità quando passi frammenti HTML in modo sicuro dentro Blade
* Anche negli scenari con `{!! $obj !!}` è più semplice gestire l'output come oggetto

<Tip>
  All'interno di una classe che implementa `Htmlable`, non concatenare direttamente input dell'utente: applica `e()` ai valori prima di incorporarli.
</Tip>

## 4) Responsable

### Definizione dell'interfaccia

```php theme={null}
interface Responsable
{
    public function toResponse($request);
}
```

### Esempio di implementazione

```php theme={null}
use Illuminate\Contracts\Support\Responsable;

final class ExportCsvResponse implements Responsable
{
    public function __construct(
        private array $rows,
        private string $filename = 'export.csv',
    ) {}

    /**
     * @param \Illuminate\Http\Request $request
     */
    public function toResponse($request)
    {
        return response()->streamDownload(function () {
            $stream = fopen('php://output', 'w');

            foreach ($this->rows as $row) {
                fputcsv($stream, $row);
            }

            fclose($stream);
        }, $this->filename, [
            'Content-Type' => 'text/csv',
        ]);
    }
}
```

### Utilizzo nel core di Laravel

* `Illuminate\Routing\Router::toResponse()` verifica per prima cosa `Responsable` e chiama `$response->toResponse($request)`
* `Illuminate\Http\Resources\Json\JsonResource` implementa `Responsable`, quindi puoi fare direttamente `return UserResource::make($user);` da un controller

### Aspetti utili nello sviluppo di pacchetti

* Nel controller eviti di comporre array e deleghi la generazione della risposta a un oggetto
* Facilita un design in cui "restituisci direttamente un DTO", separando meglio la rappresentazione HTTP da quella di dominio

## Guida alla scelta

<Steps>
  <Step title="Vuoi convertire i dati in array e riutilizzarli">
    Implementa `Arrayable` e centralizza in `toArray()` la logica di normalizzazione.
  </Step>

  <Step title="Vuoi controllare la rappresentazione JSON">
    Implementa `Jsonable` ed esplicita il formato di output in `toJson($options)`.
  </Step>

  <Step title="Vuoi trattarlo come frammento HTML">
    Implementa `Htmlable` e restituisci la stringa da renderizzare in `toHtml()`.
  </Step>

  <Step title="Vuoi restituire direttamente una risposta HTTP">
    Implementa `Responsable` e concentra la logica in `toResponse($request)`.
  </Step>
</Steps>

## Pagine da leggere successivamente

<Columns cols={2}>
  <Card title="Trait Macroable" icon="puzzle-piece" href="/it/advanced/macroable">
    Impara il pattern di estensione per aggiungere metodi personalizzati a classi esistenti.
  </Card>

  <Card title="Trait Conditionable" icon="git-branch" href="/it/advanced/conditionable">
    Impara a progettare l'inserimento di rami condizionali con `when()` / `unless()`.
  </Card>

  <Card title="Helper tap() / Tappable" icon="hand-point-up" href="/it/advanced/tap">
    Impara il design di catene che intercalano side effect restituendo comunque il valore.
  </Card>

  <Card title="Trait Dumpable" icon="bug" href="/it/advanced/dumpable">
    Impara la tecnica di debug che integra `dump()` / `dd()` negli oggetti.
  </Card>
</Columns>


## Related topics

- [Laravel Boost](/it/boost.md)
- [Creare un agente personalizzato per Boost](/it/advanced/boost-custom-agent.md)
- [Contracts (contratti)](/it/contracts.md)
- [Service provider differiti](/it/advanced/deferred-provider.md)
- [Funzioni helper](/it/helpers.md)