Laravel incluye una herramienta muy práctica para resolver este tipo de escenarios: Cache::remember(). Su objetivo es sencillo: consultar primero si un valor ya existe en caché y, únicamente si no existe o expiró, ejecutar la lógica necesaria para obtenerlo nuevamente.

¿Qué hace Cache::remember()?

La forma general de utilizarlo es la siguiente:

$data = Cache::remember(
    'example.key',
    now()->addHours(24),
    function () {
        return SomeService::getData();
    }
);

Internamente, Laravel sigue una lógica equivalente a esta:

if (Cache::has('example.key')) {
    return Cache::get('example.key');
}

$data = SomeService::getData();

Cache::put(
    'example.key',
    $data,
    now()->addHours(24)
);

return $data;

La ventaja de remember() es que concentra todo ese flujo en una sola instrucción.

¿Dónde guarda Laravel la información?

El lugar donde se almacena depende del cache store configurado en Laravel. Normalmente se define desde el archivo .env.

CACHE_STORE=file

Algunos stores comunes son:

• file: guarda la información en archivos dentro de storage/framework/cache/data.
• database: almacena los valores en una tabla de caché dentro de la base de datos.
• redis: utiliza Redis como almacenamiento de alto rendimiento.
• array: mantiene los valores únicamente durante la ejecución actual, por lo que no persisten entre peticiones.

Esto significa que Cache::remember() no necesariamente guarda información solo en memoria. Con un store persistente como file, database o redis, el dato puede seguir disponible incluso después de que la petición HTTP haya terminado.

Ejemplo práctico: consumir una API externa

Supongamos que una aplicación necesita obtener un catálogo desde una API externa. Si dicho catálogo cambia pocas veces al día, consultarlo nuevamente en cada petición no tendría mucho sentido.

$icons = Cache::remember(
    'iconify.collection.mdi',
    now()->addHours(24),
    function () {
        return $this->fetchCollectionFromApi('mdi');
    }
);

La primera vez que se ejecuta, Laravel consulta la API, guarda el resultado y lo devuelve. Las siguientes peticiones recuperan directamente el valor cacheado hasta que expire.

Aplicación
   ↓
Cache::remember()
   ↓
¿Existe el dato?
   ├── Sí → devolver caché
   └── No → consultar API
              ↓
          guardar resultado
              ↓
          devolver información

¿Cuándo se recomienda usar Cache::remember()?

Es especialmente útil cuando se cumplen tres condiciones: la información se consulta con frecuencia, obtenerla tiene un costo y puede tolerar cierto tiempo sin actualizarse.

• APIs externas: catálogos, metadatos, servicios de terceros o información que no cambia constantemente.
• Consultas pesadas: reportes, agregaciones, conteos o dashboards que implican varias operaciones en base de datos.
• Catálogos relativamente estáticos: países, estados, configuraciones, tipos de registros o listas de referencia.
• Datos procesados: información que necesita varias consultas o transformaciones antes de ser mostrada.
• Contenido muy consultado: datos que son solicitados constantemente por múltiples usuarios.

Ejemplo con una consulta a base de datos

$categories = Cache::remember(
    'categories.enabled',
    now()->addHour(),
    function () {
        return Category::where('enabled', true)
            ->orderBy('name')
            ->get();
    }
);

Mientras el caché siga vigente, Laravel evita ejecutar nuevamente la consulta y entrega el resultado almacenado.

¿Cuándo no conviene usarlo?

No todo debería almacenarse en caché. Existen datos donde la precisión en tiempo real es más importante que el rendimiento.

• Inventario disponible.
• Saldos financieros.
• Estado de una transacción.
• Disponibilidad inmediata de una reservación.
• Información que cambia cada pocos segundos.
• Datos críticos de seguridad sin una estrategia clara de invalidación.

En estos casos, mostrar información desactualizada podría provocar errores funcionales o incluso afectar procesos importantes del sistema.

La importancia del tiempo de expiración

Una de las decisiones más importantes al trabajar con caché es definir cuánto tiempo puede mantenerse vigente la información.

now()->addMinutes(10);
now()->addHour();
now()->addHours(24);
now()->addDay();

No existe un tiempo universal. Depende de qué tan rápido cambie el dato y cuánto tiempo sea aceptable trabajar con una versión anterior.

¿Qué pasa cuando el caché expira?

No necesitas crear un proceso adicional para actualizarlo. Cuando la entrada expira, la siguiente petición que ejecute Cache::remember() volverá a ejecutar el callback, obtendrá una versión nueva y la almacenará nuevamente.

También puedes eliminar manualmente una entrada:

Cache::forget('iconify.collection.mdi');

O limpiar todo el caché de la aplicación mediante Artisan:

php artisan cache:clear

Este último comando debe utilizarse con cuidado porque elimina todas las entradas del store de caché utilizado por la aplicación.

Una regla práctica

¿La información se consulta muchas veces?
        ↓ sí
¿Obtenerla es relativamente costoso?
        ↓ sí
¿Puede tolerar estar desactualizada algunos minutos u horas?
        ↓ sí
Cache::remember() es un buen candidato.

Conclusión

Cache::remember() es una de esas herramientas de Laravel que pueden parecer sencillas, pero generan una mejora importante cuando se utilizan en el escenario adecuado. Reduce consultas repetitivas, evita solicitudes innecesarias a servicios externos y ayuda a mejorar los tiempos de respuesta de una aplicación.

La clave no está en almacenar todo en caché, sino en identificar qué información se consulta constantemente, qué tan costoso es obtenerla y durante cuánto tiempo puede mantenerse sin actualizarse.

En Maria Tech desarrollamos soluciones de software a medida con Laravel y otras tecnologías, buscando que cada sistema sea mantenible, eficiente y preparado para crecer conforme lo requiera el negocio.

Este artículo explica por qué pasa y cómo resolverlo en una línea de Blade, sin agregar procesos de compilación ni dependencias nuevas al proyecto.

Por qué el navegador se queda con la copia vieja

Cuando el navegador descarga https://tusitio.com/js/cart.js, guarda una copia local. La próxima vez que necesite ese archivo, no tiene ninguna razón para volver a pedirlo: la dirección es la misma, así que asume que el contenido también.

Ese comportamiento es deseable. Es lo que hace que tu sitio cargue rápido en la segunda visita. El problema es que el navegador no tiene forma de saber que tú cambiaste el archivo.

La solución conocida es cambiar la dirección cuando cambia el contenido, agregando un parámetro de versión:

<script src="/js/cart.js?v=1.0.0"></script>

Para el navegador, cart.js?v=1.0.0 y cart.js?v=1.0.1 son dos direcciones distintas. Al cambiar el número, descarga de nuevo.

El detalle que hace que esto falle

Escrito así, el número se sube a mano. Y ahí está el punto débil: para que funcione, quien modifica el archivo tiene que acordarse de abrir otro archivo distinto, encontrar la línea correcta y cambiar un dígito, justo en el momento en que su cabeza está en el bug que acaba de arreglar.

Es fácil que se pase por alto, y cuando se pasa, el síntoma aparece mucho después y en la computadora de otra persona. Nadie relaciona una cosa con la otra.

En un proyecto que revisamos hace poco encontramos los tres estados conviviendo: un archivo con ?v=1.0.0, otro con ?v=1.0.2 que llevaba varios cambios sin actualizar, y un tercero igual de crítico sin ningún parámetro.

Vale la pena la distinción: el mecanismo estaba bien planteado. Lo que fallaba era que dependía de un paso manual.

La solución: que el número lo calcule el sistema

PHP puede leer la fecha de última modificación de un archivo con filemtime(). Ese valor cambia solo cuando el archivo cambia. Es exactamente el número de versión que necesitamos.

<script src="{{ asset('js/cart.js') }}?v={{ filemtime(public_path('js/cart.js')) }}"></script>

Al modificar cart.js, su fecha de modificación cambia, el parámetro ?v= cambia y el navegador descarga la copia nueva. Si no lo modificas, el número se mantiene y el navegador sigue usando lo que ya tiene en caché, que es justo lo que queremos.

Sin build. Sin Node. Sin recordar nada.

Agrega la protección contra archivo faltante

filemtime() emite un warning y devuelve false si el archivo no existe. En producción el archivo siempre está, pero si tienes APP_DEBUG=true en local y renombras el archivo un momento, ese warning puede escalar a excepción y tumbarte la página con un mensaje que no apunta al verdadero problema.

Se resuelve así:

<script src="{{ asset('js/cart.js') }}?v={{ @filemtime(public_path('js/cart.js')) ?: '' }}"></script>

La arroba silencia el warning y el ?: deja el parámetro vacío en lugar de imprimir false. El script sigue cargando.

Si tienes varios archivos, usa un helper

Repetir la ruta dos veces por archivo se vuelve incómodo rápido. Una clase pequeña lo resuelve:

<?php

namespace App\View;

class Asset
{
    /**
     * URL del asset con parámetro de versión derivado de su fecha de modificación.
     */
    public static function versioned(string $path): string
    {
        $version = @filemtime(public_path($path)) ?: '';

        return asset($path) . ($version ? '?v=' . $version : '');
    }
}

