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.

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.

En este artículo veremos cómo migrar la autenticación de un proyecto desde HTTPS con token hacia SSH, cómo validar que la conexión funcione correctamente y qué hacer cuando Git no permite cambiar de rama porque existen archivos locales modificados, como puede pasar con archivos de configuración en Laravel.

El problema: el token de acceso ya venció

Supongamos que tenemos un proyecto Laravel en un servidor de pruebas o demo. Al intentar ejecutar comandos como git fetch, git pull o git checkout, GitHub responde con un error de autenticación porque el token que se usaba anteriormente ya venció.

En muchos casos, aunque ya hayamos creado una llave SSH en el servidor, Git seguirá usando el token anterior si el repositorio todavía tiene configurada una URL remota con HTTPS.

Es decir, crear una llave SSH no cambia automáticamente la forma en que Git se conecta al repositorio. También debemos actualizar la URL remota del proyecto.

1. Revisar la URL remota actual

Primero debemos entrar a la carpeta del proyecto y revisar qué URL remota está usando Git.

cd /ruta/general/del/proyecto

git remote -v

Si la respuesta muestra una URL similar a esta:

origin  https://github.com/usuario/repositorio.git (fetch)
origin  https://github.com/usuario/repositorio.git (push)

significa que el proyecto todavía está usando HTTPS.

En algunos casos, incluso puede aparecer un token dentro de la URL, algo parecido a esto:

origin  https://TOKEN@github.com/usuario/repositorio.git

Ese es el escenario que debemos corregir.

2. Cambiar la URL remota de HTTPS a SSH

Para que Git use la llave SSH, debemos cambiar la URL remota del repositorio usando el comando git remote set-url.

git remote set-url origin git@github.com:usuario/repositorio.git

Este comando cambia el origen del repositorio para que Git deje de usar HTTPS y empiece a usar SSH.

Después podemos verificar nuevamente la configuración:

git remote -v

La salida esperada sería algo como:

origin  git@github.com:usuario/repositorio.git (fetch)
origin  git@github.com:usuario/repositorio.git (push)

3. Probar la conexión SSH con GitHub

Antes de intentar descargar ramas o actualizar el proyecto, conviene probar que la llave SSH realmente esté funcionando.

ssh -T git@github.com

Si la autenticación es correcta, GitHub responderá con un mensaje indicando que la conexión fue exitosa, aunque no permita acceso de shell. Esto es normal.

Una respuesta esperada puede ser similar a:

Hi usuario! You've successfully authenticated, but GitHub does not provide shell access.

Con eso confirmamos que la autenticación SSH ya está funcionando.

4. Descargar información actualizada del repositorio

Una vez configurada la URL SSH, podemos ejecutar:

git fetch origin

Este comando descarga la información actualizada de las ramas remotas sin mezclar cambios todavía en la rama actual.

5. Cambiar a una rama remota

Si necesitamos crear una rama local a partir de una rama remota, podemos usar:

git checkout -b nombre-rama origin/nombre-rama

Sin embargo, en proyectos reales puede aparecer un error indicando que un archivo local tiene cambios y que Git necesita sobrescribirlo para cambiar de rama.

Un caso común en Laravel puede ser un archivo como:

config/app.php

6. ¿Por qué pasa este error?

Git protege los cambios locales para evitar que se pierdan accidentalmente. Si tenemos modificaciones en un archivo y la rama a la que queremos cambiar también modifica ese archivo, Git detiene el proceso.

A veces se intenta usar el comando assume-unchanged para que Git ignore temporalmente un archivo:

git update-index --assume-unchanged config/app.php

Este comando puede ayudar en algunos escenarios locales, pero no es una solución ideal para manejar archivos de configuración modificados en servidores o ambientes de demo.

Además, aunque un archivo esté marcado como assume-unchanged, Git aún puede bloquear operaciones si necesita proteger cambios locales antes de cambiar de rama.

7. Revisar si un archivo está marcado como assume-unchanged

Podemos revisar el estado del archivo con:

git ls-files -v config/app.php

Si el archivo aparece con una letra minúscula al inicio, significa que está marcado como assume-unchanged.

8. Quitar assume-unchanged

Antes de resolver el conflicto, es recomendable quitar esa marca para que Git vuelva a tratar el archivo normalmente.

git update-index --no-assume-unchanged config/app.php

9. Opción segura: guardar temporalmente los cambios con stash

Si necesitamos conservar los cambios locales del archivo, podemos guardarlos temporalmente con git stash.

git stash push -m "Backup config app" -- config/app.php

Después ya podemos intentar cambiar de rama:

git checkout -b nombre-rama origin/nombre-rama

Y si necesitamos recuperar los cambios guardados:

git stash pop

Si al recuperar los cambios aparecen conflictos, deberán resolverse manualmente.

10. Opción rápida: descartar cambios locales

Si los cambios locales no son importantes, podemos descartarlos.

git restore config/app.php

Después intentamos nuevamente cambiar de rama:

git checkout -b nombre-rama origin/nombre-rama

Esta opción debe usarse con cuidado, porque elimina los cambios locales del archivo.

11. Mejor práctica en Laravel: usar .env para configuración por ambiente

En Laravel, lo más recomendable es evitar modificar archivos como config/app.php directamente en cada servidor. Si una configuración cambia dependiendo del ambiente, lo ideal es manejarla desde el archivo .env.

Por ejemplo, en lugar de dejar un valor fijo dentro de config/app.php, podemos leerlo desde una variable de entorno:

'custom_product' => env('APP_CUSTOM_PRODUCT', false),

