Registro de rutas y caché en paquetes

Cuando un paquete ofrece endpoints HTTP, no basta con que las rutas funcionen en el entorno de desarrollo: también deben funcionar con el mismo contrato después de que la aplicación que lo usa genere la caché de rutas. Si el diseño permite cambiar el prefijo de la URL o activar y desactivar las rutas mediante configuración, también hay que indicar al usuario cuándo se aplican esos cambios. Esta página parte de los fundamentos del desarrollo de paquetes y trata por separado el proceso de registro y el ciclo de vida de la caché. La documentación oficial de referencia es la rama por defecto de Laravel 13, 13.x, y la implementación del framework es la última versión, v13.34.0.

loadRoutesFrom solo carga el archivo

ServiceProvider::loadRoutesFrom() no carga el archivo de rutas si la aplicación implementa CachesRoutes y routesAreCached() devuelve verdadero. En cualquier otro caso, hace require del archivo indicado. Este método no añade por sí mismo prefijos de URI ni de nombre de ruta, espacios de nombres de controladores ni middleware. Tampoco publica archivos ni añade rutas a una caché existente. El diagrama asume una aplicación Laravel estándar. No existe una caché exclusiva para el paquete: las rutas del paquete se incluyen en la caché de rutas de toda la aplicación.

Llamar routes/web.php al archivo del paquete no le añade por sí solo el middleware web. Como la ruta de carga es distinta a la de los archivos de rutas estándar de la aplicación, declara explícitamente en el paquete el middleware que necesites.

Separar la configuración del registro

En el siguiente ejemplo se crea un endpoint público que indica si el paquete puede responder. Se asume que el PSR-4 de Composer asigna Acme\Courier\ a src/ y que el provider se registra mediante detección automática o de forma manual.

config/courier.php

<?php

return [
    'routes' => [
        'enabled' => true,
        'prefix' => 'acme-courier',
    ],
];

La fusión de la configuración se hace en register() y la carga de rutas en boot(). No conviertas en DeferrableProvider un provider que registra rutas HTTP, porque dejaría de estar garantizado que el provider arranque en el momento en que se necesitan las rutas.

src/CourierServiceProvider.php

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->mergeConfigFrom(__DIR__.'/../config/courier.php', 'courier');
    }

    public function boot(): void
    {
        if (config('courier.routes.enabled')) {
            $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
        }
    }
}

Esta condición solo controla el registro de rutas. Si el provider también registra otros servicios o vistas, no los coloques dentro de esta condición. Para saber cómo exponer la configuración al usuario y qué tener en cuenta al fusionar configuración anidada, consulta Fusión y caché de la configuración de paquetes.

routes/web.php

<?php

use Acme\Courier\Http\Controllers\StatusController;
use Illuminate\Support\Facades\Route;

Route::middleware('web')
    ->prefix(config('courier.routes.prefix'))
    ->name('acme-courier.')
    ->group(function () {
        Route::get('/status', StatusController::class)->name('status');
    });

src/Http/Controllers/StatusController.php

<?php

namespace Acme\Courier\Http\Controllers;

use Illuminate\Http\JsonResponse;

class StatusController
{
    public function __invoke(): JsonResponse
    {
        return response()->json(['available' => true]);
    }
}

La URI por defecto es /acme-courier/status y el nombre de la ruta es acme-courier.status. Si generas la URL con route('acme-courier.status'), el código que la llama puede seguir usando el mismo nombre de ruta aunque cambie el prefijo de la URI. El name() del grupo concatena la cadena tal cual, así que incluye también el . final.

web no sustituye a la autenticación ni a la autorización. Este ejemplo es un endpoint público que no contiene información confidencial. Para los endpoints que devuelven datos del usuario, añade por separado el middleware de autenticación y la autorización que requiera la especificación.

Evitar por separado los conflictos de URI y de nombre de ruta

El prefijo de la URI y el prefijo del nombre de ruta son mecanismos distintos. Añadir solo uno de ellos no evita los conflictos del otro.

Elemento	Diseño en este ejemplo	Consideraciones de mantenimiento
URI	`acme-courier` por defecto, modificable mediante configuración	Elegir un valor que no entre en conflicto con las URL existentes de la aplicación
Nombre de ruta	`acme-courier.` fijo	Usar un nombre propio del paquete y mantenerlo como contrato para generar URL
Controlador	Referencia a la clase	No depender del espacio de nombres de controladores de la aplicación
Middleware	`web` declarado explícitamente	Comprobarlo junto con la configuración de middleware de la aplicación de destino

AbstractRouteCollection lanza una LogicException al construir la colección de rutas para la caché si otra ruta tiene el mismo nombre. Que “se haya podido generar la URL en un arranque normal” no garantiza que las rutas se puedan cachear. Incluso dos rutas con URI distintas causan problemas si comparten nombre. No conviertas en mecanismo de extensión del paquete la sobrescritura de las rutas de la aplicación según el orden de registro. Si hace falta, ofrece una opción de configuración para desactivar las rutas y un servicio que el usuario pueda invocar desde sus propias rutas.

La configuración del momento de crear la caché queda en la definición de rutas

RouteCacheCommand ejecuta primero route:clear, arranca una nueva aplicación y recopila las rutas. Después prepara esas rutas para que se puedan serializar y escribe el resultado compilado en el archivo de caché. Como en ese momento también se carga el archivo de rutas del paquete, el prefijo y el hecho de registrar o no las rutas se deciden con la configuración vigente al crear la caché. En los arranques posteriores, loadRoutesFrom() no carga el archivo y se usan las rutas cacheadas.