Y en la plantilla:

<script src="{{ \App\View\Asset::versioned('js/cart.js') }}"></script>
<script src="{{ \App\View\Asset::versioned('js/custom.js') }}"></script>
<link rel="stylesheet" href="{{ \App\View\Asset::versioned('css/custom.css') }}">

Colocarla bajo app/ te ahorra tocar composer.json, porque PSR-4 ya cubre ese directorio. Si prefieres una función global en app/helpers.php, funciona igual, pero recuerda que entonces necesitas registrarla en el autoload y ejecutar composer dump-autoload en cada despliegue.

Cómo comprobar que funciona

No te quedes con que la URL se ve distinta. Verifica que el navegador realmente descargó el archivo.

1. Abre la página y las herramientas de desarrollo, en la pestaña Red.
2. Localiza tu archivo JS y anota el valor de ?v=.
3. Modifica el archivo en el servidor. Si solo quieres probar el mecanismo sin cambiar código, touch public/js/cart.js basta para actualizar su fecha.
4. Recarga con F5, sin vaciar caché a mano.

Deberías ver un ?v= distinto. Pero lo importante es la columna Tamaño: si dice un valor en KB, el archivo se descargó; si dice “(memory cache)” o “(disk cache)”, se sirvió de la caché y algo no funcionó.

Desde la consola también puedes verificarlo:

performance.getEntriesByType('resource')
  .filter(r => r.name.includes('cart.js'))
  .map(r => ({ url: r.name, bytes: r.transferSize, deCache: r.transferSize === 0 }));

Si transferSize es mayor que cero, el archivo vino de la red.

Comprueba también que al modificar un archivo solo cambie el parámetro de ese archivo. Cada uno lleva su propio control, y eso evita descargas innecesarias de los demás.

Un detalle sobre tu despliegue

git checkout y git pull no preservan la fecha de modificación de los archivos. Si despliegas así, el parámetro de versión va a cambiar en cada despliegue, incluso para archivos que no tocaste.

No es un problema: el usuario descarga unos KB de más una vez por despliegue y nunca recibe una copia desactualizada, que es lo que importa. Si quieres que el parámetro cambie estrictamente cuando cambia el contenido, sustituye filemtime() por un hash:

$version = substr(md5_file(public_path($path)), 0, 12);

El costo es leer el archivo completo en cada petición en lugar de consultar solo sus metadatos. Para archivos chicos es despreciable; si te preocupa, guárdalo en caché.

¿Y cuándo conviene compilar con Vite o Mix?

Si tu proyecto ya tiene un proceso de compilación funcionando, úsalo: @vite y mix() resuelven esto con un hash del contenido y además te dan minificación y empaquetado.

Esta solución está pensada para un escenario distinto y bastante común: proyectos donde el JavaScript vive en public/, se edita directamente y no hay pipeline montado. Ahí, incorporar los archivos a un proceso de compilación es una migración con su propio trabajo y sus propios riesgos, mientras que el problema de la caché es urgente hoy.

Un punto a considerar antes de decidirte por compilar: mix() lanza una excepción si el manifiesto está desincronizado con los archivos. Si esa llamada vive en una plantilla compartida, un despliegue sin compilar no te rompe una sección, te deja el sitio entero en blanco. Vale la pena tenerlo previsto en tu proceso de despliegue.

Las dos soluciones pueden convivir. Puedes resolver la caché hoy con esta línea y migrar a un pipeline completo cuando el proyecto lo pida, sin prisa y con todos los assets a la vez.

Resumen

• Agrega ?v={{ @filemtime(public_path($ruta)) ?: '' }} a tus etiquetas de script y estilo.
• Si son varios archivos, encapsúlalo en un helper bajo app/.
• Verifica en la pestaña Red que el archivo se descargue, no solo que la URL cambie.
• Revisa si tienes otros mecanismos que dependan de un paso manual: son los que fallan en silencio.

En este artículo vamos a ver por qué vale la pena dedicarles pruebas propias, qué conviene verificar exactamente, y cómo escribirlas y ejecutarlas paso a paso. Los ejemplos usan Eloquent, el ORM de Laravel, pero las ideas se trasladan a cualquier ORM con relaciones.

El problema: las relaciones fallan en silencio

Una relación mal definida no suele lanzar un error inmediato. El código compila, la aplicación arranca, y todo parece funcionar hasta que, en algún punto, una consulta devuelve una colección vacía donde debería haber datos, o carga el registro equivocado.

El caso más común aparece cuando el nombre de la clave foránea no sigue la convención que el ORM espera. Eloquent asume un patrón de nombres por defecto: para una relación hacia una tabla documentos, busca una columna documento_id. Si tu base de datos usa otra convención, el ORM buscará una columna que no existe y la relación devolverá vacío, sin quejarse.

Este tipo de fallo es especialmente traicionero porque no se manifiesta donde está el error, sino mucho más adelante, en una vista que no muestra datos o en un reporte con totales incompletos. Una prueba de relación lo atrapa en el acto.

Dónde vive la prueba

En Laravel, las pruebas viven en el directorio tests/, dividido en dos carpetas:

• tests/Unit/ para pruebas que no tocan la base de datos.
• tests/Feature/ para las que sí.

Las pruebas de relaciones van en tests/Feature/, porque necesitan crear registros y consultarlos.

Para crear el archivo:

php artisan make:test DocumentoRelacionesTest

Eso genera tests/Feature/DocumentoRelacionesTest.php.

El esqueleto de la clase

<?php

namespace Tests\Feature;

use App\Models\Documento;
use App\Models\Impuesto;
use App\Models\LineaDeDetalle;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class DocumentoRelacionesTest extends TestCase
{
    use RefreshDatabase;

    // Aquí van los casos
}

RefreshDatabase es la pieza clave: ejecuta las migraciones antes de la suite y envuelve cada prueba en una transacción que se revierte al terminar. Así cada caso arranca con una base limpia y no puedes ensuciar datos reales por accidente.

Cada caso es un método público cuyo nombre empieza con test, o que lleva el atributo #[Test] si prefieres nombres sin prefijo.

Los cuatro casos que conviene cubrir

1. Que la relación carga en ambos sentidos

Las relaciones tienen dos extremos y ambos pueden estar mal definidos de forma independiente. Si un padre tiene muchos hijos, verifica que desde el padre llegas a todos sus hijos, y que desde un hijo llegas a su padre.

Aquí es donde las factories hacen el trabajo pesado. Una factory es una receta para crear registros de prueba con valores realistas y, bien configurada, encadena automáticamente la creación de los registros de los que depende:

public function test_la_linea_llega_a_su_documento()
{
    // Crea la línea y, de forma automática, su documento padre
    $linea = LineaDeDetalle::factory()->create();

    $this->assertNotNull($linea->documento);
    $this->assertSame($linea->id_documento, $linea->documento->id);
}

public function test_el_documento_ve_todas_sus_lineas()
{
    $documento = Documento::factory()->create();

    LineaDeDetalle::factory()->count(3)->create([
        'id_documento' => $documento->id,
    ]);

    $this->assertCount(3, $documento->lineas);
}

Nota el fresh() que no aparece aquí y sí en otros casos: $documento->lineas se carga por primera vez en el momento de la aserción, así que todavía no hay nada en caché. Si hubieras accedido a la relación antes de crear las líneas, Eloquent devolvería la colección vacía que ya tenía guardada.

2. Que la carga anticipada funciona

La carga anticipada, o eager loading, evita el problema de las N+1 consultas: en lugar de una consulta por cada registro relacionado, se hacen dos en total. Es fácil creer que la tienes y que no esté surtiendo efecto.

La forma de comprobarlo es contar las consultas que realmente se ejecutan:

use Illuminate\Support\Facades\DB;

public function test_la_carga_anticipada_evita_consultas_por_cada_linea()
{
    Documento::factory()->count(5)->hasLineas(3)->create();

    DB::enableQueryLog();

    Documento::with('lineas')->get()->each(
        fn ($documento) => $documento->lineas->count()
    );

    // Una consulta para documentos, una para todas las líneas
    $this->assertCount(2, DB::getQueryLog());
}

Si quitas el with('lineas'), esta prueba falla con seis consultas en vez de dos. Esa es la señal de que la aserción está midiendo lo que crees.

3. Que el borrado se comporta como esperas

Si configuraste que al borrar un padre se borren sus hijos en cascada, pruébalo:

public function test_al_borrar_el_documento_se_borran_sus_lineas()
{
    $documento = Documento::factory()->hasLineas(2)->create();
    $idsLineas = $documento->lineas->pluck('id');

    $documento->delete();

    foreach ($idsLineas as $id) {
        $this->assertDatabaseMissing('lineas_de_detalle', ['id' => $id]);
    }
}

Aquí hay un detalle que conviene conocer: si la cascada está definida en la base de datos con onDelete('cascade'), el comportamiento depende del motor. Las pruebas de Laravel suelen correr sobre SQLite en memoria por velocidad, y SQLite no aplica claves foráneas a menos que se activen explícitamente. Una prueba que pasa en tu entorno podría no reflejar lo que ocurre en producción si los motores difieren.