Y en el archivo .env del servidor:

APP_CUSTOM_PRODUCT=true

De esta manera cada ambiente puede tener su propia configuración sin modificar archivos versionados en Git.

12. Flujo recomendado completo

Un flujo seguro para este tipo de situación sería:

cd /ruta/general/del/proyecto

git remote -v

git remote set-url origin git@github.com:usuario/repositorio.git

git remote -v

ssh -T git@github.com

git fetch origin

git update-index --no-assume-unchanged config/app.php

git stash push -m "Backup config app" -- config/app.php

git checkout -b nombre-rama origin/nombre-rama

Si después necesitamos recuperar los cambios locales:

git stash pop

Conclusión

Cuando un proyecto deja de autenticarse con GitHub porque venció un access token, una buena solución es migrar la conexión del repositorio a SSH. Para que esto funcione, no basta con crear la llave SSH: también debemos cambiar la URL remota del repositorio.

Además, si Git bloquea un cambio de rama por archivos modificados, debemos decidir si queremos conservar esos cambios con git stash o descartarlos con git restore.

En proyectos Laravel, la recomendación más limpia es mantener los archivos de configuración versionados sin modificaciones locales y mover los valores específicos de cada ambiente al archivo .env. Esto evita conflictos, mejora el flujo de despliegue y reduce errores al trabajar con ramas en Git.

Si necesitas ayuda para crear un proyecto de software en Maria Tech contamos con los expertos para apoyarte.

Sin embargo, cuando el formulario se envía por medio de Ajax, especialmente desde modales o componentes dinámicos, surge una duda común: ¿cómo devolvemos los errores de validación en formato JSON sin dejar de usar la estructura nativa de Laravel?

En este artículo veremos una forma práctica de trabajar con Request validation con formularios Ajax, respuestas JSON y códigos HTTP correctos.

El problema común

En un formulario tradicional, si la validación falla, Laravel redirige automáticamente al usuario a la página anterior y muestra los errores en la vista.

Pero cuando usamos Ajax, no queremos una redirección. Queremos una respuesta JSON que podamos procesar desde JavaScript para mostrar los errores dentro de un modal, un toast o una alerta.

Una solución rápida suele ser hacer la validación directamente en el controlador:

$validator = Validator::make($request->all(), $rules, $messages);

if ($validator->fails()) {
    return response()->json([
        'success' => false,
        'errors' => $validator->errors()->all(),
    ], 422);
}

Aunque esto funciona, tiene una desventaja importante: la validación queda mezclada dentro del controlador. Conforme el proyecto crece, esto vuelve el código más difícil de mantener.

La mejor opción: seguir usando Form Request

Laravel permite seguir usando Form Requests aun cuando el formulario se envía por Ajax. Lo único que necesitamos es personalizar la respuesta cuando la validación falla.

Primero, podemos crear un Form Request:

php artisan make:request Admin/User/StoreUserRequest

Luego definimos las reglas de validación:

namespace App\Http\Requests\Admin\User;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;

class StoreUserRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'last_name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'email', 'max:255', Rule::unique('users', 'email')],
            'phone' => ['nullable', 'digits:10'],
            'id_profile_type' => ['required', 'exists:profile_types,id'],
            'password' => ['required', 'string', 'min:8', 'confirmed'],
            'enabled' => ['nullable', 'boolean'],
        ];
    }
}

Personalizar la respuesta JSON de validación

Por defecto, Laravel devuelve los errores agrupados por campo:

{
    "message": "The given data was invalid.",
    "errors": {
        "email": [
            "Este correo electrónico ya está registrado."
        ],
        "password": [
            "La contraseña debe tener al menos 8 caracteres."
        ]
    }
}

Este formato es útil cuando queremos marcar errores campo por campo. Pero si nuestra interfaz usa modales y queremos mostrar una lista general de errores, puede ser más cómodo devolver una lista plana.

Para eso podemos sobrescribir el método failedValidation dentro del StoreUserRequest:

use Illuminate\Contracts\Validation\Validator;
use Illuminate\Http\Exceptions\HttpResponseException;

protected function failedValidation(Validator $validator): void
{
    throw new HttpResponseException(response()->json([
        'success' => false,
        'message' => 'Hay errores en el formulario.',
        'errors' => $validator->errors()->all(),
    ], 422));
}

Con esto, la respuesta quedará así:

{
    "success": false,
    "message": "Hay errores en el formulario.",
    "errors": [
        "El nombre es obligatorio.",
        "Este correo electrónico ya está registrado.",
        "La contraseña debe tener al menos 8 caracteres."
    ]
}

Controlador limpio usando el Form Request

Una vez que el Form Request está listo, el controlador puede mantenerse limpio:

use App\Http\Requests\Admin\User\StoreUserRequest;
use App\Models\User;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Hash;
use Throwable;

public function store(StoreUserRequest $request): JsonResponse
{
    try {
        $validated = $request->validated();

        $user = User::create([
            'name' => $validated['name'],
            'last_name' => $validated['last_name'],
            'email' => $validated['email'],
            'phone' => $validated['phone'] ?? null,
            'id_profile_type' => $validated['id_profile_type'],
            'password' => Hash::make($validated['password']),
            'enabled' => $validated['enabled'] ?? 1,
        ]);

        return response()->json([
            'success' => true,
            'message' => 'Usuario registrado correctamente.',
            'user_id' => $user->id,
        ], 201);

    } catch (Throwable $e) {
        report($e);

        return response()->json([
            'success' => false,
            'message' => 'No fue posible registrar el usuario. Inténtalo nuevamente.',
        ], 500);
    }
}

