Tema 5 · Relaciones Condicionales

5. Colecciones y Relaciones Condicionales con Resource::collection y whenLoaded

Transforma listados masivos y carga relaciones de Eloquent únicamente cuando hayan sido precargadas (Eager Loading) evitando el problema de consultas N+1.

Transformación de Listados con Resource::collection()

Cuando consultas un único elemento utilizas new ProductoResource($producto). Sin embargo, al transformar un listado o colección paginada (Paginator o Collection de Eloquent), se debe utilizar el método estático ProductoResource::collection($productos).

El Peligro del N+1 en APIs y la Solución con whenLoaded

Imagina que cada producto pertenece a una categoría. Si en tu Resource escribes 'categoria' => new CategoriaResource($this->categoria), Eloquent ejecutará una consulta SQL adicional por cada producto listado (el grave problema de consultas N+1).

Laravel soluciona esto con el método condicional whenLoaded():

'categoria' => new CategoriaResource($this->whenLoaded('categoria')),

whenLoaded('categoria') comprueba si el controlador ejecutó un Eager Loading previo (Producto::with('categoria')->get()). Si la relación fue precargada, la incluye en el JSON; si no fue precargada, la omite por completo del JSON sin disparar ninguna consulta extra a la base de datos.

⚡ Inclusión Condicional de Relaciones y Atributos con whenLoaded y when

Uso avanzado de whenLoaded() y when() para optimizar el peso del JSON y las consultas SQL:

app/Http/Resources/ProductoRelacionesResource.php
Solo lectura
<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class ProductoResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'     => $this->id,
            'nombre' => $this->nombre,
            'precio' => (float)$this->precio,

            // Incluir relación 'categoria' SOLO si el controlador usó with('categoria')
            'categoria' => new CategoriaResource($this->whenLoaded('categoria')),

            // Incluir colección de 'comentarios' SOLO si fue precargada
            'comentarios' => ComentarioResource::collection($this->whenLoaded('comentarios')),

            // Incluir un campo sensible únicamente si el usuario autenticado es Administrador
            'costo_proveedor' => $this->when($request->user()?->esAdmin(), (float)$this->costo_compra),
        ];
    }
}

// En el controlador:
// $productos = Producto::with('categoria')->paginate(20);
// return ProductoResource::collection($productos);
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Qué hace la función "$this->whenLoaded('relacion')" dentro de un API Resource de Laravel?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar APIs RESTful con Laravel, Resources & Sanctum y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.