Puedes verificar contra qué motor estás corriendo:

php artisan test --filter=test_al_borrar_el_documento -v

Y si quieres que las pruebas usen el mismo motor que producción, configúralo en phpunit.xml:

<env name="DB_CONNECTION" value="mysql"/>
<env name="DB_DATABASE" value="almcns_testing"/>

Es más lento, pero prueba lo que de verdad va a ocurrir.

4. Que los datos de captura histórica se conservan

Este es sutil y muy valioso. A veces guardas una copia de un dato en el momento de una transacción, por ejemplo el nombre y el precio de un producto tal como estaban ese día, en lugar de depender siempre del registro vivo. Una prueba puede confirmar que si el registro original cambia después, la copia guardada conserva su valor:

public function test_la_linea_conserva_el_precio_del_momento_de_captura()
{
    $producto = Producto::factory()->create(['precio' => 100.00]);

    $linea = LineaDeDetalle::factory()->create([
        'id_producto' => $producto->id,
        'precio'      => $producto->precio,
    ]);

    $producto->update(['precio' => 250.00]);

    $this->assertSame('100.00', $linea->fresh()->precio);
    $this->assertSame('250.00', $linea->producto->fresh()->precio);
}

Las dos aserciones juntas son las que dan el valor: confirman que la copia no se movió y que la relación hacia el registro vivo sigue funcionando. Es la diferencia entre un histórico confiable y uno que se reescribe solo.

El fresh() aquí no es decorativo. Sin él estarías consultando el objeto que ya tienes en memoria, no lo que quedó guardado, y la prueba pasaría incluso si la base de datos dijera otra cosa.

Cómo ejecutarlas

Las pruebas se ejecutan en la terminal, desde la raíz del proyecto. No hay nada que abrir en el navegador.

Toda la suite:

php artisan test

Solo tu archivo:

php artisan test tests/Feature/DocumentoRelacionesTest.php

Un solo caso, por nombre:

php artisan test --filter=test_la_linea_conserva_el_precio_del_momento_de_captura

Una salida exitosa se ve así:

   PASS  Tests\Feature\DocumentoRelacionesTest
  ✓ la linea llega a su documento                        0.34s
  ✓ el documento ve todas sus lineas                     0.08s
  ✓ la carga anticipada evita consultas por cada linea   0.11s
  ✓ al borrar el documento se borran sus lineas          0.09s
  ✓ la linea conserva el precio del momento de captura   0.10s

  Tests:    5 passed (12 assertions)
  Duration: 0.72s

Cuando algo falla, la salida te dice qué esperaba y qué obtuvo:

  ⨯ el documento ve todas sus lineas

  Failed asserting that actual size 0 matches expected size 3.

  at tests/Feature/DocumentoRelacionesTest.php:31

Ese “size 0” es exactamente el síntoma del que hablábamos al principio: la relación devuelve vacío sin lanzar ningún error. La diferencia es que ahora aparece en tu terminal en menos de un segundo, y no en un reporte de producción dentro de tres semanas.

Si prefieres no escribir el comando cada vez, puedes dejarlas corriendo en modo observador:

php artisan test --watch

Un consejo que ahorra dolores de cabeza

Si tu base de datos no usa la convención de nombres por defecto del ORM, declara la clave foránea de forma explícita en cada relación. No dependas de que el framework la adivine:

public function lineas()
{
    return $this->hasMany(LineaDeDetalle::class, 'id_documento', 'id');
}

Es un argumento más por relación y elimina de raíz toda una categoría de errores silenciosos.

Una red de seguridad para refactorizaciones

El mayor valor de estas pruebas aparece cuando tienes que modificar la estructura de datos. Agregar tablas, normalizar información que antes estaba mezclada, cambiar cómo se conectan las entidades: son cambios que tocan muchas piezas a la vez y donde es fácil romper una relación sin darte cuenta.

Con un conjunto de pruebas de relaciones en su lugar, cada cambio se valida solo. Si una modificación rompe la conexión entre dos modelos, lo sabes en segundos, no cuando un usuario reporta que un reporte sale vacío. Esa retroalimentación inmediata es lo que convierte una refactorización arriesgada en una rutina controlada.

En resumen

Las relaciones entre modelos son la fontanería de una aplicación: invisibles cuando funcionan, catastróficas cuando fallan. Dedicarles pruebas propias no lleva mucho tiempo, sobre todo apoyándote en factories que preparen los datos, y a cambio obtienes una red de seguridad que atrapa una clase de errores que de otro modo llegarían hasta el usuario final.

La próxima vez que definas una relación, considera escribir junto a ella una prueba breve que confirme que carga bien, en ambos sentidos. Tu yo del futuro, en medio de una refactorización, te lo agradecerá.

Al inicio puede parecer práctico resolver todo dentro del controller, pero con el tiempo esa decisión vuelve más difícil mantener, probar y escalar el proyecto. Por eso conviene separar responsabilidades entre Controllers, Form Requests, Services y Models.

La idea no es complicar la arquitectura, sino poner cada pieza en el lugar correcto.

Resumen rápido

Una forma sencilla de entenderlo es esta:

En otras palabras:

Request
  ↓
Form Request
  ↓
Controller
  ↓
Service
  ↓
Model / Base de datos
  ↓
Response

Qué es un Controller en Laravel

Un controller agrupa la lógica que responde a peticiones HTTP relacionadas con un recurso. Laravel recomienda usarlos para organizar el manejo de solicitudes que, de otra forma, terminarían como closures dentro de las rutas.

El controller debe actuar como coordinador. No debería cargar toda la lógica de negocio del sistema.

Responsabilidades recomendadas de un controller

• Recibir la petición.
• Usar un Form Request para validar.
• Buscar un modelo cuando sea algo simple.
• Llamar un Service cuando haya lógica de negocio.
• Regresar una vista, redirect o respuesta JSON.

Ejemplo de controller limpio

public function update(UpdateProductRequest $request, string $product)
{
    $product = Product::find($product);

    $product = $this->productService->update(
        $product,
        $request->validated()
    );

    return response()->json([
        'success' => true,
        'message' => 'Producto actualizado correctamente.',
        'product' => [
            'id' => $product->id,
            'name' => $product->name,
        ],
    ]);
}

Este controller no sabe todos los detalles de cómo se actualiza el producto. Solo controla el flujo.

Eso lo hace más fácil de leer, mantener y modificar.

Qué es un Form Request

Un Form Request es una clase especializada para validar y autorizar datos de entrada. Laravel permite crear estos archivos para encapsular validación y autorización en un lugar separado del controller.

Esto evita que el controller se llene de reglas como required, exists, max, email, validaciones condicionales o preparación de datos.

Responsabilidades recomendadas de un Form Request

• Validar campos requeridos.
• Validar formatos.
• Validar existencia de registros en base de datos.
• Preparar datos antes de validar.
• Autorizar si el usuario puede ejecutar la acción.

Ejemplo de Form Request

class UpdateProductRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'product_id' => ['required', 'integer', 'exists:products,id'],
            'name' => ['required', 'string', 'max:255'],
            'price' => ['required', 'numeric', 'min:0'],
        ];
    }

    public function authorize(): bool
    {
        return true;
    }
}

El controller ya no necesita preocuparse por esa preparación.

Qué es un Service

Un Service es una clase donde se concentra la lógica de negocio o los procesos importantes del sistema. Aunque Laravel no obliga a crear una carpeta Services, el framework sí facilita este patrón gracias a su Service Container y a la inyección de dependencias.

La pregunta clave para decidir si algo va a un Service es:

¿Esto solo controla una petición HTTP o representa una operación importante del negocio?

Si representa una operación del negocio, normalmente conviene moverlo a un Service.

Responsabilidades recomendadas de un Service

• Crear registros.
• Actualizar registros.
• Eliminar registros.
• Ejecutar transacciones.
• Aplicar reglas de negocio.
• Coordinar varias tablas.
• Calcular importes, descuentos, comisiones o estados.
• Consumir APIs externas.
• Disparar notificaciones, eventos o procesos relacionados.

Ejemplo de Service

class ProductService
{
    public function create(array $data): Product
    {
        return DB::transaction(function () use ($data) {
            return Product::create([
                'name' => $data['name'],
                'description' => $data['description'] ?? null,
                'price' => $data['price'],
                'enabled' => $data['enabled'] ?? true,
            ]);
        });
    }

    public function update(Product $product, array $data): Product
    {
        return DB::transaction(function () use ($product, $data) {
            $product->name = $data['name'];
            $product->description = $data['description'] ?? null;
            $product->price = $data['price'];
            $product->enabled = $data['enabled'] ?? $product->enabled;
            $product->save();

            return $product->fresh();
        });
    }

    public function delete(Product $product): void
    {
        DB::transaction(function () use ($product) {
            $product->delete();
        });
    }
}