Códigos HTTP recomendados

Es importante regresar códigos HTTP correctos para que el frontend pueda interpretar bien la respuesta.

• 200: operación correcta.
• 201: registro creado correctamente.
• 401: usuario no autenticado.
• 403: usuario autenticado, pero sin permisos.
• 404: recurso no encontrado.
• 422: error de validación.
• 500: error inesperado del servidor.

Para formularios Ajax, una convención práctica sería:

Validación fallida  → 422
Creación correcta   → 201
Actualización       → 200
Eliminación         → 200
No encontrado       → 404
Sin permisos        → 403
Error inesperado    → 500

Conclusión

Usar Form Requests con formularios Ajax es una forma limpia y profesional de validar datos en Laravel sin sacrificar la experiencia de usuario.

La clave está en no llevar las reglas de validación al controlador, sino mantenerlas dentro del Request y personalizar la respuesta JSON cuando la validación falla.

Con esta estructura logramos:

• Controladores más limpios.
• Validaciones reutilizables.
• Respuestas JSON consistentes.
• Códigos HTTP correctos.
• Mejor integración con formularios en modales.
• Mejor experiencia de usuario usando Ajax.

Esta forma de trabajo es especialmente útil en paneles administrativos, sistemas internos, CRMs, ERPs y plataformas donde los formularios se muestran en modales o secciones dinámicas.

Si necesitas ayuda para crear un proyecto de software en Maria Tech contamos con los expertos para apoyarte.

En este artículo veremos cómo estructurar un proceso de recuperación de contraseña en Laravel 13 para dos tipos de usuarios: administradores y clientes. El objetivo es mantener una arquitectura limpia, segura y fácil de mantener.

Contexto del problema

Laravel Breeze instala un sistema de autenticación funcional, pero por defecto está pensado para trabajar principalmente con una sola tabla de usuarios, normalmente users.

Sin embargo, en proyectos más completos podemos necesitar algo como esto:

• Administradores: usuarios internos del sistema, almacenados en la tabla users.
• Clientes: usuarios externos que acceden al sitio o portal del cliente, almacenados en la tabla customers.

En este escenario no conviene mezclar ambos tipos de usuario en la misma tabla, porque normalmente tienen permisos, vistas, reglas de negocio y flujos diferentes.

Estructura recomendada

app/
├── Http/
│   ├── Controllers/
│   │   ├── Admin/
│   │   │   └── Auth/
│   │   │       ├── PasswordResetLinkController.php
│   │   │       └── NewPasswordController.php
│   │   └── Customer/
│   │       └── Auth/
│   │           ├── PasswordResetLinkController.php
│   │           └── NewPasswordController.php

resources/
├── views/
│   ├── admin/
│   │   └── auth/
│   │       ├── forgot-password.blade.php
│   │       └── reset-password.blade.php
│   └── customer/
│       └── auth/
│           ├── forgot-password.blade.php
│           └── reset-password.blade.php

routes/
├── admin.php
└── customer.php

La idea es separar cada flujo para evitar dependencias innecesarias y tener rutas, controladores, vistas y brokers independientes.

Configuración de autenticación

En config/auth.php podemos definir un guard y un provider para cada tipo de usuario.

<?php

use App\Models\User;
use App\Models\Customer;

return [

    'defaults' => [
        'guard' => 'web',
        'passwords' => 'users',
    ],

    'guards' => [
        'web' => [
            'driver' => 'session',
            'provider' => 'users',
        ],

        'customer' => [
            'driver' => 'session',
            'provider' => 'customers',
        ],
    ],

    'providers' => [
        'users' => [
            'driver' => 'eloquent',
            'model' => User::class,
        ],

        'customers' => [
            'driver' => 'eloquent',
            'model' => Customer::class,
        ],
    ],

    'passwords' => [
        'users' => [
            'provider' => 'users',
            'table' => 'password_reset_tokens',
            'expire' => 60,
            'throttle' => 60,
        ],

        'customers' => [
            'provider' => 'customers',
            'table' => 'customer_password_reset_tokens',
            'expire' => 60,
            'throttle' => 60,
        ],
    ],

];

El punto clave está en la sección passwords. Ahí definimos dos brokers: users para administradores y customers para clientes. Cada broker usa su propio provider y su propia tabla de tokens.

Migración para tokens de clientes

Schema::create('customer_password_reset_tokens', function (Blueprint $table) {
    $table->string('email')->primary();
    $table->string('token');
    $table->timestamp('created_at')->nullable();
});

Esto permite que el flujo de administradores y clientes quede completamente separado.

Rutas para administradores

use App\Http\Controllers\Admin\Auth\PasswordResetLinkController;
use App\Http\Controllers\Admin\Auth\NewPasswordController;
use Illuminate\Support\Facades\Route;

Route::middleware('admin.guest')->group(function () {
    Route::get('/forgot-password', [PasswordResetLinkController::class, 'create'])
        ->name('password.request');

    Route::post('/forgot-password', [PasswordResetLinkController::class, 'store'])
        ->name('password.email');

    Route::get('/reset-password/{token}', [NewPasswordController::class, 'create'])
        ->name('password.reset');

    Route::post('/reset-password', [NewPasswordController::class, 'store'])
        ->name('password.store');
});

Rutas para clientes

use App\Http\Controllers\Customer\Auth\PasswordResetLinkController;
use App\Http\Controllers\Customer\Auth\NewPasswordController;
use Illuminate\Support\Facades\Route;

