Desarrollo de Paquetes

• Introducción
  • Una nota sobre los Facades
• Descubrimiento de Paquetes
• Proveedores de Servicios
• Recursos
  • Configuración
  • Migraciones
  • Rutas
  • Archivos de Idioma
  • Vistas
  • Componentes de Vista
  • Comando Artisan "About"
• Comandos
• Assets Públicos
• Publicación de Grupos de Archivos

#Introducción

Los paquetes son la forma principal de añadir funcionalidad a Laravel. Los paquetes pueden ser desde una excelente herramienta para trabajar con fechas como Carbon hasta un paquete que permite asociar archivos con modelos Eloquent como la Laravel Media Library de Spatie.

Existen diferentes tipos de paquetes. Algunos paquetes son independientes, lo que significa que funcionan con cualquier framework PHP. Carbon y PHPUnit son ejemplos de paquetes independientes. Cualquiera de estos paquetes puede usarse con Laravel requiriéndolos en su archivo composer.json.

Por otro lado, otros paquetes están específicamente diseñados para usarse con Laravel. Estos paquetes pueden tener rutas, controladores, vistas y configuración pensados para mejorar una aplicación Laravel. Esta guía cubre principalmente el desarrollo de esos paquetes específicos para Laravel.

#Una nota sobre los Facades

Al escribir una aplicación Laravel, generalmente no importa si usa contracts o facades, ya que ambos ofrecen niveles de testabilidad esencialmente iguales. Sin embargo, al escribir paquetes, su paquete normalmente no tendrá acceso a todos los helpers de pruebas de Laravel. Si desea poder escribir pruebas para su paquete como si estuviera instalado dentro de una aplicación Laravel típica, puede usar el paquete Orchestral Testbench.

#Descubrimiento de Paquetes

En el archivo de configuración config/app.php de una aplicación Laravel, la opción providers define una lista de proveedores de servicios que Laravel debe cargar. Cuando alguien instala su paquete, normalmente querrá que su proveedor de servicios esté incluido en esta lista. En lugar de requerir que los usuarios agreguen manualmente su proveedor de servicios a la lista, puede definir el proveedor en la sección extra del archivo composer.json de su paquete. Además de los proveedores de servicios, también puede listar cualquier facade que desee registrar:

"extra": {
    "laravel": {
        "providers": [
            "Barryvdh\\Debugbar\\ServiceProvider"
        ],
        "aliases": {
            "Debugbar": "Barryvdh\\Debugbar\\Facade"
        }
    }
},

Una vez que su paquete ha sido configurado para el descubrimiento, Laravel registrará automáticamente sus proveedores de servicios y facades cuando se instale, creando una experiencia de instalación conveniente para los usuarios de su paquete.

#Desactivar el Descubrimiento de Paquetes

Si usted es consumidor de un paquete y desea desactivar el descubrimiento de paquetes para uno, puede listar el nombre del paquete en la sección extra del archivo composer.json de su aplicación:

"extra": {
    "laravel": {
        "dont-discover": [
            "barryvdh/laravel-debugbar"
        ]
    }
},

También puede desactivar el descubrimiento de paquetes para todos los paquetes usando el carácter * dentro de la directiva dont-discover de su aplicación:

"extra": {
    "laravel": {
        "dont-discover": [
            "*"
        ]
    }
},

#Proveedores de Servicios

Los proveedores de servicios son el punto de conexión entre su paquete y Laravel. Un proveedor de servicios es responsable de enlazar elementos en el contenedor de servicios de Laravel e informar a Laravel dónde cargar recursos del paquete como vistas, configuración y archivos de idioma.

Un proveedor de servicios extiende la clase Illuminate\Support\ServiceProvider y contiene dos métodos: register y boot. La clase base ServiceProvider se encuentra en el paquete Composer illuminate/support, que debe agregar a las dependencias de su propio paquete. Para aprender más sobre la estructura y propósito de los proveedores de servicios, consulte su documentación.

#Recursos

#Configuración

Normalmente, necesitará publicar el archivo de configuración de su paquete en el directorio config de la aplicación. Esto permitirá a los usuarios de su paquete sobrescribir fácilmente las opciones de configuración predeterminadas. Para permitir que sus archivos de configuración se publiquen, llame al método publishes desde el método boot de su proveedor de servicios:

/**
 * Inicializar cualquier servicio del paquete.
 */
public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/courier.php' => config_path('courier.php'),
    ]);
}

Ahora, cuando los usuarios de su paquete ejecuten el comando vendor:publish de Laravel, su archivo será copiado a la ubicación de publicación especificada. Una vez que su configuración haya sido publicada, sus valores pueden accederse como cualquier otro archivo de configuración:

$value = config('courier.option');

#Configuración Predeterminada del Paquete

También puede fusionar su propio archivo de configuración del paquete con la copia publicada en la aplicación. Esto permitirá a sus usuarios definir solo las opciones que realmente desean sobrescribir en la copia publicada del archivo de configuración. Para fusionar los valores del archivo de configuración, use el método mergeConfigFrom dentro del método register de su proveedor de servicios.