Cambio	Si queda una caché de rutas antigua	Acción necesaria
Añadir rutas al paquete	Las rutas añadidas no aparecen	Regenerar la caché de rutas
Cambiar `routes.prefix`	Se mantiene la URI anterior	Regenerarla con la nueva configuración
Cambiar `routes.enabled` a `false`	Las rutas cacheadas no desaparecen	Regenerarla con la configuración desactivada
Eliminar el paquete	Pueden quedar definiciones que referencian clases eliminadas	Regenerarla con la configuración posterior a la eliminación

routes.enabled es una opción que controla el registro, no un rechazo de acceso por petición. Si solo desactivas la configuración mientras queda una caché antigua, el endpoint no se habrá detenido.

No registres rutas en función de condiciones que cambian en cada petición, como el usuario o el tenant. Esas condiciones se evalúan en el entorno CLI en el momento de crear la caché. Registra las rutas con una configuración estable y decide si se permite el acceso mediante middleware o autorización dentro del controlador.

En el despliegue, fija primero la configuración

Una vez actualizados el código y la configuración, si se usa la caché de configuración, regenera las cachés en el siguiente orden. Incorpóralo al proceso de despliegue de la aplicación que usa el paquete.

php artisan config:cache
php artisan route:cache
php artisan route:list --name=acme-courier -vv

Si ejecutas route:cache mientras queda una caché de configuración antigua, las rutas también se generan con la configuración antigua. Volver a ejecutar solo config:cache no actualiza la caché de rutas. Con -vv también puedes comprobar el contenido de los grupos de middleware. Si durante el desarrollo quieres comprobar el funcionamiento sin caché, limpia ambas según sea necesario.

php artisan config:clear
php artisan route:clear

El archivo de rutas no se ejecuta en los arranques que usan la caché. Si registras en él listeners de eventos o bindings del contenedor, el comportamiento cambiará, así que no le des efectos secundarios distintos de la definición de rutas. En entornos con procesos de larga duración, incluye también la recarga tras actualizar la caché en el procedimiento de despliegue habitual.

Combinaciones que comprobar antes de publicar una versión

Además de las pruebas del paquete, comprueba las siguientes combinaciones en una aplicación Laravel 13 que lo use. No te limites al registro de rutas en memoria: incluye también el camino en el que Artisan arranca una nueva aplicación.

Sin caché, /acme-courier/status responde y el nombre de ruta y el middleware son los esperados.
route:cache se ejecuta correctamente y, en un nuevo arranque, responde con la misma URI y el mismo nombre de ruta.
Al cambiar el prefijo y regenerar la caché, responde la nueva URI y desaparece la ruta del paquete en la URI anterior.
Al desactivar las rutas y regenerar la caché, la ruta no aparece en route:list --name=acme-courier.
No hay conflictos de URI ni de nombre de ruta con la aplicación ni con otros paquetes.

Si también compruebas el caso en que queda una caché antigua, podrás reproducir informes de usuarios del tipo “he cambiado el archivo de configuración, pero la URL no cambia”. Indica la regeneración de la caché en las instrucciones de actualización y trata también los cambios en los nombres de ruta y el middleware como cuestiones de compatibilidad.

Páginas relacionadas

Enrutamiento

Repasa los fundamentos de los grupos de rutas, las rutas con nombre y su listado.

Fusión y caché de la configuración de paquetes

Repasa el procedimiento de actualización teniendo en cuenta la configuración publicada y la caché de configuración.

Service providers diferidos

Repasa por qué no conviene diferir un provider que registra rutas.

Gestión de la compatibilidad de versiones de paquetes

Vincula los cambios en la API pública con la política de versiones y la verificación continua.

Desarrollo con IA

Patrones de diseño

Desarrollo de paquetes

Estructura de la aplicación

Novedades de Laravel 13

Profundizando en Eloquent

Extensión de validación

Extensión de autenticación

Seguridad

Colas

Pruebas

Tiempo real

Registro de rutas y caché en paquetes

loadRoutesFrom solo carga el archivo

Separar la configuración del registro

Evitar por separado los conflictos de URI y de nombre de ruta

La configuración del momento de crear la caché queda en la definición de rutas

En el despliegue, fija primero la configuración

Combinaciones que comprobar antes de publicar una versión

Páginas relacionadas

Enrutamiento

Fusión y caché de la configuración de paquetes

Service providers diferidos

Gestión de la compatibilidad de versiones de paquetes

Fuentes primarias consultadas

​loadRoutesFrom solo carga el archivo

​Separar la configuración del registro

​Evitar por separado los conflictos de URI y de nombre de ruta

​La configuración del momento de crear la caché queda en la definición de rutas

​En el despliegue, fija primero la configuración

​Combinaciones que comprobar antes de publicar una versión

​Páginas relacionadas

Enrutamiento

Fusión y caché de la configuración de paquetes

Service providers diferidos

Gestión de la compatibilidad de versiones de paquetes

​Fuentes primarias consultadas

loadRoutesFrom solo carga el archivo

Separar la configuración del registro

Evitar por separado los conflictos de URI y de nombre de ruta

La configuración del momento de crear la caché queda en la definición de rutas

En el despliegue, fija primero la configuración

Combinaciones que comprobar antes de publicar una versión

Páginas relacionadas

Fuentes primarias consultadas