Route::middleware('customer.guest')->group(function () {
    Route::get('/forgot-password', [PasswordResetLinkController::class, 'create'])
        ->name('password.request');

    Route::post('/forgot-password', [PasswordResetLinkController::class, 'store'])
        ->name('password.email');

    Route::get('/reset-password/{token}', [NewPasswordController::class, 'create'])
        ->name('password.reset');

    Route::post('/reset-password', [NewPasswordController::class, 'store'])
        ->name('password.store');
});

Controlador para enviar el enlace de recuperación

El controlador encargado de enviar el enlace de recuperación debe usar el broker correcto.

Administrador

namespace App\Http\Controllers\Admin\Auth;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Password;
use Illuminate\Validation\ValidationException;

class PasswordResetLinkController extends Controller
{
    public function create()
    {
        return view('admin.auth.forgot-password');
    }

    public function store(Request $request)
    {
        $request->validate([
            'email' => ['required', 'email'],
        ]);

        $status = Password::broker('users')->sendResetLink(
            $request->only('email')
        );

        if ($status === Password::RESET_LINK_SENT) {
            return back()->with('status', __($status));
        }

        throw ValidationException::withMessages([
            'email' => __($status),
        ]);
    }
}

Cliente

namespace App\Http\Controllers\Customer\Auth;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Password;
use Illuminate\Validation\ValidationException;

class PasswordResetLinkController extends Controller
{
    public function create()
    {
        return view('customer.auth.forgot-password');
    }

    public function store(Request $request)
    {
        $request->validate([
            'email' => ['required', 'email'],
        ]);

        $status = Password::broker('customers')->sendResetLink(
            $request->only('email')
        );

        if ($status === Password::RESET_LINK_SENT) {
            return back()->with('status', __($status));
        }

        throw ValidationException::withMessages([
            'email' => __($status),
        ]);
    }
}

El cambio central es el broker:

Password::broker('users')      // Administradores
Password::broker('customers')  // Clientes

Controlador para actualizar la contraseña

Administrador

namespace App\Http\Controllers\Admin\Auth;

use App\Http\Controllers\Controller;
use Illuminate\Auth\Events\PasswordReset;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Password;
use Illuminate\Support\Str;
use Illuminate\Validation\Rules;

class NewPasswordController extends Controller
{
    public function create(Request $request)
    {
        return view('admin.auth.reset-password', [
            'request' => $request,
        ]);
    }

    public function store(Request $request)
    {
        $request->validate([
            'token' => ['required'],
            'email' => ['required', 'email'],
            'password' => ['required', 'confirmed', Rules\Password::defaults()],
        ]);

        $status = Password::broker('users')->reset(
            $request->only('email', 'password', 'password_confirmation', 'token'),
            function ($user) use ($request) {
                $user->forceFill([
                    'password' => Hash::make($request->password),
                    'remember_token' => Str::random(60),
                ])->save();

                event(new PasswordReset($user));
            }
        );

        return $status === Password::PASSWORD_RESET
            ? redirect()->route('admin.login')->with('status', __($status))
            : back()->withInput($request->only('email'))
                ->withErrors(['email' => __($status)]);
    }
}

Cliente

namespace App\Http\Controllers\Customer\Auth;

use App\Http\Controllers\Controller;
use Illuminate\Auth\Events\PasswordReset;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Password;
use Illuminate\Support\Str;
use Illuminate\Validation\Rules;

class NewPasswordController extends Controller
{
    public function create(Request $request)
    {
        return view('customer.auth.reset-password', [
            'request' => $request,
        ]);
    }

    public function store(Request $request)
    {
        $request->validate([
            'token' => ['required'],
            'email' => ['required', 'email'],
            'password' => ['required', 'confirmed', Rules\Password::defaults()],
        ]);

        $status = Password::broker('customers')->reset(
            $request->only('email', 'password', 'password_confirmation', 'token'),
            function ($customer) use ($request) {
                $customer->forceFill([
                    'password' => Hash::make($request->password),
                    'remember_token' => Str::random(60),
                ])->save();

                event(new PasswordReset($customer));
            }
        );

        return $status === Password::PASSWORD_RESET
            ? redirect()->route('customer.login')->with('status', __($status))
            : back()->withInput($request->only('email'))
                ->withErrors(['email' => __($status)]);
    }
}

Personalizar la URL del correo de recuperación

Un detalle importante es que Laravel genera el enlace de recuperación usando una notificación. Si no personalizamos ese enlace, puede terminar enviando al usuario al flujo equivocado.

Para resolverlo, podemos agregar la lógica en app/Providers/AppServiceProvider.php.

namespace App\Providers;

use App\Models\Customer;
use App\Models\User;
use Illuminate\Auth\Notifications\ResetPassword;
use Illuminate\Support\Facades\URL;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        //
    }

    public function boot(): void
    {
        ResetPassword::createUrlUsing(function (object $notifiable, string $token): string {
            if ($notifiable instanceof Customer) {
                return URL::route('customer.password.reset', [
                    'token' => $token,
                    'email' => $notifiable->getEmailForPasswordReset(),
                ]);
            }

            if ($notifiable instanceof User) {
                return URL::route('admin.password.reset', [
                    'token' => $token,
                    'email' => $notifiable->getEmailForPasswordReset(),
                ]);
            }

            return URL::route('customer.password.reset', [
                'token' => $token,
                'email' => $notifiable->getEmailForPasswordReset(),
            ]);
        });
    }
}

