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

> Die vier wichtigsten Contracts aus Illuminate\Contracts\Support, erläutert anhand des offiziellen Quellcodes von Laravel 13.

## Was sind die Support Contracts?

`Illuminate\Contracts\Support` versammelt eine Reihe kleiner, aber wichtiger Interfaces, die überall in Laravel verwendet werden.\
Vor allem `Arrayable`, `Jsonable`, `Htmlable` und `Responsable` sind Basismuster, um Value Objects, DTOs und Response-Objekte natürlich in die bestehenden Laravel-Flüsse einzupassen.

```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["e()-Helper / Blade-Ausgabe"]
    E --> H["Controller-Return / Router::toResponse()"]
```

<Info>
  Die Signaturen basieren auf dem offiziellen Quellcode von Laravel 13.x (`laravel/framework`).
</Info>

## 1) Arrayable

### Interface-Definition

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

### Beispielimplementierung

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

### Verwendung im Laravel-Kern

* `Illuminate\Database\Eloquent\Model` implementiert `Arrayable` und stellt `toArray()` bereit.
* `Illuminate\Http\JsonResponse::setData()` erkennt `Arrayable` und serialisiert per `json_encode($data->toArray(), ...)`.

### Nutzen in der Paketentwicklung

* DTOs und Value Objects erhalten ein einheitliches Format für Controller, Resources und Log-Ausgabe.
* Die Verantwortung für die Umwandlung in ein Array bleibt im Objekt gekapselt.

## 2) Jsonable

### Interface-Definition

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

### Beispielimplementierung

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

### Verwendung im Laravel-Kern

* `Model` implementiert zusätzlich `Jsonable` und liefert `toJson($options = 0)`.
* `JsonResponse::setData()` prüft `Jsonable` bevorzugt und verwendet `toJson()`.

### Nutzen in der Paketentwicklung

* JSON-Strukturen für Audit-Logs oder Webhook-Auslieferungen lassen sich fest definieren.
* Sie überlassen die JSON-Repräsentation nicht `json_encode()`, sondern drücken sie domänenspezifisch aus.

## 3) Htmlable

### Interface-Definition

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

### Beispielimplementierung

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

### Verwendung im Laravel-Kern

* `Illuminate\Support\HtmlString` implementiert `Htmlable`.
* Der Helper `e()` gibt bei einem `Htmlable`-Argument `toHtml()` zurück (ohne erneute Escapes).

### Nutzen in der Paketentwicklung

* Sie erhalten klare Verantwortungs-Grenzen, um HTML-Fragmente sicher an Blade zu übergeben.
* Auch bei `{!! $obj !!}` lässt sich die Ausgabe objektorientiert verwalten.

<Tip>
  Verketten Sie in Klassen, die `Htmlable` implementieren, Nutzereingaben niemals direkt. Nötige Werte sollten Sie mit `e()` escapen und erst dann einbetten.
</Tip>

## 4) Responsable

### Interface-Definition

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

### Beispielimplementierung

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

### Verwendung im Laravel-Kern

* `Illuminate\Routing\Router::toResponse()` prüft zunächst auf `Responsable` und ruft `$response->toResponse($request)` auf.
* `Illuminate\Http\Resources\Json\JsonResource` implementiert `Responsable`, sodass ein Controller direkt `return UserResource::make($user);` schreiben kann.

### Nutzen in der Paketentwicklung

* Statt in Controllern Arrays zusammenzubauen, delegieren Sie die Response-Erzeugung ans Objekt.
* Ein Design, das „DTOs direkt returned", trennt HTTP- von Domänen-Repräsentation.

## Wann welche Implementierung?

<Steps>
  <Step title="Daten in ein Array umwandeln und wiederverwenden">
    `Arrayable` implementieren; die Normalisierungslogik bündelt sich in `toArray()`.
  </Step>

  <Step title="JSON-Repräsentation kontrollieren">
    `Jsonable` implementieren; über `toJson($options)` legen Sie das Ausgabeformat fest.
  </Step>

  <Step title="Als HTML-Fragment behandeln">
    `Htmlable` implementieren; `toHtml()` gibt den Render-String zurück.
  </Step>

  <Step title="Direkt eine HTTP-Response zurückgeben">
    `Responsable` implementieren; die Verantwortung bündelt sich in `toResponse($request)`.
  </Step>
</Steps>

## Weiterführende Seiten

<Columns cols={2}>
  <Card title="Macroable-Trait" icon="puzzle-piece" href="/de/advanced/macroable">
    Lernen Sie das Erweiterungsmuster kennen, um bestehenden Klassen eigene Methoden hinzuzufügen.
  </Card>

  <Card title="Conditionable-Trait" icon="git-branch" href="/de/advanced/conditionable">
    Lernen Sie das Design von Bedingungs-Chains mit `when()` / `unless()`.
  </Card>

  <Card title="tap()-Helper / Tappable" icon="hand-point-up" href="/de/advanced/tap">
    Lernen Sie die Chain-Muster für Seiteneffekte kennen, die den Wert weiter durchreichen.
  </Card>

  <Card title="Dumpable-Trait" icon="bug" href="/de/advanced/dumpable">
    Lernen Sie die Debug-Technik, `dump()` / `dd()` in Objekte einzubetten.
  </Card>
</Columns>


## Related topics

- [Contracts](/de/contracts.md)
- [Einen eigenen Agenten für Boost erstellen](/de/advanced/boost-custom-agent.md)
- [Laravel Boost](/de/boost.md)
- [Deferred Service Provider](/de/advanced/deferred-provider.md)
- [Helfer-Funktionen](/de/helpers.md)