Skip to main content
En un paquete que permite al usuario personalizar las plantillas de pantallas o correos, no basta con publicar las vistas: también se necesita un contrato que permita actualizar el paquete conservando los archivos publicados. Aunque corrijas un archivo Blade del paquete, no hay garantía de que la aplicación del usuario esté renderizando ese archivo. Esta página parte de los fundamentos del desarrollo de paquetes y trata por separado la selección de vistas, la publicación de archivos y la caché. La documentación oficial de referencia es la de Laravel 13, y la implementación del framework es la última versión, v13.34.0.

​
El registro y la publicación son procesos distintos

loadViewsFrom() registra una ruta de búsqueda para un espacio de nombres. publishes() registra el origen y el destino de la copia, y la copia real la realiza vendor:publish. En el siguiente ejemplo, puedes usar courier::deliveries.show sin publicar nada.
src/CourierServiceProvider.php
El archivo del paquete se coloca en resources/views/deliveries/show.blade.php. Los puntos del nombre de la vista se convierten en separadores de directorio durante la búsqueda.
resources/views/deliveries/show.blade.php
El espacio de nombres de las vistas es independiente del nombre del paquete de Composer y del namespace de PHP. Aquí, courier, indicado como segundo argumento de loadViewsFrom(), es el contrato que define tanto la referencia a las vistas como el directorio de sobrescritura.

​
El destino de sobrescritura se busca archivo por archivo

Cuando se resuelve view, ServiceProvider::loadViewsFrom() recorre en orden las rutas de view.paths de la configuración. Si en alguna de ellas existe el directorio vendor/courier, lo añade al espacio de nombres y, por último, añade la ruta del paquete. FileViewFinder busca en orden en las rutas de ese espacio de nombres y devuelve el primer archivo que encuentra. En una configuración que usa el resources/views estándar, el orden es el siguiente. No se trata de cambiar todo el directorio. Aunque el usuario sobrescriba solo deliveries/show.blade.php, las demás vistas que no haya sobrescrito se cargan desde el paquete.
En configuraciones con varias entradas en view.paths, también puede haber varios destinos de sobrescritura. resource_path('views/vendor/courier') es el destino de publicación de este ejemplo, no un proceso que limite la búsqueda a esa ubicación. Usa un espacio de nombres propio del paquete y evita diseños en los que varios providers añaden rutas al mismo nombre.

​
Personalizar solo las vistas necesarias

El usuario puede copiar las plantillas con el siguiente comando. Indica el provider y la etiqueta para no arrastrar otros recursos.
Con este registro se publica todo el directorio de vistas. Si no es necesario sobrescribirlo todo, también puedes revisar el contenido y conservar solo los archivos que vayas a personalizar, o copiar manualmente solo los archivos necesarios a la misma ruta relativa. Esto se debe a que una copia sin editar también se trata como sobrescritura mientras exista.
Las plantillas publicadas no se sincronizan automáticamente con las actualizaciones del paquete. Si una copia antigua tiene prioridad y solo se corrige el lado del paquete, los cambios de esa vista no se reflejan. Las correcciones de errores de visualización o los cambios en formularios también requieren comparar con los archivos de sobrescritura.

​
Volver a publicar no fusiona diferencias

Normalmente, VendorPublishCommand omite la copia si ya existe un archivo con el mismo nombre en el destino. --force sobrescribe los archivos existentes. Además, --existing también es una opción que “sobrescribe los archivos ya publicados”, no un modo que conserve las ediciones del usuario. Ninguno de estos métodos es una fusión que compare la versión antigua, la nueva y las ediciones del usuario. Tampoco eliminan automáticamente del destino de publicación las vistas que se hayan quitado del paquete. No reduzcas el procedimiento de actualización a “volver a publicar la misma etiqueta”.

​
Mantener las vistas también como API pública