Con esto, cuando el modelo sea User, Laravel enviará al flujo de administrador. Cuando el modelo sea Customer, enviará al flujo de cliente.

Vistas de recuperación de contraseña

En cada formulario es importante apuntar a la ruta correcta.

Formulario para solicitar enlace

Administrador:

<form method="POST" action="{{ route('admin.password.email') }}">
    @csrf
    <input type="email" name="email" required>
    <button type="submit">
        Enviar enlace
    </button>
</form>

Cliente:

<form method="POST" action="{{ route('customer.password.email') }}">
    @csrf
    <input type="email" name="email" required>
    <button type="submit">
        Enviar enlace
    </button>
</form>

Formulario para crear nueva contraseña

Administrador:

<form method="POST" action="{{ route('admin.password.store') }}">
    @csrf
    <input type="hidden" name="token" value="{{ $request->route('token') }}">
    <input type="email" name="email" value="{{ old('email', $request->email) }}" required>
    <input type="password" name="password" required>
    <input type="password" name="password_confirmation" required>
    <button type="submit">
        Actualizar contraseña
    </button>
</form>

Cliente:

<form method="POST" action="{{ route('customer.password.store') }}">
    @csrf
    <input type="hidden" name="token" value="{{ $request->route('token') }}">
    <input type="email" name="email" value="{{ old('email', $request->email) }}" required>
    <input type="password" name="password" required>
    <input type="password" name="password_confirmation" required>
    <button type="submit">
        Actualizar contraseña
    </button>
</form>

Buenas prácticas

• Usar modelos separados cuando los usuarios internos y externos tienen responsabilidades diferentes.
• Separar rutas, vistas y controladores por tipo de usuario.
• Usar un broker de contraseña diferente para cada tabla.
• Personalizar la URL del correo para evitar que el usuario llegue al flujo equivocado.
• No depender completamente de la estructura por defecto de Breeze cuando el proyecto requiere múltiples áreas de autenticación.
• Mantener nombres claros como Admin y Customer para facilitar el mantenimiento.

Conclusión

La recuperación de contraseña para múltiples tipos de usuarios en Laravel requiere separar correctamente guards, providers, brokers, rutas, controladores y vistas. Aunque Breeze ofrece una buena base inicial, en proyectos con administradores y clientes conviene tomar el control del flujo para evitar cruces entre autenticaciones.

La clave está en usar un broker distinto para cada tipo de usuario:

Password::broker('users')      // Administradores
Password::broker('customers')  // Clientes

Y personalizar el enlace generado por correo desde AppServiceProvider, para que cada usuario llegue al formulario correcto.

Con esta estructura, el sistema queda más limpio, seguro y preparado para crecer.

¡Si te ha servido de algo este artículo no olvides dejarnos un comentario!

En este artículo veremos cómo estructurar en Laravel una autenticación separada para dos tipos de usuarios: administradores y clientes. La idea es mantener una arquitectura limpia, segura y fácil de mantener.

Contexto del proyecto

El escenario es el siguiente:

• El administrador accede desde una URL privada, por ejemplo: /admin.
• Los clientes acceden desde el sitio público, por ejemplo: /.
• Los administradores se almacenan en la tabla users.
• Los clientes se almacenan en la tabla customers.
• Cada sección usa vistas, layouts, assets y controladores separados.
• Se utiliza Laravel Breeze como punto de partida, pero se adapta la estructura para soportar dos autenticaciones independientes.

La decisión principal fue no mezclar administradores y clientes en una misma tabla, ya que tienen responsabilidades, permisos y flujos completamente diferentes.

Estructura recomendada del proyecto

Una estructura limpia puede organizarse así:

app/
├── Http/
│   ├── Controllers/
│   │   ├── Admin/
│   │   │   ├── Auth/
│   │   │   └── DashboardController.php
│   │   │
│   │   ├── Customer/
│   │   │   ├── Auth/
│   │   │   └── AccountController.php
│   │   │
│   │   └── Controller.php
│   │
│   ├── Requests/
│   │   ├── Admin/
│   │   │   └── Auth/
│   │   │       └── LoginRequest.php
│   │   │
│   │   └── Customer/
│   │       └── Auth/
│   │           └── LoginRequest.php
│
resources/
├── views/
│   ├── admin/
│   │   ├── auth/
│   │   ├── layouts/
│   │   └── dashboard/
│   │
│   └── customer/
│       ├── auth/
│       ├── layouts/
│       └── account/
│
routes/
├── admin.php
├── customer.php
├── web.php
└── console.php

public/
└── assets/
    ├── admin/
    └── customer/

Esta separación permite que cada sección tenga su propia lógica, sus propios recursos visuales y sus propios middlewares.

Configuración de guards y providers

Laravel permite manejar múltiples sistemas de autenticación mediante guards y providers.

En este caso usamos:

• web para administradores.
• customer para clientes.

La configuración se realiza en config/auth.php:

<?php

use App\Models\User;
use App\Models\Customer;

return [

    'defaults' => [
        'guard' => env('AUTH_GUARD', 'web'),
        'passwords' => env('AUTH_PASSWORD_BROKER', 'users'),
    ],

    'guards' => [
        'web' => [
            'driver' => 'session',
            'provider' => 'users',
        ],

        'customer' => [
            'driver' => 'session',
            'provider' => 'customers',
        ],
    ],

    'providers' => [
        'users' => [
            'driver' => 'eloquent',
            'model' => User::class,
        ],

        'customers' => [
            'driver' => 'eloquent',
            'model' => Customer::class,
        ],
    ],

    'passwords' => [
        'users' => [
            'provider' => 'users',
            'table' => env('AUTH_PASSWORD_RESET_TOKEN_TABLE', 'password_reset_tokens'),
            'expire' => 60,
            'throttle' => 60,
        ],

        'customers' => [
            'provider' => 'customers',
            'table' => env('CUSTOMER_AUTH_PASSWORD_RESET_TOKEN_TABLE', 'customer_password_reset_tokens'),
            'expire' => 60,
            'throttle' => 60,
        ],
    ],

    'password_timeout' => env('AUTH_PASSWORD_TIMEOUT', 10800),

];