Aunque algunos métodos parezcan simples al inicio, tenerlos en un Service permite que crezcan ordenadamente. Hoy un delete() puede borrar un registro; mañana puede validar permisos internos, eliminar relaciones, registrar historial y disparar una notificación.

Qué es un Model en Laravel

Un Model representa una tabla de base de datos dentro de Eloquent. Laravel indica que cada tabla suele tener un modelo correspondiente, y que estos modelos permiten consultar, insertar, actualizar y eliminar registros.

Pero eso no significa que toda la lógica de negocio deba vivir dentro del Model.

Responsabilidades recomendadas de un Model

• Definir la tabla si no sigue la convención.
• Definir campos fillable o guarded.
• Definir relaciones.
• Definir casts.
• Crear accessors y mutators.
• Crear scopes reutilizables.
• Agregar métodos simples propios de la entidad.

Ejemplo de Model

class Product extends Model
{
    protected $fillable = [
        'name',
        'description',
        'price',
        'enabled',
    ];

    protected function casts(): array
    {
        return [
            'price' => 'decimal:2',
            'enabled' => 'boolean',
        ];
    }

    public function scopeEnabled($query)
    {
        return $query->where('enabled', true);
    }

    public function isAvailable(): bool
    {
        return $this->enabled === true;
    }
}

Este tipo de lógica sí pertenece al modelo porque describe el comportamiento directo de la entidad Product.

En cambio, si el proceso implica cobrar, registrar historial, enviar notificaciones y actualizar varias tablas, eso ya debería ir a un Service.

Cuándo usar cada uno

Usa Controller cuando…

• Necesitas recibir una petición HTTP.
• Necesitas devolver una vista.
• Necesitas devolver JSON.
• Necesitas redireccionar.
• La acción solo coordina otras piezas.

public function index()
{
    $products = Product::enabled()
        ->orderBy('name')
        ->paginate(20);

    return view('products.index', compact('products'));
}

Una consulta sencilla para mostrar datos puede quedarse en el controller.

Usa Form Request cuando…

• Hay reglas de validación.
• Hay autorización de la acción.
• Necesitas preparar datos antes de validarlos.
• Quieres evitar que el controller se llene de reglas.

public function rules(): array
{
    return [
        'name' => ['required', 'string', 'max:255'],
        'email' => ['required', 'email'],
    ];
}

Usa Service cuando…

• La acción crea, actualiza o elimina información importante.
• La acción toca varias tablas.
• La lógica se reutilizará desde varios lugares.
• Hay transacciones.
• Hay integración con APIs externas.
• Hay reglas de negocio.

$order = $this->orderService->create($request->validated());

Usa Model cuando…

• Necesitas definir relaciones.
• Necesitas casts.
• Necesitas scopes.
• Necesitas accessors o mutators.
• Necesitas métodos simples de la entidad.

public function scopeEnabled($query)
{
    return $query->where('enabled', true);
}

Ejemplo completo: creación de una orden

Supongamos que tenemos un sistema donde un cliente puede crear una orden. La orden debe guardar productos, calcular total, registrar pagos pendientes y devolver una respuesta.

Si todo se mete en el controller, el método puede volverse enorme. Una mejor separación sería:

Ruta

Route::post('/orders', [OrderController::class, 'store'])
    ->name('orders.store');

Controller

class OrderController extends Controller
{
    public function __construct(
        private readonly OrderService $orderService
    ) {}

    public function store(StoreOrderRequest $request)
    {
        $order = $this->orderService->create($request->validated());

        return response()->json([
            'success' => true,
            'message' => 'Orden creada correctamente.',
            'order' => [
                'id' => $order->id,
                'total' => $order->total,
            ],
        ]);
    }
}

Form Request

class StoreOrderRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'customer_name' => ['required', 'string', 'max:255'],
            'items' => ['required', 'array', 'min:1'],
            'items.*.product_id' => ['required', 'integer', 'exists:products,id'],
            'items.*.quantity' => ['required', 'integer', 'min:1'],
        ];
    }
}

Service

class OrderService
{
    public function create(array $data): Order
    {
        return DB::transaction(function () use ($data) {
            $order = Order::create([
                'customer_name' => $data['customer_name'],
                'total' => 0,
                'status' => 'pending',
            ]);

            $total = 0;

            foreach ($data['items'] as $item) {
                $product = Product::findOrFail($item['product_id']);
                $subtotal = $product->price * $item['quantity'];

                $order->items()->create([
                    'product_id' => $product->id,
                    'quantity' => $item['quantity'],
                    'unit_price' => $product->price,
                    'subtotal' => $subtotal,
                ]);

                $total += $subtotal;
            }

            $order->update([
                'total' => $total,
            ]);

            return $order->fresh();
        });
    }
}

Model

class Order extends Model
{
    protected $fillable = [
        'customer_name',
        'total',
        'status',
    ];

    protected function casts(): array
    {
        return [
            'total' => 'decimal:2',
        ];
    }

    public function items()
    {
        return $this->hasMany(OrderItem::class);
    }

    public function isPending(): bool
    {
        return $this->status === 'pending';
    }
}

Con esta estructura, cada clase tiene una responsabilidad clara.

El controller no calcula totales. El Form Request no guarda datos. El Service no genera respuestas HTTP. El Model no se encarga de coordinar todo el proceso.

Errores comunes al separar responsabilidades

1. Crear Services para todo

No todas las acciones necesitan un Service. Si solo vas a mostrar una vista con una consulta sencilla, el controller puede hacerlo.

2. Meter validaciones en el Service

La validación de entrada normalmente debe vivir en un Form Request. El Service debe recibir datos ya validados y ejecutar el proceso.

3. Regresar respuestas HTTP desde el Service

El Service no debería regresar response()->json() ni redirects. Eso le corresponde al controller.

4. Convertir el Model en una clase gigante

El Model debe representar la entidad, pero no coordinar procesos completos del sistema. Si una operación toca varias entidades o APIs externas, probablemente debe vivir en un Service.

5. No usar transacciones en procesos críticos

Cuando una operación crea o actualiza varios registros relacionados, conviene usar transacciones para evitar datos incompletos si algo falla a mitad del proceso.

Regla práctica para proyectos Laravel

Una convención sencilla para mantener el orden es esta:

Si una acción crea, actualiza o elimina información importante de la base de datos, o representa un proceso del negocio, la lógica principal debe ir en un Service.

Esto no significa que el controller nunca pueda consultar modelos. Para listados simples, vistas de edición o pantallas informativas, puede ser totalmente válido.

Pero cuando el método empieza a tener transacciones, ciclos, cálculos, integraciones, actualizaciones en varias tablas o condiciones del negocio, es momento de mover esa lógica a un Service.

Guía rápida

Conclusión

Separar Controllers, Form Requests, Services y Models no es solo una cuestión de estilo. Es una forma de mantener proyectos Laravel más claros, escalables y fáciles de modificar.

Un controller debe controlar el flujo de la petición. Un Form Request debe validar y preparar datos. Un Service debe ejecutar la lógica de negocio. Un Model debe representar la entidad y su relación con la base de datos.

La meta no es crear más archivos sin razón, sino evitar que una sola clase tenga demasiadas responsabilidades.

Cuando cada pieza cumple su función, el código se vuelve más fácil de leer, probar y mantener.

Fuentes consultadas

• Laravel Documentation: Controllers
• Laravel Documentation: Form Request Validation
• Laravel Documentation: Preparing Input for Validation
• Laravel Documentation: Service Container
• Laravel Documentation: Eloquent ORM

En este artículo explicaremos de forma práctica cuándo usar GET, cuándo usar POST y por qué no todas las acciones deberían ejecutarse desde un simple enlace.

La regla básica

Una forma sencilla de verlo es la siguiente:

GET  → consultar, mostrar o leer información.
POST → enviar información, ejecutar acciones o modificar el estado del sistema.

Esta diferencia es importante porque no todos los accesos a una URL deberían tener consecuencias dentro del sistema. Una ruta que solamente muestra información puede trabajar con GET. En cambio, una ruta que guarda, actualiza, elimina o dispara un proceso debería utilizar POST u otro método apropiado.

Cuándo usar GET

El método GET se utiliza principalmente para consultar información. Es decir, cuando el usuario entra a una URL y espera ver datos, una página, un listado o un formulario, pero sin modificar nada en el sistema.

Ejemplos comunes de rutas que sí pueden usar GET:

• Mostrar el listado de productos.
• Ver el detalle de un pedido.
• Abrir un formulario de registro.
• Consultar reportes.
• Filtrar información en una tabla.
• Mostrar una pantalla de configuración.

Ejemplo genérico en Laravel:

Route::get('/admin/productos', [ProductController::class, 'index'])
    ->name('admin.products.index');

En este caso, la ruta solamente muestra información. No guarda datos, no elimina registros y no dispara procesos internos. Por eso GET es adecuado.

Cuándo usar POST

El método POST se utiliza cuando el usuario va a enviar información o cuando una acción puede modificar el estado de la aplicación.

Ejemplos comunes de acciones que deberían usar POST:

