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

> Explica los cuatro contratos principales de Illuminate\Contracts\Support basándose en el código fuente oficial de Laravel 13.

## Qué son los Support Contracts

`Illuminate\Contracts\Support` reúne interfaces pequeñas pero importantes que Laravel usa en todas partes.
En particular, `Arrayable` / `Jsonable` / `Htmlable` / `Responsable` son los patrones básicos para integrar de forma natural Value Objects, DTOs y objetos de respuesta en los flujos existentes 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() / salida Blade"]
    E --> H["Retorno de controlador / Router::toResponse()"]
```

<Info>
  Las firmas mostradas aquí se basan en el código fuente oficial (`laravel/framework`) de Laravel 13.x.
</Info>

## 1) Arrayable

### Definición de la interfaz

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

### Ejemplo de implementación

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

### Ejemplos en el core de Laravel

* `Illuminate\Database\Eloquent\Model` implementa `Arrayable` y ofrece `toArray()`.
* `Illuminate\Http\JsonResponse::setData()` detecta `Arrayable` y serializa con `json_encode($data->toArray(), ...)`.

### Uso en el desarrollo de paquetes

* Puedes unificar el formato de DTOs y Value Objects en controladores, resources y logs.
* La responsabilidad de la conversión a `array` queda dentro del propio objeto.

## 2) Jsonable

### Definición de la interfaz

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

### Ejemplo de implementación

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

### Ejemplos en el core de Laravel

* `Model` también implementa `Jsonable` y ofrece `toJson($options = 0)`.
* `JsonResponse::setData()` prioriza `Jsonable` y usa su `toJson()`.

### Uso en el desarrollo de paquetes

* Puedes fijar estrictamente la estructura JSON en audit logs y webhooks.
* Explicitas la representación JSON según las necesidades de dominio en vez de delegarla en `json_encode()`.

## 3) Htmlable

### Definición de la interfaz

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

### Ejemplo de implementación

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

### Ejemplos en el core de Laravel

* `Illuminate\Support\HtmlString` implementa `Htmlable`.
* El helper `e()` devuelve `toHtml()` cuando el argumento es `Htmlable` (no vuelve a escapar).

### Uso en el desarrollo de paquetes

* Aclara la frontera de responsabilidad al pasar fragmentos de HTML seguros dentro de Blade.
* Aunque uses `{!! $obj !!}`, es más fácil gestionar la salida con un objeto.

<Tip>
  Dentro de una clase que implementa `Htmlable`, no concatenes datos del usuario directamente: escápalos con `e()` antes de embutirlos.
</Tip>

## 4) Responsable

### Definición de la interfaz

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

### Ejemplo de implementación

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

### Ejemplos en el core de Laravel

* `Illuminate\Routing\Router::toResponse()` detecta primero `Responsable` e invoca `$response->toResponse($request)`.
* `Illuminate\Http\Resources\Json\JsonResource` implementa `Responsable`, por lo que puedes hacer `return UserResource::make($user);` directamente desde un controlador.

### Uso en el desarrollo de paquetes

* Delegas la construcción de la respuesta en un objeto en lugar de armar arrays en el controlador.
* Facilita el diseño «devuelvo el DTO tal cual», separando la representación HTTP de la de dominio.

## Guía para elegir la implementación

<Steps>
  <Step title="Quieres reutilizar los datos como array">
    Implementa `Arrayable` y concentra la lógica de normalización en `toArray()`.
  </Step>

  <Step title="Quieres controlar la representación JSON">
    Implementa `Jsonable` y explicita el formato de salida en `toJson($options)`.
  </Step>

  <Step title="Quieres tratarlo como fragmento HTML">
    Implementa `Htmlable` y devuelve el markup en `toHtml()`.
  </Step>

  <Step title="Quieres devolver directamente una respuesta HTTP">
    Implementa `Responsable` y concentra la responsabilidad en `toResponse($request)`.
  </Step>
</Steps>

## Siguientes lecturas

<Columns cols={2}>
  <Card title="Trait Macroable" icon="puzzle-piece" href="/es/advanced/macroable">
    Aprende el patrón para extender clases existentes con métodos propios.
  </Card>

  <Card title="Trait Conditionable" icon="git-branch" href="/es/advanced/conditionable">
    Diseño de bifurcaciones condicionales con `when()` / `unless()`.
  </Card>

  <Card title="Helper tap() / Tappable" icon="hand-point-up" href="/es/advanced/tap">
    Cadenas que devuelven el valor mientras intercalan efectos colaterales.
  </Card>

  <Card title="Trait Dumpable" icon="bug" href="/es/advanced/dumpable">
    Técnicas de depuración integrando `dump()` / `dd()` en tus objetos.
  </Card>
</Columns>


## Related topics

- [Laravel Boost](/es/boost.md)
- [Contracts (contratos)](/es/contracts.md)
- [Service providers diferidos](/es/advanced/deferred-provider.md)
- [Funciones auxiliares](/es/helpers.md)
- [Service providers](/es/service-providers.md)