Un detalle importante es no usar la misma variable AUTH_MODEL para ambos providers, porque podría provocar que los clientes intenten autenticarse con el modelo de usuarios administrativos.

Modelo Customer autenticable

El modelo de cliente no debe extender directamente de Model, sino de Authenticatable, igual que el modelo User.

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class Customer extends Authenticatable
{
    use Notifiable;

    protected $guard = 'customer';

    protected $fillable = [
        'name',
        'last_name',
        'phone',
        'email',
        'password',
        'enabled',
    ];

    protected $hidden = [
        'password',
        'remember_token',
    ];
}

Esto permite que Laravel pueda autenticar clientes usando el guard customer.

Migraciones principales

Para los clientes se puede crear una tabla independiente:

Schema::create('customers', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('last_name');
    $table->char('phone', 10)->nullable();
    $table->string('email')->unique();
    $table->timestamp('email_verified_at')->nullable();
    $table->string('password');
    $table->rememberToken();
    $table->tinyInteger('enabled')->default(1);
    $table->timestamps();
});

También se puede manejar una tabla independiente para recuperación de contraseñas:

Schema::create('customer_password_reset_tokens', function (Blueprint $table) {
    $table->string('email')->primary();
    $table->string('token');
    $table->timestamp('created_at')->nullable();
});

En cuanto a sesiones, no es obligatorio crear una tabla diferente para clientes. Laravel usa la tabla sessions para guardar la sesión del navegador, no una sesión independiente por guard.

Rutas separadas

Una buena práctica es separar las rutas del administrador y del cliente.

Ejemplo de routes/admin.php:

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Admin\Auth\AuthenticatedSessionController;
use App\Http\Controllers\Admin\DashboardController;

Route::middleware('admin.guest')->group(function () {
    Route::get('/login', [AuthenticatedSessionController::class, 'create'])
        ->name('login');

    Route::post('/login', [AuthenticatedSessionController::class, 'store'])
        ->name('login.store');
});

Route::middleware('admin.auth')->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index'])
        ->name('dashboard');

    Route::post('/logout', [AuthenticatedSessionController::class, 'destroy'])
        ->name('logout');
});

Ejemplo de routes/customer.php:

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Customer\Auth\AuthenticatedSessionController;
use App\Http\Controllers\Customer\HomeController;
use App\Http\Controllers\Customer\AccountController;

Route::get('/', [HomeController::class, 'index'])
    ->name('home');

Route::middleware('customer.guest')->group(function () {
    Route::get('/login', [AuthenticatedSessionController::class, 'create'])
        ->name('login');

    Route::post('/login', [AuthenticatedSessionController::class, 'store'])
        ->name('login.store');
});

Route::middleware('customer.auth')->group(function () {
    Route::get('/mi-cuenta', [AccountController::class, 'index'])
        ->name('account');

    Route::post('/logout', [AuthenticatedSessionController::class, 'destroy'])
        ->name('logout');
});

Cargar rutas desde bootstrap/app.php

En Laravel moderno, las rutas adicionales pueden registrarse desde bootstrap/app.php:

use Illuminate\Support\Facades\Route;

->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    then: function () {
        Route::middleware('web')
            ->prefix('admin')
            ->name('admin.')
            ->group(base_path('routes/admin.php'));

        Route::middleware('web')
            ->name('customer.')
            ->group(base_path('routes/customer.php'));
    },
)

Con esta configuración se obtienen rutas como:

• /admin/login → admin.login
• /admin/dashboard → admin.dashboard
• /login → customer.login
• /mi-cuenta → customer.account

Middlewares propios por tipo de usuario

Para evitar lógica condicional dentro de bootstrap/app.php, se pueden crear middlewares específicos para cada sección.

Por ejemplo:

• admin.auth: valida que el usuario admin esté autenticado y activo.
• admin.guest: evita que un admin autenticado vuelva al login.
• customer.auth: valida que el cliente esté autenticado y activo.
• customer.guest: evita que un cliente autenticado vuelva al login.

Middleware de administrador autenticado:

<?php

namespace App\Http\Middleware\Admin;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Symfony\Component\HttpFoundation\Response;

class EnsureAdminIsAuthenticated
{
    public function handle(Request $request, Closure $next): Response
    {
        if (! Auth::guard('web')->check()) {
            return redirect()->route('admin.login');
        }

        $user = Auth::guard('web')->user();

        if (! $user->enabled) {
            Auth::guard('web')->logout();

            $request->session()->invalidate();
            $request->session()->regenerateToken();

            return redirect()
                ->route('admin.login')
                ->withErrors([
                    'email' => 'Tu cuenta se encuentra deshabilitada.',
                ]);
        }

        return $next($request);
    }
}

Middleware de cliente autenticado:

<?php

namespace App\Http\Middleware\Customer;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Symfony\Component\HttpFoundation\Response;