El método mergeConfigFrom acepta la ruta al archivo de configuración de su paquete como primer argumento y el nombre de la copia del archivo de configuración en la aplicación como segundo argumento:

/**
 * Registrar cualquier servicio de la aplicación.
 */
public function register(): void
{
    $this->mergeConfigFrom(
        __DIR__.'/../config/courier.php', 'courier'
    );
}

#Rutas

Si su paquete contiene rutas, puede cargarlas usando el método loadRoutesFrom. Este método determinará automáticamente si las rutas de la aplicación están en caché y no cargará su archivo de rutas si ya están en caché:

/**
 * Inicializar cualquier servicio del paquete.
 */
public function boot(): void
{
    $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
}

#Migraciones

Si su paquete contiene migraciones de base de datos, puede usar el método loadMigrationsFrom para informar a Laravel cómo cargarlas. El método loadMigrationsFrom acepta la ruta a las migraciones de su paquete como único argumento:

/**
 * Inicializar cualquier servicio del paquete.
 */
public function boot(): void
{
    $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
}

Una vez que las migraciones de su paquete hayan sido registradas, se ejecutarán automáticamente cuando se ejecute el comando php artisan migrate. No es necesario exportarlas al directorio database/migrations de la aplicación.

#Archivos de Idioma

Si su paquete contiene archivos de idioma, puede usar el método loadTranslationsFrom para informar a Laravel cómo cargarlos. Por ejemplo, si su paquete se llama courier, debe agregar lo siguiente al método boot de su proveedor de servicios:

/**
 * Inicializar cualquier servicio del paquete.
 */
public function boot(): void
{
    $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');
}

Las líneas de traducción del paquete se referencian usando la convención de sintaxis package::file.line. Por lo tanto, puede cargar la línea welcome del paquete courier desde el archivo messages así:

echo trans('courier::messages.welcome');

Puede registrar archivos de traducción JSON para su paquete usando el método loadJsonTranslationsFrom. Este método acepta la ruta al directorio que contiene los archivos JSON de traducción de su paquete:

/**
 * Inicializar cualquier servicio del paquete.
 */
public function boot(): void
{
    $this->loadJsonTranslationsFrom(__DIR__.'/../lang');
}

#Publicar Archivos de Idioma

Si desea publicar los archivos de idioma de su paquete en el directorio lang/vendor de la aplicación, puede usar el método publishes del proveedor de servicios. El método publishes acepta un arreglo de rutas del paquete y sus ubicaciones deseadas de publicación. Por ejemplo, para publicar los archivos de idioma del paquete courier, puede hacer lo siguiente:

/**
 * Inicializar cualquier servicio del paquete.
 */
public function boot(): void
{
    $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');

    $this->publishes([
        __DIR__.'/../lang' => $this->app->langPath('vendor/courier'),
    ]);
}

Ahora, cuando los usuarios de su paquete ejecuten el comando Artisan vendor:publish de Laravel, los archivos de idioma de su paquete serán publicados en la ubicación especificada.

#Vistas

Para registrar las vistas de su paquete con Laravel, debe indicarle dónde se encuentran las vistas. Puede hacer esto usando el método loadViewsFrom del proveedor de servicios. El método loadViewsFrom acepta dos argumentos: la ruta a sus plantillas de vista y el nombre de su paquete. Por ejemplo, si el nombre de su paquete es courier, agregaría lo siguiente al método boot de su proveedor de servicios:

/**
 * Inicializar cualquier servicio del paquete.
 */
public function boot(): void
{
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
}

Las vistas del paquete se referencian usando la convención de sintaxis package::view. Así, una vez que la ruta de su vista esté registrada en un proveedor de servicios, puede cargar la vista dashboard del paquete courier así:

Route::get('/dashboard', function () {
    return view('courier::dashboard');
});

#Sobrescribir Vistas del Paquete

Cuando usa el método loadViewsFrom, Laravel en realidad registra dos ubicaciones para sus vistas: el directorio resources/views/vendor de la aplicación y el directorio que usted especifica. Por lo tanto, usando el paquete courier como ejemplo, Laravel primero verificará si el desarrollador ha colocado una versión personalizada de la vista en el directorio resources/views/vendor/courier. Luego, si la vista no ha sido personalizada, Laravel buscará en el directorio de vistas del paquete que especificó en su llamada a loadViewsFrom. Esto facilita que los usuarios del paquete personalicen o sobrescriban las vistas de su paquete.

#Publicar Vistas

Si desea que sus vistas estén disponibles para ser publicadas en el directorio resources/views/vendor de la aplicación, puede usar el método publishes del proveedor de servicios. El método publishes acepta un arreglo de rutas de vistas del paquete y sus ubicaciones deseadas de publicación:

/**
 * Bootstrap the package services.
 */