• Guardar un producto.
• Crear un pedido.
• Registrar un cliente.
• Enviar un formulario.
• Ejecutar una sincronización.
• Procesar información externa.
• Generar una acción administrativa.

Ejemplo genérico:

Route::post('/admin/productos', [ProductController::class, 'store'])
    ->name('admin.products.store');

Aquí la ruta recibe información y crea un nuevo registro. Por lo tanto, usar POST es lo correcto.

¿Y si no estoy enviando parámetros?

Una duda común aparece cuando tenemos un botón que no envía datos visibles, pero sí ejecuta una acción. Por ejemplo:

• Sincronizar productos.
• Procesar pedidos pendientes.
• Actualizar inventario.
• Ejecutar una tarea interna.

En estos casos podría parecer práctico usar un enlace con href y una ruta GET, porque no estamos enviando campos de formulario. Sin embargo, la decisión no depende solamente de si enviamos parámetros, sino de lo que ocurre cuando se visita la URL.

Si al abrir la URL se ejecuta un proceso, se modifica información o se cambia el estado del sistema, entonces no debería ser GET. Debería ser POST.

Ejemplo: ejecutar una sincronización

Supongamos que tenemos una aplicación administrativa y queremos agregar un botón para sincronizar información con un servicio externo.

Una opción incorrecta sería hacerlo así:

<a href="/admin/sincronizar-productos" class="btn btn-primary">
    Sincronizar productos
</a>

Y definir la ruta como GET:

Route::get('/admin/sincronizar-productos', [SyncController::class, 'syncProducts']);

El problema es que esa URL ejecuta un proceso. No solo muestra información. Por lo tanto, puede activarse accidentalmente si el usuario recarga la página, abre el enlace en otra pestaña, el navegador intenta previsualizarlo o incluso si algún rastreador accede a esa URL.

La forma más adecuada sería usar una ruta POST:

Route::post('/admin/sincronizar-productos', [SyncController::class, 'syncProducts'])
    ->name('admin.products.sync');

Y ejecutarla desde un formulario:

<form action="{{ route('admin.products.sync') }}" method="POST">
    @csrf

    <button type="submit" class="btn btn-primary">
        Sincronizar productos
    </button>
</form>

Aunque el formulario no envíe campos adicionales, el uso de POST comunica correctamente que se trata de una acción, no de una simple consulta.

Por qué evitar GET para acciones importantes

Usar GET para ejecutar acciones puede provocar varios problemas:

• La acción puede ejecutarse accidentalmente al recargar la página.
• La URL puede compartirse o abrirse sin intención.
• Un navegador puede intentar previsualizar o precargar el enlace.
• Un bot o rastreador podría visitar la ruta.
• No se aprovecha la protección CSRF de la misma manera que con formularios POST.
• Se rompe la semántica de la aplicación, porque una consulta termina modificando el sistema.

Por eso, aunque usar GET pueda parecer más cómodo visualmente, no siempre es la opción correcta.

La importancia del CSRF

En frameworks como Laravel, los formularios POST suelen incluir un token CSRF para validar que la petición realmente fue generada desde la aplicación y no desde un sitio externo.

Ejemplo:

<form action="{{ route('admin.products.sync') }}" method="POST">
    @csrf

    <button type="submit">
        Ejecutar sincronización
    </button>
</form>

La directiva @csrf genera un token oculto que Laravel verifica al recibir la solicitud. Esto ayuda a proteger acciones sensibles como guardar información, eliminar registros o ejecutar procesos administrativos.

¿Qué pasa si el formulario afecta el diseño?

En ocasiones se evita usar un formulario porque visualmente no encaja bien dentro de un grupo de botones o dentro de una interfaz administrativa. Sin embargo, ese es un problema de presentación, no de arquitectura.

Podemos mantener el método correcto y ajustar el diseño con CSS:

<div class="btn-group" role="group">
    <a href="{{ route('admin.products.index') }}" class="btn btn-secondary">
        Regresar
    </a>

    <form action="{{ route('admin.products.sync') }}" method="POST" class="m-0 d-inline">
        @csrf
        <button type="submit" class="btn btn-primary">
            Sincronizar
        </button>
    </form>
</div>

También puede resolverse con una petición AJAX usando fetch, manteniendo el método POST y enviando el token CSRF en los encabezados.

<button type="button" id="btn-sync" class="btn btn-primary">
    Sincronizar
</button>

<script>
document.getElementById('btn-sync').addEventListener('click', function () {
    fetch('/admin/sincronizar-productos', {
        method: 'POST',
        headers: {
            'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content,
            'Accept': 'application/json'
        }
    });
});
</script>

Lo importante es no cambiar a GET solo porque estéticamente es más cómodo usar un enlace.

GET no debe tener efectos secundarios

Una buena práctica es que las rutas GET no tengan efectos secundarios importantes. Es decir, visitar una URL con GET no debería crear registros, eliminar información, actualizar inventario ni ejecutar procesos internos.

Por ejemplo, estas rutas deberían evitarse:

GET /admin/eliminar-producto/10
GET /admin/procesar-pedidos
GET /admin/sincronizar-inventario
GET /admin/ejecutar-comando

Aunque técnicamente puedan funcionar, no son una buena práctica porque una simple visita a la URL puede cambiar el estado del sistema.

Entonces, ¿cuándo usar cada uno?

Más allá de GET y POST

En aplicaciones modernas también es común utilizar otros métodos HTTP:

• PUT: para actualizar completamente un recurso.
• PATCH: para actualizar parcialmente un recurso.
• DELETE: para eliminar un recurso.

Sin embargo, en formularios HTML tradicionales normalmente se trabaja con GET y POST. Frameworks como Laravel permiten simular métodos como PUT, PATCH o DELETE mediante campos ocultos.

<form action="{{ route('admin.products.destroy', $product) }}" method="POST">
    @csrf
    @method('DELETE')
    <button type="submit">
        Eliminar producto
    </button>
</form>

Esto permite mantener una estructura más clara y alineada con las buenas prácticas de desarrollo web.

Ejemplo práctico de flujo correcto

Supongamos que tenemos un módulo de pedidos y necesitamos estas acciones:

GET    /admin/pedidos              → Mostrar pedidos
GET    /admin/pedidos/15           → Ver detalle del pedido
GET    /admin/pedidos/create       → Mostrar formulario
POST   /admin/pedidos              → Guardar pedido
POST   /admin/pedidos/sincronizar  → Ejecutar sincronización
DELETE /admin/pedidos/15           → Eliminar pedido

Este tipo de estructura permite entender rápidamente qué hace cada ruta y qué impacto tiene dentro de la aplicación.

Conclusión

Elegir entre GET y POST no debería depender únicamente de si enviamos parámetros o de qué opción se ve mejor en la interfaz. La decisión debe basarse en la intención de la ruta.

Si la ruta solo consulta o muestra información, GET es correcto. Si la ruta guarda, modifica, elimina o ejecuta un proceso dentro del sistema, entonces debe usarse POST u otro método adecuado.

En proyectos reales, esta diferencia ayuda a construir aplicaciones más seguras, ordenadas y fáciles de mantener. Además, evita que acciones importantes se ejecuten accidentalmente desde una URL que debería ser únicamente de consulta.

La interfaz siempre se puede ajustar con CSS o JavaScript, pero la intención técnica de una ruta debe mantenerse clara desde el diseño de la aplicación.

Mantener actualizado el inventario entre un sistema interno y una plataforma externa es una tarea clave para cualquier negocio que vende productos en distintos canales. Cuando el stock no se sincroniza correctamente, pueden aparecer problemas como ventas sin existencia, información desactualizada o diferencias entre lo que ve el cliente y lo que realmente existe en almacén.

El reto de sincronizar inventario

En muchos sistemas, el inventario principal se administra desde una aplicación interna. Esta aplicación puede controlar productos, almacenes, existencias, movimientos, pedidos y configuraciones propias del negocio.

Por otro lado, una plataforma externa puede funcionar como canal de venta, catálogo público o punto de contacto con los clientes. El problema aparece cuando el stock cambia dentro del sistema interno, pero esa actualización no llega de inmediato a la plataforma externa.

Esto puede provocar que un producto aparezca disponible cuando realmente ya no hay existencias, o que el equipo operativo tenga que corregir manualmente la información en más de un lugar.

Por eso es importante diseñar un proceso de sincronización que permita mantener ambos sistemas alineados.

Definir una fuente principal de información

Antes de implementar la sincronización, es necesario definir qué sistema será la fuente principal del stock.

En la mayoría de los casos, el sistema interno debe ser la fuente confiable, ya que ahí se registran los movimientos reales de inventario. La plataforma externa solo debería recibir el dato actualizado.

Este principio evita conflictos como:

• Actualizar stock desde dos lugares diferentes.
• Sobrescribir información correcta con datos desactualizados.
• Perder control sobre qué sistema tiene la información válida.
• Generar diferencias entre almacenes y publicaciones externas.

Cuando el sistema interno es la fuente principal, la sincronización se vuelve más clara: se calcula el stock disponible internamente y después se envía hacia la plataforma externa.