class EnsureCustomerIsAuthenticated
{
    public function handle(Request $request, Closure $next): Response
    {
        if (! Auth::guard('customer')->check()) {
            return redirect()->route('customer.login');
        }

        $customer = Auth::guard('customer')->user();

        if (! $customer->enabled) {
            Auth::guard('customer')->logout();

            $request->session()->invalidate();
            $request->session()->regenerateToken();

            return redirect()
                ->route('customer.login')
                ->withErrors([
                    'email' => 'Tu cuenta se encuentra deshabilitada.',
                ]);
        }

        return $next($request);
    }
}

Después se registran los alias de middleware en bootstrap/app.php:

use Illuminate\Foundation\Configuration\Middleware;
use App\Http\Middleware\Admin\EnsureAdminIsAuthenticated;
use App\Http\Middleware\Admin\RedirectIfAdminAuthenticated;
use App\Http\Middleware\Customer\EnsureCustomerIsAuthenticated;
use App\Http\Middleware\Customer\RedirectIfCustomerAuthenticated;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->alias([
        'admin.auth' => EnsureAdminIsAuthenticated::class,
        'admin.guest' => RedirectIfAdminAuthenticated::class,

        'customer.auth' => EnsureCustomerIsAuthenticated::class,
        'customer.guest' => RedirectIfCustomerAuthenticated::class,
    ]);
})

LoginRequest para clientes

Uno de los errores más comunes al trabajar con múltiples guards es usar Auth::attempt() sin especificar guard. Cuando se hace eso, Laravel utiliza el guard por defecto, normalmente web.

Para el login de clientes debe usarse:

Auth::guard('customer')->attempt($credentials, $this->boolean('remember'))

Ejemplo:

public function authenticate(): void
{
    $this->ensureIsNotRateLimited();

    $credentials = $this->only('email', 'password');
    $credentials['enabled'] = 1;

    if (! Auth::guard('customer')->attempt($credentials, $this->boolean('remember'))) {
        RateLimiter::hit($this->throttleKey());

        throw ValidationException::withMessages([
            'email' => trans('auth.failed'),
        ]);
    }

    Auth::guard('web')->logout();

    RateLimiter::clear($this->throttleKey());
}

En este ejemplo, después de iniciar sesión como cliente, se cierra cualquier sesión activa del administrador en el mismo navegador.

LoginRequest para administradores

Para el administrador se hace lo mismo, pero usando el guard web:

public function authenticate(): void
{
    $this->ensureIsNotRateLimited();

    $credentials = $this->only('email', 'password');
    $credentials['enabled'] = 1;

    if (! Auth::guard('web')->attempt($credentials, $this->boolean('remember'))) {
        RateLimiter::hit($this->throttleKey());

        throw ValidationException::withMessages([
            'email' => trans('auth.failed'),
        ]);
    }

    Auth::guard('customer')->logout();

    RateLimiter::clear($this->throttleKey());
}

De esta manera se evita que el mismo navegador mantenga una sesión de administrador y una sesión de cliente al mismo tiempo.

Uso correcto en Blade

Otro detalle importante es que la directiva @auth usa el guard por defecto si no se especifica uno. Por eso, en vistas de cliente se debe indicar explícitamente el guard.

Para clientes:

@auth('customer')
    Hola, {{ auth('customer')->user()->name }}
@endauth

@guest('customer')
    <a href="{{ route('customer.login') }}">Iniciar sesión</a>
@endguest

Para administradores:

@auth('web')
    Hola, {{ auth('web')->user()->name }}
@endauth

@guest('web')
    <a href="{{ route('admin.login') }}">Iniciar sesión</a>
@endguest

Sesiones en base de datos

Cuando se usa SESSION_DRIVER=database, Laravel guarda la sesión del navegador en la tabla sessions. Es importante entender que no se crea una sesión independiente por guard.

Si se inicia sesión como administrador y después como cliente en el mismo navegador, Laravel puede seguir usando el mismo registro de sesión. Lo importante es que el guard correcto esté autenticado y el otro haya sido cerrado.

Para validar:

auth('web')->check();   // Admin
auth('customer')->check(); // Cliente

También es normal que el registro en la tabla sessions permanezca por un tiempo aunque el usuario haya cerrado sesión. Laravel limpia las sesiones expiradas según su configuración de expiración.

Extras

Assets separados con Vite

Si cada sección utiliza un template diferente, también conviene separar los assets.

resources/
├── admin/
│   ├── css/
│   │   └── app.css
│   └── js/
│       └── app.js
│
└── customer/
    ├── css/
    │   └── app.css
    └── js/
        └── app.js

Ejemplo de vite.config.js:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/admin/css/app.css',
                'resources/admin/js/app.js',

                'resources/customer/css/app.css',
                'resources/customer/js/app.js',
            ],
            refresh: true,
        }),
    ],
});

En el layout de administrador:

@vite([
    'resources/admin/css/app.css',
    'resources/admin/js/app.js'
])

En el layout de cliente:

@vite([
    'resources/customer/css/app.css',
    'resources/customer/js/app.js'
])

Conclusión

Implementar autenticación para dos tipos de usuarios en Laravel requiere separar responsabilidades desde el inicio. La clave está en no mezclar modelos, guards, rutas ni vistas.

Una arquitectura limpia para este caso sería:

• users para administradores.
• customers para clientes.
• web como guard de administradores.
• customer como guard de clientes.
• resources/views/admin para el panel administrativo.
• resources/views/customer para el portal público.
• routes/admin.php y routes/customer.php para separar rutas.
• Middlewares propios para controlar accesos y redirecciones.

