Support Contracts (Arrayable / Jsonable / Htmlable / Responsable)

​

Was sind die Support Contracts?

​

1) Arrayable

​

Interface-Definition

interface Arrayable
{
    public function toArray();
}

​

Beispielimplementierung

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

interface Jsonable
{
    public function toJson($options = 0);
}

​

Beispielimplementierung

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

interface Htmlable
{
    public function toHtml();
}

​

Beispielimplementierung

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.

​

4) Responsable

​

Interface-Definition

interface Responsable
{
    public function toResponse($request);
}

​

Beispielimplementierung

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?

​

Weiterführende Seiten