No solo los nombres de las vistas, sino también los datos que reciben y los componentes a los que hacen referencia afectan a las personalizaciones del usuario. Por ejemplo, si en una nueva versión cambias trackingCode por otro nombre de variable, los usuarios que conserven la plantilla antigua dejarán de recibir el valor que necesitan desde el nuevo código. Antes de publicar una versión, comprueba los siguientes contratos.
  • No cambiar sin motivo el espacio de nombres ni los nombres de vista como deliveries.show.
  • Documentar las variables que se pasan, sus tipos y si son obligatorias u opcionales.
  • Incluir en los cambios los destinos de @include y @extends y las props de los componentes Blade.
  • Indicar en las notas de la versión las vistas modificadas y los cambios que deben aplicarse a las versiones antiguas ya publicadas.
Para los usuarios, prepara un procedimiento para comparar las vistas del paquete de la versión antigua con las de la nueva e incorporar manualmente los cambios necesarios a los archivos personalizados. Los archivos cuya sobrescritura ya no sea necesaria pueden eliminarse, después de conservar los cambios en una copia de seguridad o en el control de versiones, para volver a las vistas del paquete.

​
La caché de Blade no actualiza los archivos de sobrescritura

view:cache precompila las plantillas Blade a PHP. ViewCacheCommand ejecuta primero view:clear y, a continuación, reúne las rutas de vistas normales y las rutas registradas en los espacios de nombres para buscar los archivos que debe compilar.
Este proceso no reescribe los archivos Blade publicados ni cambia la prioridad de búsqueda de las vistas. Si existe un archivo de sobrescritura antiguo, seguirá seleccionándose aunque reconstruyas la caché. En el despliegue, compila después de haber actualizado el código y los archivos de sobrescritura. Si durante el desarrollo quieres eliminar los archivos compilados y volver a renderizar, usa el siguiente comando.
Si la comprobación normal de marcas de tiempo está habilitada, el compilador de Blade compara la fecha de modificación del archivo original con la del archivo compilado. Sin embargo, hay configuraciones que desactivan esta comprobación, así que no dejes la reconstrucción durante el despliegue solo en manos de la detección automática.

​
Distinguirla de la caché de resultados de búsqueda

FileViewFinder::find() guarda la ruta encontrada en el array $views de esa instancia del Finder. Además, la comprobación de existencia del directorio de sobrescritura se realiza en el callback de loadViewsFrom(). Añadir un directorio nuevo después del arranque no lo agrega automáticamente a las rutas de búsqueda ya registradas. view:clear no es un comando que borre de una vez el estado del Finder que mantienen otros procesos en ejecución. En procesos de larga duración como Octane, recárgalos siguiendo el procedimiento de despliegue habitual. flush() del Finder borra los resultados de búsqueda, pero no llega a registrar nuevos directorios de sobrescritura.

​
Qué comprobar antes de publicar una versión

Además de las pruebas del paquete, comprueba las siguientes combinaciones en una aplicación de usuario. Una prueba que solo renderiza la plantilla más reciente no verifica la compatibilidad con los usuarios que publicaron la versión antigua.
  • Sin publicar, se renderiza la vista del paquete.
  • Al sobrescribir un solo archivo, solo ese archivo tiene prioridad y los demás recurren al paquete.
  • Aun conservando las plantillas publicadas de la versión antigua, se puede renderizar con los datos que pasa la nueva versión.
  • La republicación normal conserva las personalizaciones y la adición de archivos no publicados es la esperada.
  • Tras modificar un archivo de sobrescritura, view:cache se ejecuta correctamente y, en un nuevo arranque, se muestra el cambio.

​
Páginas relacionadas

Vistas

Repasa los fundamentos de la creación de vistas, el paso de datos y la precompilación.

Plantillas Blade

Repasa el uso de layouts, include y componentes.

Gestión de la compatibilidad de versiones

Vincula los cambios en el contrato de las plantillas con la política de versiones.

Octane

Repasa el ciclo de vida y la recarga de las aplicaciones de larga duración.

​
Fuentes primarias consultadas

Última modificación el 4 de octubre de 2026