Relacionar productos internos con elementos externos

Un paso fundamental es relacionar cada producto interno con su equivalente en la plataforma externa.

No se debe enviar stock si no existe una relación clara entre ambos elementos. De lo contrario, el sistema podría actualizar el producto equivocado o enviar información incorrecta.

Una relación puede contener datos generales como:

• Identificador del producto interno.
• Identificador del elemento externo.
• Estado de la relación.
• Última fecha de sincronización.
• Stock enviado más recientemente.

Esta relación permite saber qué elementos pueden sincronizarse y cuáles necesitan revisión antes de participar en el proceso.

Obtener el stock correcto

Cuando el sistema interno maneja varios almacenes, no siempre conviene enviar el stock total de todos ellos. En algunos casos, la plataforma externa debe trabajar únicamente con un almacén específico.

Por ejemplo, una empresa puede tener inventario en sucursales, almacenes físicos o puntos de distribución diferentes. La sincronización debe respetar la configuración del negocio y tomar el stock desde el almacén autorizado para ese canal.

También es recomendable validar que el stock enviado nunca sea negativo. Si el sistema interno llegara a tener un valor menor que cero por algún ajuste o movimiento pendiente, lo más seguro es enviar cero a la plataforma externa.

Separar la lógica usando Jobs

En Laravel, una buena práctica es separar este tipo de procesos en Jobs.

Un Job permite ejecutar la sincronización sin cargar toda la lógica dentro del controlador. Esto hace que el código sea más ordenado, más fácil de mantener y más flexible.

El flujo general puede verse así:

Usuario o tarea programada inicia la sincronización
↓
Laravel dispara un Job
↓
El Job busca productos relacionados
↓
Calcula el stock interno
↓
Envía la información al servicio externo
↓
Registra el resultado

Esta estructura permite ejecutar la misma lógica desde distintos puntos, como un botón manual, una tarea programada o un comando de consola.

Usar un servicio para comunicarse con la plataforma externa

La comunicación con la API externa debería estar aislada en una clase de servicio.

Esto evita que el controlador o el Job tengan demasiada responsabilidad. El servicio puede encargarse de preparar la petición, enviar el stock, interpretar la respuesta y devolver un resultado claro.

De forma conceptual, el servicio debería realizar estas tareas:

• Validar que exista una configuración activa.
• Obtener el token o credenciales necesarias.
• Enviar la cantidad disponible a la plataforma externa.
• Revisar si la respuesta fue exitosa.
• Detectar errores conocidos.
• Devolver el resultado al proceso principal.

Separar esta lógica facilita futuras modificaciones, especialmente si la plataforma externa cambia sus reglas, endpoints o formato de respuesta.

Actualizar información local solo cuando la API responda correctamente

Una parte importante del proceso es no asumir que la sincronización fue exitosa solo porque se envió una petición.

La plataforma externa puede rechazar el cambio por varias razones: credenciales inválidas, producto no encontrado, permisos insuficientes, reglas del canal o restricciones sobre ciertos campos.

Por eso, el sistema interno solo debería actualizar su registro local de “último stock sincronizado” cuando la API confirme que la operación fue aceptada.

Esto evita mostrar información incorrecta dentro del sistema administrativo.

Registrar una bitácora de sincronización

Toda integración con servicios externos debería contar con una bitácora.

La bitácora permite saber qué ocurrió en cada intento de sincronización. Esto es útil para auditoría, soporte y diagnóstico de errores.

Una buena bitácora puede registrar información como:

• Fecha del intento.
• Producto interno relacionado.
• Elemento externo actualizado.
• Stock calculado internamente.
• Stock enviado a la plataforma externa.
• Estado de la operación.
• Código de respuesta.
• Mensaje descriptivo del resultado.

Con esta información, el equipo puede saber si una actualización fue exitosa, si la plataforma externa rechazó el cambio o si ocurrió un problema de configuración.

Mostrar la bitácora en el panel administrativo

Guardar la bitácora en la base de datos es útil, pero mostrarla en la interfaz administrativa mejora mucho la experiencia del usuario.

Una pestaña de historial o bitácora permite revisar rápidamente los últimos intentos de sincronización sin entrar directamente a la base de datos.

Esta sección puede mostrar columnas como:

• Fecha.
• Producto.
• Stock interno.
• Stock enviado.
• Estado.
• Código de respuesta.
• Mensaje.

De esta manera, el usuario puede identificar rápidamente si una sincronización fue exitosa o si necesita atención.

Sincronización automática y sincronización manual

Una sincronización puede ejecutarse de forma automática mediante tareas programadas. Esto ayuda a mantener el inventario actualizado sin intervención constante del usuario.

Sin embargo, también es útil contar con una opción manual desde el panel administrativo.

El botón manual no reemplaza el proceso automático, sino que lo complementa. Puede servir cuando el usuario necesita actualizar el stock inmediatamente después de hacer cambios importantes en el inventario o en las relaciones con la plataforma externa.

Para evitar ejecuciones accidentales, conviene mostrar una confirmación antes de iniciar el proceso.

Manejo de errores

No todos los errores significan que la lógica interna esté mal. A veces la plataforma externa rechaza una actualización por sus propias reglas.

Algunos casos comunes son:

• Token expirado.
• Permisos insuficientes.
• Producto externo no encontrado.
• Campo no editable.
• Restricciones por estado del producto.
• Errores temporales del servicio externo.

Por eso es importante que el sistema muestre mensajes claros y registre la respuesta técnica para diagnóstico.

Un mensaje útil para el usuario debe explicar el problema sin saturarlo con detalles técnicos innecesarios.

Buenas prácticas

Al implementar sincronización de stock entre un sistema interno y una plataforma externa, conviene aplicar estas buenas prácticas:

• Definir claramente cuál sistema es la fuente principal del inventario.
• Sincronizar solo productos correctamente relacionados.
• Tomar el stock desde el almacén configurado.
• Evitar enviar cantidades negativas.
• Separar responsabilidades usando controladores, Jobs y servicios.
• Registrar cada intento en una bitácora.
• Actualizar datos locales solo cuando la API confirme éxito.
• Mostrar resultados de sincronización en el panel administrativo.
• Manejar errores de forma clara.
• Mantener una opción manual como apoyo al proceso automático.

Conclusión

Sincronizar stock entre un sistema interno y una plataforma externa no consiste solamente en enviar una cantidad mediante una API. También implica validar relaciones, respetar configuraciones, manejar errores, registrar evidencia y mantener consistencia entre ambos sistemas.

Laravel ofrece herramientas muy útiles para construir este tipo de procesos de forma ordenada, como Jobs, servicios, comandos de consola, tareas programadas y manejo de peticiones HTTP.

Una implementación bien diseñada permite que el sistema interno conserve el control principal del inventario, mientras la plataforma externa recibe actualizaciones confiables y trazables.

El resultado es una integración más segura, más fácil de mantener y más útil para los usuarios que necesitan operar productos en diferentes canales de venta.

Sin embargo, también puede pasar que una rama se cree desde una base incorrecta. Por ejemplo, en lugar de crear una nueva rama desde main, se crea desde otra rama de desarrollo que todavía no está lista para integrarse. Cuando esto ocurre, el Pull Request puede mostrar muchos commits adicionales que no pertenecen realmente al cambio que queremos subir.

El problema

Supongamos que tenemos una rama principal:

main

También existe una rama de desarrollo para una integración grande:

feature/integracion-api

Después se crea una nueva rama para una funcionalidad más pequeña, por ejemplo el registro del costo de envío:

feature/integracion-envios

El detalle es que esta última rama fue creada accidentalmente desde feature/integracion-api y no desde main. Entonces, al intentar crear un Pull Request hacia main, GitHub muestra que se van a aplicar muchos commits adicionales.

En ese punto la señal de alerta es clara: si la funcionalidad era pequeña, pero el Pull Request muestra demasiados commits o archivos que no corresponden, no conviene hacer el merge todavía.

Por qué no era buena idea hacer el merge directo

Si se hacía el merge directo de feature/integracion-envios hacia main, también se podían integrar cambios incompletos de la rama feature/integracion-api. Esto habría mezclado funcionalidades distintas y pudo provocar errores en producción o en el ambiente de pruebas.

El objetivo era integrar únicamente los commits relacionados con el registro del costo de envío, sin arrastrar el trabajo de otra rama.

La solución: crear una rama limpia desde main

La solución fue crear una nueva rama partiendo correctamente desde main y después aplicar únicamente los commits necesarios usando git cherry-pick.

El comando git cherry-pick permite tomar uno o varios commits específicos de otra rama y aplicarlos sobre la rama actual. Esto resulta útil cuando queremos rescatar cambios puntuales sin mezclar todo el historial de la rama original.

1. Actualizar la información del repositorio

Primero se actualiza la información del repositorio remoto:

git fetch origin

Este comando descarga las referencias más recientes de las ramas remotas, sin modificar directamente el código de la rama actual.

2. Cambiar a main y actualizarla

Después se cambia a la rama principal y se actualiza con los últimos cambios disponibles:

