> ## 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)

> Découvrez les quatre principaux contrats d'Illuminate\Contracts\Support, à partir du code source officiel de Laravel 13.

## Que sont les Support Contracts

`Illuminate\Contracts\Support` regroupe de petites interfaces essentielles utilisées partout dans Laravel.\
En particulier, `Arrayable` / `Jsonable` / `Htmlable` / `Responsable` sont les patterns de base qui permettent d'insérer naturellement Value Objects, DTO et objets de réponse dans les flux existants de 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() / sortie Blade"]
    E --> H["retour de contrôleur / Router::toResponse()"]
```

<Info>
  Les signatures présentées ici proviennent des sources officielles de Laravel 13.x (`laravel/framework`).
</Info>

## 1) Arrayable

### Définition de l'interface

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

### Exemple d'implémentation

```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,
        ];
    }
}
```

### Utilisations dans le cœur de Laravel

* `Illuminate\Database\Eloquent\Model` implémente `Arrayable` et fournit `toArray()`.
* `Illuminate\Http\JsonResponse::setData()` détecte `Arrayable` et sérialise via `json_encode($data->toArray(), ...)`.

### Intérêt pour le développement de packages

* Uniformiser le format des DTO et Value Objects dans les contrôleurs, ressources, journaux, etc.
* Enfermer dans l'objet la responsabilité de conversion en `array`.

## 2) Jsonable

### Définition de l'interface

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

### Exemple d'implémentation

```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);
    }
}
```

### Utilisations dans le cœur de Laravel

* `Model` implémente également `Jsonable` et fournit `toJson($options = 0)`.
* `JsonResponse::setData()` évalue `Jsonable` en priorité et utilise `toJson()`.

### Intérêt pour le développement de packages

* Fixer strictement la structure JSON pour les journaux d'audit, l'envoi de webhooks, etc.
* Expliciter la représentation JSON métier, sans dépendre du comportement de `json_encode()`.

## 3) Htmlable

### Définition de l'interface

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

### Exemple d'implémentation

```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>";
    }
}
```

### Utilisations dans le cœur de Laravel

* `Illuminate\Support\HtmlString` implémente `Htmlable`.
* Le helper `e()` renvoie `toHtml()` si son argument est un `Htmlable` (sans ré-échapper).

### Intérêt pour le développement de packages

* Clarifier la frontière de responsabilités lors du passage sûr de fragments HTML dans Blade.
* Faciliter la gestion de la sortie par objet, y compris là où on utilise `{!! $obj !!}`.

<Tip>
  Dans une classe implémentant `Htmlable`, ne concaténez pas directement les entrées utilisateur : échappez d'abord les valeurs nécessaires avec `e()`.
</Tip>

## 4) Responsable

### Définition de l'interface

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

### Exemple d'implémentation

```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',
        ]);
    }
}
```

### Utilisations dans le cœur de Laravel

* `Illuminate\Routing\Router::toResponse()` évalue d'abord `Responsable` et appelle `$response->toResponse($request)`.
* `Illuminate\Http\Resources\Json\JsonResource` implémente `Responsable` : vous pouvez faire directement `return UserResource::make($user);` depuis un contrôleur.

### Intérêt pour le développement de packages

* Éviter d'assembler les tableaux dans le contrôleur en déléguant la génération de la réponse à un objet.
* Faciliter le style « je retourne le DTO tel quel », en séparant représentation HTTP et représentation métier.

## Guide de choix des implémentations

<Steps>
  <Step title="Vous voulez transformer en tableau pour réutilisation">
    Implémentez `Arrayable` et concentrez la logique de normalisation dans `toArray()`.
  </Step>

  <Step title="Vous voulez maîtriser la représentation JSON">
    Implémentez `Jsonable` et explicitez le format de sortie dans `toJson($options)`.
  </Step>

  <Step title="Vous voulez manipuler des fragments HTML">
    Implémentez `Htmlable` et retournez la chaîne de rendu depuis `toHtml()`.
  </Step>

  <Step title="Vous voulez retourner directement une réponse HTTP">
    Implémentez `Responsable` et concentrez la responsabilité dans `toResponse($request)`.
  </Step>
</Steps>

## Pages à lire ensuite

<Columns cols={2}>
  <Card title="Trait Macroable" icon="puzzle-piece" href="/fr/advanced/macroable">
    Découvrez le pattern d'extension permettant d'ajouter des méthodes personnalisées aux classes existantes.
  </Card>

  <Card title="Trait Conditionable" icon="git-branch" href="/fr/advanced/conditionable">
    Découvrez la conception de branchement conditionnel avec `when()` / `unless()`.
  </Card>

  <Card title="Helper tap() / Tappable" icon="hand-point-up" href="/fr/advanced/tap">
    Découvrez le pattern de chaînage renvoyant la valeur tout en glissant un effet de bord.
  </Card>

  <Card title="Trait Dumpable" icon="bug" href="/fr/advanced/dumpable">
    Découvrez comment intégrer `dump()` / `dd()` à vos objets pour le débogage.
  </Card>
</Columns>


## Related topics

- [Laravel Boost](/fr/boost.md)
- [Service providers différés](/fr/advanced/deferred-provider.md)
- [Fonctions helper](/fr/helpers.md)
- [Service providers](/fr/service-providers.md)
- [Façades](/fr/facades.md)