> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Sobrescritura y actualización de vistas de paquetes

> A partir de la implementación de Laravel 13, explica el orden de búsqueda de las vistas con espacio de nombres, el mantenimiento de las plantillas Blade publicadas y la diferencia entre la caché de vistas y la caché de resultados de búsqueda.

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](/es/advanced/package-development) 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.

```php src/CourierServiceProvider.php theme={null}
<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');

        $this->publishes([
            __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
        ], 'courier-views');
    }
}
```

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.

```php theme={null}
return view('courier::deliveries.show', [
    'trackingCode' => 'TRACK-001',
]);
```

```blade resources/views/deliveries/show.blade.php theme={null}
<p>Número de seguimiento: {{ $trackingCode }}</p>
```

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.

```mermaid theme={null}
flowchart TD
    A["courier::deliveries.show"] --> B["Busca resources/views/vendor/courier/<br>deliveries/show.blade.php"]
    B --> C{"¿Existe el archivo?"}
    C -->|Sí| D["Usa la vista de la aplicación"]
    C -->|No| E["Busca resources/views/<br>deliveries/show.blade.php del paquete"]
    E --> F{"¿Existe el archivo?"}
    F -->|Sí| G["Usa la vista del paquete"]
    F -->|No| H["Excepción de vista no encontrada"]
```

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.

| Estado de la aplicación | Vista seleccionada |
| - | - |
| No hay archivo de sobrescritura | El archivo del paquete |
| Hay un archivo de sobrescritura con la misma ruta relativa | El archivo de la aplicación |
| Se eliminó solo el archivo de sobrescritura | En un nuevo arranque se vuelve al archivo del paquete |
| El archivo no existe en ninguno de los dos | Excepción `View [...] not found.` |

<Info>
  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.
</Info>

## 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.

```bash theme={null}
php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider" --tag=courier-views
```

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.

<Warning>
  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.
</Warning>

### 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.

| Operación | Efecto en los archivos de vista |
| - | - |
| Republicación normal | Conserva los archivos existentes y copia los archivos de destino que no existen |
| Publicar con `--force` | También sobrescribe las personalizaciones existentes |
| Publicar con `--existing` | Sobrescribe solo los archivos de destino que ya existen en la ubicación de publicación |

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.

```bash theme={null}
php artisan view:cache
```

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.

```bash theme={null}
php artisan view:clear
```

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.

| Elemento gestionado | Función | Cómo abordarlo al actualizar |
| - | - | - |
| Archivos Blade publicados | Personalizaciones del usuario | Incorporar las diferencias o dejar de sobrescribir |
| PHP compilado | Resultado de la compilación de Blade | Gestionarlo con `view:cache` / `view:clear` |
| Rutas registradas y resultados de búsqueda del Finder | Selección de vistas en la instancia en ejecución | Reiniciar los procesos de larga duración con el nuevo código y la nueva configuración |

`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

<Columns cols={2}>
  <Card title="Vistas" icon="eye" href="/es/views">
    Repasa los fundamentos de la creación de vistas, el paso de datos y la precompilación.
  </Card>

  <Card title="Plantillas Blade" icon="code" href="/es/blade">
    Repasa el uso de layouts, include y componentes.
  </Card>

  <Card title="Gestión de la compatibilidad de versiones" icon="code-branch" href="/es/advanced/package-versioning">
    Vincula los cambios en el contrato de las plantillas con la política de versiones.
  </Card>

  <Card title="Octane" icon="bolt" href="/es/octane">
    Repasa el ciclo de vida y la recarga de las aplicaciones de larga duración.
  </Card>
</Columns>

## Fuentes primarias consultadas

* [Documentación oficial de Laravel: vistas de paquetes](https://github.com/laravel/docs/blob/156fc7fde114548640e13c39aa79b991291c3f91/packages.md#views)
* [ServiceProvider: registro de rutas de vistas](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Support/ServiceProvider.php)
* [FileViewFinder: orden de búsqueda y conservación de resultados](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/View/FileViewFinder.php)
* [VendorPublishCommand: condiciones de publicación de archivos](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/VendorPublishCommand.php)
* [ViewCacheCommand: recopilación de rutas de vistas y compilación](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/ViewCacheCommand.php)
* [ViewClearCommand: eliminación de archivos compilados](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/ViewClearCommand.php)
* [Compiler: comprobación de la fecha de modificación](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/View/Compilers/Compiler.php)


## Related topics

- [Desarrollo de paquetes para Laravel](/es/advanced/package-development.md)
- [Temas avanzados](/es/advanced/index.md)
- [Publicación y actualización de migraciones de paquetes](/es/advanced/package-migrations.md)
- [Actualización de Laravel 8 a 9](/es/blog/upgrade-8-to-9.md)
- [Actualización de Laravel — Septiembre de 2026](/es/blog/changelog/202609.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.