Esta estructura evita confusiones, mejora la seguridad y permite que el proyecto crezca de forma ordenada.

En sistemas donde existen usuarios internos y clientes finales, separar la autenticación no solo es una buena práctica técnica: también facilita el mantenimiento, las pruebas y la evolución del proyecto.

Esto es muy útil cuando un proyecto requiere una versión específica de PHP o cuando algún paquete de Composer todavía no es compatible con la versión más reciente.

En este artículo veremos cómo instalar y usar una versión diferente de PHP con Laravel Valet, tomando como ejemplo un problema común al instalar paquetes como maatwebsite/excel.

El problema: incompatibilidad entre paquetes y versión de PHP

En nuestro caso, al intentar instalar maatwebsite/excel, Composer mostró un error relacionado con phpoffice/phpspreadsheet:

phpoffice/phpspreadsheet 1.30.4 requires php >=7.4.0 <8.5.0 -> your php version (8.5.5) does not satisfy that requirement.

El mensaje es bastante claro: la versión instalada de PHP era 8.5.5, pero phpoffice/phpspreadsheet en la versión requerida por el proyecto solo permite PHP menor a 8.5.0.

Esto no significa que Laravel Valet esté mal configurado. Simplemente quiere decir que el paquete aún no es compatible con la versión de PHP que estamos usando.

maatwebsite/excel utiliza phpoffice/phpspreadsheet como dependencia para trabajar con archivos Excel y CSV.

¿Por qué conviene cambiar de PHP en lugar de forzar Composer?

Cuando Composer marca un error de compatibilidad, una tentación común es usar banderas como:

composer require paquete --ignore-platform-reqs

Aunque esto puede “saltarse” temporalmente la validación, no es recomendable como solución principal.

El problema es que Composer dejaría instalar un paquete que oficialmente no soporta tu versión de PHP. Eso puede provocar errores más adelante en ejecución, especialmente cuando se trata de librerías que manipulan archivos, fechas, memoria, formatos o extensiones de PHP.

La solución más limpia es usar una versión de PHP compatible con el proyecto.

En este caso, la solución fue bajar de PHP 8.5 a PHP 8.4.

Verificar la versión actual de PHP

Antes de cambiar nada, conviene revisar qué versión está usando nuestra terminal:

php -v

También podemos revisar qué versión de PHP está usando Valet:

valet which-php

Esto ayuda a confirmar si Composer, Laravel y Valet están trabajando con la versión esperada.

Instalar PHP 8.4 con Homebrew

Si estamos usando Valet en macOS, lo normal es instalar PHP mediante Homebrew.

Para instalar PHP 8.4 ejecutamos:

brew install php@8.4

Si ya lo teníamos instalado, podemos asegurarnos de que esté actualizado con:

brew update
brew upgrade php@8.4

Cambiar Laravel Valet a PHP 8.4

Laravel Valet permite cambiar la versión global de PHP con el comando valet use.

Para cambiar Valet a PHP 8.4:

valet use php@8.4

Se reiniciará Valet de manera automática, si no lo hace lo reiniciamos nosotros:

valet restart

Y validamos:

php -v
valet which-php

La salida debería mostrar una versión PHP 8.4.x.

Si la terminal sigue usando otra versión

Puede pasar que Valet ya esté usando PHP 8.4, pero la terminal siga apuntando a PHP 8.5.

En ese caso, podemos forzar el link de Homebrew:

brew unlink php
brew link --force --overwrite php@8.4

Luego volvemos a validar:

php -v

Si todo está correcto, Composer ya debería detectar PHP 8.4.

Instalar nuevamente el paquete

Una vez cambiada la versión de PHP, regresamos al proyecto Laravel:

cd ~/Developments/LaravelProjects/nombre-del-proyecto

Y ejecutamos:

composer require maatwebsite/excel

Si el problema era la incompatibilidad con PHP 8.5, ahora Composer debería poder resolver las dependencias correctamente.

Usar una versión de PHP solo para un proyecto

Una opción muy útil de Valet es aislar una versión de PHP por proyecto.

Esto sirve cuando tenemos varios proyectos con diferentes necesidades. Por ejemplo:

• Un proyecto moderno usando PHP 8.4.
• Un proyecto legacy usando PHP 8.2.
• Un proyecto experimental usando PHP 8.5.

Para aislar un proyecto con PHP 8.4:

cd ~/Developments/LaravelProjects/foresta
valet isolate php@8.4

Para ver los sitios aislados:

valet isolated

Para quitar el aislamiento y volver a usar la versión global de Valet:

valet unisolate

Esta opción es muy práctica porque evita estar cambiando la versión global de PHP cada vez que trabajamos en proyectos distintos.

Crear un archivo .valetrc

Otra alternativa es crear un archivo .valetrc dentro del proyecto indicando la versión de PHP que debe usar.

Dentro del proyecto:

touch .valetrc

Y agregamos:

php=php@8.4

Después podemos ejecutar:

valet use

Valet leerá el archivo y aplicará la versión indicada.

Comandos útiles de diagnóstico

Cuando Composer marque errores de compatibilidad, estos comandos ayudan bastante:

php -v

valet which-php

composer check-platform-reqs

composer why-not maatwebsite/excel

También podemos revisar qué paquetes están bloqueando una instalación específica:

composer why-not phpoffice/phpspreadsheet

Conclusión

Laravel Valet facilita bastante el manejo de versiones de PHP en macOS. Cuando un paquete no es compatible con la versión actual, lo ideal no es forzar Composer, sino revisar los requisitos y utilizar una versión de PHP compatible.