git checkout main
git pull origin main

Esto asegura que la nueva rama limpia se cree desde la versión más reciente de main.

3. Crear una nueva rama limpia

Con main actualizada, se crea una nueva rama limpia para la funcionalidad:

git checkout -b feature/integracion-envios-clean

Esta nueva rama ya no tendrá como base la rama de integración grande, sino directamente main.

4. Identificar los commits correctos

El siguiente paso es identificar los commits que realmente corresponden a la funcionalidad de envíos.

git log --oneline origin/feature/integracion-api..origin/feature/integracion-envios

Este comando ayuda a visualizar los commits que existen en la rama de envíos, pero que no forman parte de la rama base desde la que fue creada.

El resultado puede ser algo como:

abc1234 Agrega campo de costo de envío al pedido
def5678 Ajusta cálculo total incluyendo envío

En este ejemplo, esos dos commits serían los únicos que realmente se necesitan aplicar en la rama limpia.

5. Aplicar los commits con cherry-pick

Una vez identificados los commits correctos, se aplican sobre la rama limpia:

git cherry-pick abc1234 def5678

Con esto, Git toma los cambios introducidos por esos commits y los aplica sobre la rama actual, generando nuevos commits con esos mismos cambios.

Si durante el proceso aparecen conflictos, se deben resolver manualmente, agregar los archivos corregidos y continuar el cherry-pick:

git add .
git cherry-pick --continue

Si fuera necesario cancelar el proceso, se puede usar:

git cherry-pick --abort

6. Revisar los cambios antes de subir la rama

Antes de subir la nueva rama, se revisa el estado del repositorio:

git status

También es recomendable revisar qué archivos quedaron modificados:

git diff --name-only main...feature/integracion-envios-clean

La idea es confirmar que la rama limpia solo contiene archivos relacionados con la funcionalidad que se quiere integrar.

7. Subir la rama limpia al repositorio remoto

Una vez revisado todo, se sube la nueva rama a GitHub:

git push -u origin feature/integracion-envios-clean

Después de esto, ya es posible crear un nuevo Pull Request desde la rama limpia hacia main.

8. Crear el Pull Request correcto

En GitHub, el nuevo Pull Request debe quedar configurado de esta forma:

base: main
compare: feature/integracion-envios-clean

Ahora el Pull Request mostrará únicamente los commits necesarios y los archivos relacionados con el registro del costo de envío.

Esto permite hacer una revisión más clara, evitar mezclar funcionalidades y mantener la rama main limpia.

Flujo completo de comandos

El flujo completo quedaría de la siguiente manera:

git fetch origin

git checkout main
git pull origin main

git checkout -b feature/integracion-envios-clean

git log --oneline origin/feature/integracion-api..origin/feature/integracion-envios

git cherry-pick abc1234 def5678

git status

git diff --name-only main...feature/integracion-envios-clean

git push -u origin feature/integracion-envios-clean

Buenas prácticas para evitar este problema

Antes de empezar una nueva funcionalidad, es recomendable seguir este flujo:

git checkout main
git pull origin main
git checkout -b feature/nueva-funcionalidad

También conviene revisar la rama actual antes de crear una nueva:

git branch --show-current

Con este pequeño hábito se evitan muchos problemas al momento de crear Pull Requests.

Conclusión

Cuando una rama se crea desde la base incorrecta, no siempre es necesario rehacer todo el trabajo. Si los cambios están organizados en commits claros, podemos crear una rama limpia desde main y aplicar únicamente los commits necesarios con git cherry-pick.

En este caso, la solución fue evitar el merge directo, crear una nueva rama limpia, aplicar los commits correctos y generar un Pull Request más claro y seguro. Esto permitió integrar la funcionalidad sin arrastrar cambios de otra rama que todavía no estaba lista.

Este tipo de situaciones son comunes en proyectos reales, y aprender a resolverlas correctamente ayuda a mantener un historial limpio, reducir errores y mejorar el flujo de trabajo en equipo.

En este caso, el origen del problema estaba relacionado con Iconify, específicamente con el archivo iconify-icon.js y el uso de IntersectionObserver para renderizar o remover iconos dependiendo de si están visibles en pantalla.

El síntoma

El problema aparece únicamente en páginas con altura considerable, donde era necesario hacer scroll para revisar el contenido. Al avanzar hacia abajo, llegaba un punto en el que la pantalla se quedaba “atorada” y comenzaba a “saltar”, como si intentara regresar a una posición anterior.

Después de realizar un rastreo y de varias pruebas, el comportamiento desaparecía al quitar el archivo:

<script src="/assets/js/iconify-icon.js"></script>

Esto permitió confirmar que el problema no estaba en Bootstrap, DataTables, CSS personalizado ni en el layout principal, sino en la forma en que Iconify estaba administrando los iconos durante el scroll.

Por qué sucede

Algunas versiones de iconify-icon.js usan IntersectionObserver para detectar si un icono está visible dentro del viewport. Cuando el icono sale de pantalla, el script puede remover el SVG renderizado; cuando vuelve a entrar, lo renderiza nuevamente.

El comportamiento problemático se encuentra en una lógica similar a esta:

    this._observer = new IntersectionObserver((entries) => {
        const isVisible = entries.some((entry) => entry.isIntersecting);

        if (isVisible !== this._visible) {
            this._visible = isVisible;
            this._forceRender();
        }
    });
    

Y dentro de _forceRender() puede existir una lógica que elimina el icono del Shadow DOM cuando ya no está visible:

    _forceRender() {
        if (this._visible) {
            this._queueCheck();
        } else {
            const element = getRenderedIcon(this._shadowRoot);

            if (element) {
                this._shadowRoot.removeChild(element);
            }
        }
    }

En teoría, esto busca optimizar el rendimiento. Pero en páginas largas, con muchos iconos y contenido dinámico, puede causar el efecto contrario: cada vez que el usuario hace scroll, el script modifica el DOM, el navegador recalcula layout, el observer vuelve a detectar cambios y se puede producir un ciclo de renderizado/recalculo.

La solución aplicada

La solución fue desactivar ese comportamiento de observación de visibilidad y mantener los iconos renderizados de forma estable. Esto evita que Iconify quite y vuelva a insertar SVGs durante el scroll.

Antes de modificar el archivo, es recomendable hacer un respaldo:

cp public/assets/js/iconify-icon.js public/assets/js/iconify-icon.backup.js

Después, se pueden aplicar los siguientes ajustes dentro del archivo iconify-icon.js.

1. Ajustar connectedCallback()

Busca una función similar a esta:

connectedCallback() {
    this._connected = true;
    this.startObserver();
}

Y cámbiala por:

connectedCallback() {
    this._connected = true;
    this._visible = true;
    this._queueCheck();
}

Con este cambio, al conectar el elemento al DOM, el icono se considera visible y se renderiza sin iniciar el observer.

2. Corregir la lógica de noobserver

En algunas versiones, el manejo del atributo noobserver puede estar invertido. Si encuentras algo similar a esto:

case "noobserver":
    this.hasAttribute("noobserver") ? this.startObserver() : this.stopObserver();
    break;

Cámbialo por:

case "noobserver":
    this.hasAttribute("noobserver") ? this.stopObserver() : this.startObserver();
    break;

Esto hace que, si el elemento tiene el atributo noobserver, el observer se detenga en lugar de iniciarse.

3. Reemplazar startObserver()

Busca el método startObserver(). Normalmente contiene una instancia de IntersectionObserver, similar a esta:

startObserver() {
    if (!this._observer && !this.hasAttribute("noobserver")) {
        try {
            this._observer = new IntersectionObserver((entries) => {
                const isVisible = entries.some((entry) => entry.isIntersecting);

                if (isVisible !== this._visible) {
                    this._visible = isVisible;
                    this._forceRender();
                }
            });

            this._observer.observe(this);
        } catch (error) {
            if (this._observer) {
                try {
                    this._observer.disconnect();
                } catch (error) {}

                this._observer = null;
            }
        }
    }
}

Reemplázalo por una versión simple:

startObserver() {
    this._visible = true;
    this._queueCheck();
}

Este es el cambio principal. El icono se mantiene renderizado y ya no se elimina o reconstruye durante el scroll.

4. Ajustar _forceRender()

Busca una función similar a esta:

_forceRender() {
    if (this._visible) {
        this._queueCheck();
    } else {
        const element = getRenderedIcon(this._shadowRoot);

        if (element) {
            this._shadowRoot.removeChild(element);
        }
    }
}

Y cámbiala por:

_forceRender() {
    this._visible = true;
    this._queueCheck();
}

Con esto se evita que cualquier flujo interno vuelva a remover el SVG del Shadow DOM.

Cómo evitar problemas de caché

Después de modificar el archivo, es importante forzar al navegador a cargar la nueva versión. Una forma sencilla es agregar un parámetro de versión al script:

<script src="/assets/js/iconify-icon.js?v=1.0.2"></script>

También puedes limpiar caché manualmente o compilar nuevamente los assets si el archivo forma parte de un proceso de build.

