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:
<?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¿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.