public function boot(): void
{
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');

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

Ahora, cuando los usuarios de su paquete ejecuten el comando Artisan vendor:publish de Laravel, las vistas de su paquete serán copiadas a la ubicación de publicación especificada.

#Componentes de Vista

Si está construyendo un paquete que utiliza componentes Blade o coloca componentes en directorios no convencionales, necesitará registrar manualmente la clase de su componente y su alias de etiqueta HTML para que Laravel sepa dónde encontrar el componente. Normalmente debería registrar sus componentes en el método boot del proveedor de servicios de su paquete:

use Illuminate\Support\Facades\Blade;
use VendorPackage\View\Components\AlertComponent;

/**
 * Inicializar los servicios de su paquete.
 */
public function boot(): void
{
    Blade::component('package-alert', AlertComponent::class);
}

Una vez que su componente ha sido registrado, puede renderizarse usando su alias de etiqueta:

<x-package-alert/>

#Autocarga de Componentes del Paquete

Alternativamente, puede usar el método componentNamespace para autocargar clases de componentes por convención. Por ejemplo, un paquete Nightshade podría tener componentes Calendar y ColorPicker que residen dentro del namespace Nightshade\Views\Components:

use Illuminate\Support\Facades\Blade;

/**
 * Inicializar los servicios de su paquete.
 */
public function boot(): void
{
    Blade::componentNamespace('Nightshade\\Views\\Components', 'nightshade');
}

Esto permitirá el uso de componentes del paquete por su namespace de proveedor usando la sintaxis package-name:::

<x-nightshade::calendar />
<x-nightshade::color-picker />

Blade detectará automáticamente la clase vinculada a este componente usando PascalCase para el nombre del componente. También se soportan subdirectorios usando la notación con "puntos".

#Componentes Anónimos

Si su paquete contiene componentes anónimos, deben colocarse dentro de un directorio components dentro del directorio de "vistas" de su paquete (como se especifica en el método loadViewsFrom). Luego, puede renderizarlos prefijando el nombre del componente con el namespace de vista del paquete:

<x-courier::alert />

#Comando Artisan "About"

El comando Artisan incorporado about de Laravel proporciona un resumen del entorno y configuración de la aplicación. Los paquetes pueden añadir información adicional a la salida de este comando mediante la clase AboutCommand. Normalmente, esta información se añade desde el método boot del proveedor de servicios de su paquete:

use Illuminate\Foundation\Console\AboutCommand;

/**
 * Inicializar cualquier servicio de la aplicación.
 */
public function boot(): void
{
    AboutCommand::add('My Package', fn () => ['Version' => '1.0.0']);
}

#Comandos

Para registrar los comandos Artisan de su paquete con Laravel, puede usar el método commands. Este método espera un arreglo con los nombres de las clases de comandos. Una vez registrados, puede ejecutarlos usando la CLI Artisan:

use Courier\Console\Commands\InstallCommand;
use Courier\Console\Commands\NetworkCommand;

/**
 * Inicializar cualquier servicio del paquete.
 */
public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            InstallCommand::class,
            NetworkCommand::class,
        ]);
    }
}

#Assets Públicos

Su paquete puede tener assets como JavaScript, CSS e imágenes. Para publicar estos assets en el directorio public de la aplicación, use el método publishes del proveedor de servicios. En este ejemplo, también añadiremos una etiqueta de grupo de assets public, que puede usarse para publicar fácilmente grupos de assets relacionados:

/**
 * Inicializar cualquier servicio del paquete.
 */
public function boot(): void
{
    $this->publishes([
        __DIR__.'/../public' => public_path('vendor/courier'),
    ], 'public');
}

Ahora, cuando los usuarios de su paquete ejecuten el comando vendor:publish, sus assets serán copiados a la ubicación de publicación especificada. Dado que los usuarios normalmente necesitarán sobrescribir los assets cada vez que el paquete se actualice, puede usar la bandera --force:

php artisan vendor:publish --tag=public --force

#Publicación de Grupos de Archivos

Puede que desee publicar grupos de assets y recursos del paquete por separado. Por ejemplo, podría querer permitir que sus usuarios publiquen los archivos de configuración de su paquete sin verse obligados a publicar los assets. Puede hacer esto "etiquetándolos" al llamar al método publishes desde el proveedor de servicios del paquete. Por ejemplo, use etiquetas para definir dos grupos de publicación para el paquete courier (courier-config y courier-migrations) en el método boot del proveedor de servicios del paquete:

/**
 * Inicializar cualquier servicio del paquete.
 */
public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/package.php' => config_path('package.php')
    ], 'courier-config');

    $this->publishes([
        __DIR__.'/../database/migrations/' => database_path('migrations')
    ], 'courier-migrations');
}

Ahora sus usuarios pueden publicar estos grupos por separado haciendo referencia a su etiqueta al ejecutar el comando vendor:publish:

php artisan vendor:publish --tag=courier-config