Alternativa: usar un patch separado

Si no quieres modificar directamente la librería, puedes crear un archivo adicional que se cargue después de iconify-icon.js. Esta opción es útil cuando el archivo original pertenece a una plantilla o paquete de terceros.

<script src="/assets/js/iconify-icon.js"></script>
<script src="/assets/js/iconify-icon-noobserver-patch.js"></script>

Sin embargo, si el problema está dentro de la clase registrada como Web Component, modificar directamente el método dentro del archivo original suele ser más estable, siempre que se haga con respaldo y control de versiones.

Cuándo conviene aplicar esta solución

Este ajuste puede ser útil cuando se cumplen varias de estas condiciones:

• La página tiene muchos iconos generados con <iconify-icon>.
• El problema aparece únicamente en páginas largas con scroll.
• El salto desaparece al quitar iconify-icon.js.
• No existen errores claros en consola.
• El navegador muestra actividad alta de renderizado o recalculado de estilos.

Recomendaciones finales

Antes de modificar una librería de terceros, conviene confirmar que realmente es la causa del problema. Para hacerlo puedes probar lo siguiente:

• Desactivar temporalmente el script sospechoso.
• Probar la misma página con pocos iconos.
• Revisar si el problema aparece solo al hacer scroll.
• Validar que no existan scripts duplicados.
• Hacer respaldo del archivo original antes de editarlo.

En este caso, la solución fue mantener los iconos renderizados y desactivar la observación de visibilidad con IntersectionObserver. Con ello se evita que el navegador entre en un ciclo de recalculado al hacer scroll y la interfaz vuelve a comportarse de forma estable.

Conclusión

Los bugs de scroll pueden ser difíciles de detectar porque no siempre generan errores en consola. Muchas veces el problema no está en el CSS, sino en scripts que modifican el DOM mientras el usuario navega por la página.

Cuando una librería intenta optimizar el renderizado quitando y agregando elementos durante el scroll, puede terminar provocando saltos visuales, congelamientos o recalculados constantes. En interfaces administrativas con muchos iconos, desactivar ese comportamiento puede ser una solución práctica y efectiva.

Este es uno de los problemas más frecuentes durante el desarrollo local y suele estar relacionado con una causa muy específica: la discrepancia de protocolos en la URI de redirección (redirect_uri).

A continuación, veremos por qué ocurre este problema y cómo solucionarlo para que tu flujo de autenticación funcione correctamente tanto en desarrollo como en producción.

El origen del problema: la seguridad en OAuth 2.0

OAuth 2.0 es el estándar utilizado por numerosas plataformas y servicios para permitir que aplicaciones externas accedan a recursos protegidos de forma segura. Durante la configuración de una aplicación, normalmente se debe registrar una o más URI de redirección.

Estas direcciones son utilizadas por el proveedor de autenticación para devolver al usuario a tu aplicación una vez que ha iniciado sesión y autorizado el acceso.

El conflicto suele aparecer debido a la diferencia entre los requisitos de seguridad de la plataforma y las características de un entorno local de desarrollo:

1. Las plataformas exigen HTTPS: Muchos proveedores requieren que la redirect_uri utilice un protocolo seguro (https://) para proteger el intercambio de información sensible.
2. Los entornos locales suelen usar HTTP: Herramientas de desarrollo como Laragon, XAMPP, WAMP o configuraciones locales de servidores web suelen funcionar inicialmente mediante http://.

Cuando la aplicación genera una URL con HTTPS pero el servidor local no está preparado para responder mediante ese protocolo, el navegador no puede establecer la conexión. Por otro lado, si se utiliza HTTP, muchos proveedores rechazarán la solicitud por razones de seguridad o porque la URL no coincide exactamente con la registrada.

La solución en 3 pasos

La clave consiste en lograr que tu entorno local soporte HTTPS y que las URLs generadas por tu aplicación coincidan exactamente con las registradas en el proveedor de autenticación.

Paso 1: Habilitar HTTPS en tu entorno local

Configura un certificado SSL local para que tu aplicación pueda responder mediante HTTPS.

Algunas opciones comunes son:

• Laragon: Permite habilitar certificados SSL locales de forma automática.
• Laravel Valet: Puede generar certificados locales seguros mediante comandos específicos.
• mkcert: Herramienta ampliamente utilizada para crear certificados confiables en entornos de desarrollo.
• Docker o servidores personalizados: Configura certificados SSL dentro del contenedor o servidor correspondiente.

Una vez configurado, tu aplicación debería ser accesible mediante una URL similar a:

https://miaplicacion.local

Paso 2: Generar URLs seguras desde la aplicación

Es importante que la URI de redirección se genere utilizando HTTPS para garantizar que coincida con la configuración registrada en el proveedor.

Por ejemplo, en Laravel:

$redirect_uri = secure_url(route('oauth.callback', [], false));

El objetivo no es utilizar una función específica, sino asegurarse de que la URL enviada al proveedor tenga exactamente el protocolo HTTPS esperado.

Paso 3: Verificar la configuración del proveedor

La URI configurada en el panel del proveedor debe coincidir exactamente con la generada por tu aplicación.

Ejemplos:

• Correcto: https://miaplicacion.local/oauth/callback
• Incorrecto: http://miaplicacion.local/oauth/callback
• Incorrecto: https://miaplicacion.local/oauth/callback/
• Incorrecto: https://www.miaplicacion.local/oauth/callback (si el dominio registrado no incluye www)

Las plataformas suelen realizar comparaciones estrictas, por lo que cualquier diferencia en protocolo, dominio, ruta, mayúsculas o barras finales puede provocar errores de autenticación.

Buenas prácticas adicionales

Además de corregir el problema inmediato, es recomendable seguir estas prácticas:

• Mantener la misma estructura de URLs entre desarrollo, pruebas y producción.
• Utilizar variables de entorno para configurar dominios y rutas de autenticación.
• Evitar construir manualmente las URLs de redirección cuando el framework puede generarlas automáticamente.
• Verificar periódicamente la configuración registrada en los proveedores externos.
• Probar el flujo completo de autenticación antes de desplegar cambios en producción.

Conclusión

La mayoría de los problemas relacionados con OAuth 2.0 en entornos de desarrollo no provienen de errores en el código, sino de diferencias entre la configuración local y los requisitos de seguridad exigidos por los proveedores de autenticación.

Al habilitar HTTPS localmente, generar URLs seguras desde la aplicación y asegurarte de que las URIs registradas coincidan exactamente con las utilizadas en el código, podrás evitar errores de autenticación y contar con un flujo de integración mucho más estable y seguro.

Estos mismos principios aplican a cualquier integración basada en OAuth 2.0, independientemente del proveedor o servicio externo con el que estés trabajando.

En este artículo, exploraremos las mejores prácticas para implementar OAuth 2.0 en Laravel, protegiendo las credenciales de tu aplicación y evitando vulnerabilidades críticas.

¿Por qué no deberías guardar tokens en texto plano?

Cuando trabajas con integraciones de terceros, el flujo de OAuth 2.0 te entrega un access_token y, a menudo, un refresh_token. El error más común en desarrolladores junior es guardar estas cadenas directamente en la base de datos como texto plano.

Si un atacante lograra vulnerar tu base de datos, tendría acceso total a las cuentas de tus clientes en esas plataformas externas. En Laravel, la solución es sumamente sencilla gracias a sus Facades de encriptación.

Al guardar tus credenciales, asegúrate de utilizar la función nativa de Laravel para encriptar los datos sensibles, de manera que solo tu aplicación pueda interpretarlos usando la llave maestra (APP_KEY) de tu entorno.

Creando una arquitectura segura en la Base de Datos

Otro aspecto vital es la separación de responsabilidades. No mezcles la configuración de tus APIs con la tabla general de usuarios de tu sistema.

Lo ideal es diseñar una tabla específica (por ejemplo, api_configurations) que contenga únicamente los datos de autenticación: el App ID, el Secret Key y los tokens. Esto te permite aplicar reglas estrictas de acceso, implementar restricciones de unicidad para evitar duplicados en las configuraciones y aislar la información crítica del resto de la lógica de negocio.

El flujo de autorización y el control de Callbacks

OAuth 2.0 requiere que el usuario sea redirigido a la plataforma externa para dar su consentimiento y luego regrese a tu aplicación a través de una URL de retorno (Callback).

Un buen desarrollador debe blindar esta ruta de retorno. Nunca asumas que la redirección viene con los parámetros correctos. Es indispensable:

• Validar que el código de autorización realmente venga en la URL.
• Implementar validaciones de estado para evitar peticiones redundantes.
• Manejar bloqueos para que un usuario no pueda acceder a rutas de “desconexión” si la cuenta ya ha sido desvinculada previamente.

Conclusión: La seguridad no es opcional

Conectar una API es un logro técnico, pero asegurarla es lo que distingue a un desarrollo amateur de uno profesional. Laravel nos ofrece todas las herramientas necesarias —desde rutas nombradas hasta encriptación nativa y middlewares— para que nuestras integraciones sean robustas y a prueba de balas.