Desarrollo de paquetes para Laravel

Qué es un paquete

En Laravel, un paquete es un paquete de Composer que añade funcionalidad a la aplicación. Hay dos tipos principales.

Paquete independiente — biblioteca PHP de propósito general que no depende de Laravel (por ejemplo: Carbon, Pest).
Paquete de Laravel — paquete que ofrece funciones integradas con Laravel, como rutas, controladores, vistas o configuración.

Esta guía trata el segundo caso, el desarrollo de paquetes específicos para Laravel. El desarrollo de paquetes requiere un conocimiento profundo de la estructura interna de Laravel, incluidos los service providers, las fachadas y la publicación de archivos de configuración.

Si vas a escribir pruebas para el paquete, utiliza Orchestra Testbench. Podrás escribir las pruebas del paquete igual que en una aplicación Laravel normal.

Detección automática de paquetes

Cuando instalas un paquete, Laravel lee la sección extra.laravel de composer.json y registra automáticamente los service providers y las fachadas.

"extra": {
    "laravel": {
        "providers": [
            "Acme\\Courier\\CourierServiceProvider"
        ],
        "aliases": {
            "Courier": "Acme\\Courier\\Facades\\Courier"
        }
    }
}

Con esta configuración, el paquete se carga automáticamente sin que el usuario tenga que editar bootstrap/providers.php a mano.

En Estructura interna de la detección automática de paquetes se explica cómo se implementa esta detección automática y cuándo se reconstruye la caché.

Desactivar la detección automática

Si el usuario quiere desactivar la detección automática de un paquete concreto, puede configurarlo en el composer.json de la aplicación.

"extra": {
    "laravel": {
        "dont-discover": [
            "acme/courier"
        ]
    }
}

El papel del service provider

El service provider es el punto de entrada del paquete. Aquí es donde concentras el registro de recursos como vistas, configuración, migraciones o rutas en Laravel. Un service provider extiende Illuminate\Support\ServiceProvider y dispone de dos métodos: register y boot.

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    /**
     * Registra los servicios del paquete
     */
    public function register(): void
    {
        // Los bindings al service container se realizan aquí
        $this->mergeConfigFrom(
            __DIR__.'/../config/courier.php', 'courier'
        );

        $this->app->singleton(CourierManager::class, function ($app) {
            return new CourierManager($app['config']['courier']);
        });
    }

    /**
     * Inicializa los servicios del paquete
     */
    public function boot(): void
    {
        // El registro de recursos se realiza aquí
        $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
        $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
        $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');

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

        $this->publishes([
            __DIR__.'/../config/courier.php' => config_path('courier.php'),
        ], 'courier-config');

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

No registres listeners de eventos, rutas o vistas dentro del método register. Podrías utilizar por error servicios de otro service provider que aún no se ha cargado. Todo lo que no sean bindings debe hacerse en el método boot.

Para extender un servicio sin crearlo hasta que se use y aplicar la configuración incluso cuando ya se ha resuelto, consulta Hooks de resolución de servicios en paquetes. Allí se explica cuándo se ejecuta callAfterResolving() y cómo diseñar para tolerar aplicaciones repetidas. Para registrar servicios que no arrastren estado ni en Octane ni en los workers de colas, consulta Diseño del ciclo de vida de los servicios de paquetes. Allí se explica la implementación interna de scoped() y las precauciones con las dependencias que retiene un singleton.

Publicación de archivos de configuración

publishes() — publicar archivos

Si llamas a publishes() dentro del método boot, el usuario podrá copiar el archivo de configuración a su aplicación mediante el comando vendor:publish.

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

Una vez publicado, puedes acceder a los valores de configuración con el mecanismo habitual de config.

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

mergeConfigFrom() — fusionar con los valores por defecto

Si utilizas mergeConfigFrom() en el método register, los valores por defecto del paquete se aplicarán aunque el usuario no haya publicado el archivo de configuración.

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

mergeConfigFrom() no fusiona los niveles más profundos de los arrays anidados. En configuraciones con arrays multidimensionales, es posible que si el usuario define solo una parte, el resto de las opciones no se fusionen.

En Fusión y caché de la configuración de paquetes se explican las diferencias con el método de reemplazo recursivo de Laravel 13, el tratamiento de las listas con claves numéricas y los pasos de actualización cuando se usa la caché de configuración.

Separar grupos de publicación mediante etiquetas

Si pasas una etiqueta como segundo argumento a publishes(), el usuario podrá publicar solo los recursos que necesite.

public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/courier.php' => config_path('courier.php'),
    ], 'courier-config');

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

# Publicar solo el archivo de configuración
php artisan vendor:publish --tag=courier-config

# Publicar todos los archivos que ofrece el provider
php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider"

Registro de rutas

Utiliza loadRoutesFrom() para cargar el archivo de rutas. Si la caché de rutas de la aplicación está activa, se omite automáticamente.

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

Dentro del archivo de rutas apuntas a los controladores del paquete.

// routes/web.php
use Acme\Courier\Http\Controllers\TrackingController;
use Illuminate\Support\Facades\Route;

Route::prefix('courier')->group(function () {
    Route::get('/track/{id}', [TrackingController::class, 'show'])
        ->name('courier.track');
});

Cómo declarar el middleware explícitamente, cómo evitar conflictos de URI y de nombre de ruta, y los pasos para aplicar los cambios de configuración a la caché se explican en Registro de rutas y caché en paquetes.

Publicación de migraciones

Con publishesMigrations() puedes registrar los archivos de migración para publicarlos. En la configuración estándar de Laravel 13, database.migrations.update_date_on_publish está activado, por lo que la marca de tiempo del nombre de archivo se actualiza al publicar. Si el ajuste está desactivado o no existe, esta actualización no se realiza.

public function boot(): void
{
    $this->publishesMigrations([
        __DIR__.'/../database/migrations' => database_path('migrations'),
    ]);
}

Cuándo publicar o cargar directamente, las condiciones del cambio de marca de tiempo, los riesgos de republicar y los cambios de esquema para usuarios existentes se explican en Publicación y actualización de migraciones de paquetes.

Publicación de vistas

loadViewsFrom() — registrar vistas

Registra el directorio de vistas con loadViewsFrom(). El segundo argumento es el espacio de nombres, que se utiliza para referenciar las vistas con el formato paquete::vista.

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

Una vez registradas, las vistas se referencian con el espacio de nombres del paquete.

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

Laravel busca las vistas en dos ubicaciones. Primero comprueba el directorio resources/views/vendor/courier de la aplicación y, si no existe, utiliza el directorio de vistas del paquete. Esto permite al usuario personalizar las vistas. El orden de búsqueda real en la implementación, el fallback archivo por archivo, cómo hacer llegar los cambios a las plantillas publicadas y la diferencia con la caché de Blade se explican en Sobrescritura y actualización de vistas de paquetes.

Publicar las vistas

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

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

Registrar componentes Blade

Si el paquete incluye componentes, regístralos en el método boot.

use Illuminate\Support\Facades\Blade;
use Acme\Courier\View\Components\AlertComponent;

public function boot(): void
{
    Blade::component('courier-alert', AlertComponent::class);
}

También puedes registrarlos por lotes usando un espacio de nombres de componentes.

use Illuminate\Support\Facades\Blade;

public function boot(): void
{
    Blade::componentNamespace('Acme\\Courier\\View\\Components', 'courier');
}

{{-- Registro individual --}}
<x-courier-alert />

{{-- Registro con espacio de nombres --}}
<x-courier::alert />

Distribución de assets públicos

Para distribuir el JavaScript, el CSS y las imágenes del paquete, registra con publishes() la copia a una ruta como public_path('vendor/courier'). Aunque actualices el paquete, los archivos ya publicados no cambian automáticamente. El filtrado por etiquetas y providers, la diferencia entre --force y --existing, el tratamiento de los archivos eliminados y la actualización mediante laravel-assets se explican en Assets públicos de paquetes y su actualización.

Publicación de archivos de traducción

Registra los archivos de traducción con loadTranslationsFrom(). Las traducciones se referencian con el formato paquete::archivo.clave.

public function boot(): void
{
    $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');

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

// Uso de la traducción
echo trans('courier::messages.welcome');

Si utilizas archivos de traducción en JSON, usa loadJsonTranslationsFrom().

public function boot(): void
{
    $this->loadJsonTranslationsFrom(__DIR__.'/../lang');
}

La sobrescritura parcial de traducciones PHP, el orden de carga y el destino de sobrescritura de las traducciones JSON, la compatibilidad de las claves de traducción y la actualización de los archivos publicados se explican en Sobrescritura y actualización de traducciones de paquetes.

Registro de comandos

Los comandos Artisan del paquete se registran con el método commands(). Lo habitual es registrarlos solo en el entorno de consola.

use Acme\Courier\Console\Commands\InstallCommand;
use Acme\Courier\Console\Commands\SyncCommand;

public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            InstallCommand::class,
            SyncCommand::class,
        ]);
    }
}

Integración con el comando `optimize`

Si el paquete tiene su propia caché, puedes integrarlo con php artisan optimize y php artisan optimize:clear mediante el método optimizes().

public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->optimizes(
            optimize: 'courier:cache',
            clear: 'courier:clear-cache',
        );
    }
}

Registrar clases de comando y registrar tareas de optimización son procesos distintos. Las colisiones de claves de registro, la exclusión con --except, el orden de ejecución respecto a las tareas estándar y el código de salida en caso de fallo se explican en Caché de paquetes e integración con optimize.

Añadir información al comando `about`

Para añadir información del paquete a la salida de php artisan about, utiliza AboutCommand::add().

use Illuminate\Foundation\Console\AboutCommand;

public function boot(): void
{
    AboutCommand::add('Courier Package', fn () => ['Version' => '1.0.0']);
}

Consulta Añadir información de diagnóstico del paquete a about para saber cuándo se evalúan los datos, cómo funcionan --only y la salida JSON, cómo evitar exponer secretos y cómo manejar el estado de registro en las pruebas.

Creación de fachadas

Las fachadas permiten invocar los bindings del service container como si fueran métodos estáticos.

Crea la clase de servicio

<?php

namespace Acme\Courier;

class CourierManager
{
    public function __construct(
        protected array $config,
    ) {}

    public function send(string $to, string $message): bool
    {
        // Procesamiento del envío del mensaje
        return true;
    }

    public function track(string $id): array
    {
        // Procesamiento de obtención de la información de seguimiento
        return ['status' => 'delivered'];
    }
}

Crea la clase de fachada

Extiende Illuminate\Support\Facades\Facade y devuelve la clave del binding del service container en getFacadeAccessor().

<?php

namespace Acme\Courier\Facades;

use Illuminate\Support\Facades\Facade;

/**
 * @method static bool send(string $to, string $message)
 * @method static array track(string $id)
 *
 * @see \Acme\Courier\CourierManager
 */
class Courier extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return \Acme\Courier\CourierManager::class;
    }
}

Vincúlala en el service provider

public function register(): void
{
    $this->app->singleton(\Acme\Courier\CourierManager::class, function ($app) {
        return new \Acme\Courier\CourierManager($app['config']['courier']);
    });
}

Regístrala en composer.json

"extra": {
    "laravel": {
        "providers": [
            "Acme\\Courier\\CourierServiceProvider"
        ],
        "aliases": {
            "Courier": "Acme\\Courier\\Facades\\Courier"
        }
    }
}

Al añadir anotaciones PHPDoc @method a los métodos de la fachada, se habilita el autocompletado del IDE.

// Invocar el servicio a través de la fachada
use Acme\Courier\Facades\Courier;

Courier::send('[email protected]', 'Tu paquete ha llegado');
$status = Courier::track('ABC-123');

DeferrableProvider — implementar la carga diferida

Los providers que solo realizan bindings al service container pueden implementar la interfaz DeferrableProvider para lograr una carga diferida. Como el provider no se carga hasta que un servicio se necesita realmente, mejora el rendimiento de la aplicación.

<?php

namespace Acme\Courier;

use Illuminate\Contracts\Support\DeferrableProvider;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        $this->app->singleton(CourierManager::class, function ($app) {
            return new CourierManager($app['config']['courier']);
        });
    }

    /**
     * Devuelve la lista de servicios que ofrece este provider
     *
     * @return array<int, string>
     */
    public function provides(): array
    {
        return [CourierManager::class];
    }
}

Laravel compila y almacena la lista de servicios que ofrecen los providers diferidos. El provider solo se carga cuando se resuelve alguno de los servicios enumerados en provides().

No utilices DeferrableProvider en providers que necesiten registrar recursos (vistas, rutas, listeners de eventos, etc.). Si se cargan de forma diferida, esos recursos podrían no quedar registrados.

Pruebas del paquete

Para probar el paquete por separado, utiliza Orchestra Testbench. Podrás escribir las pruebas del paquete como si estuvieras dentro de una aplicación Laravel normal.

composer require --dev orchestra/testbench

En el caso de prueba, sobreescribe getPackageProviders() para registrar el service provider del paquete.

<?php

namespace Acme\Courier\Tests;

use Acme\Courier\CourierServiceProvider;
use Orchestra\Testbench\TestCase as BaseTestCase;

class TestCase extends BaseTestCase
{
    /**
     * Registra los service providers del paquete
     */
    protected function getPackageProviders($app): array
    {
        return [
            CourierServiceProvider::class,
        ];
    }

    /**
     * Registra los alias de fachada del paquete
     */
    protected function getPackageAliases($app): array
    {
        return [
            'Courier' => \Acme\Courier\Facades\Courier::class,
        ];
    }

    /**
     * Configuración del entorno de pruebas
     */
    protected function defineEnvironment($app): void
    {
        $app['config']->set('courier.api_key', 'test-key');
    }
}

<?php

namespace Acme\Courier\Tests\Feature;

use Acme\Courier\Facades\Courier;
use Acme\Courier\Tests\TestCase;

class CourierTest extends TestCase
{
    public function test_can_send_message(): void
    {
        $result = Courier::send('[email protected]', 'Mensaje de prueba');

        $this->assertTrue($result);
    }
}

Publicación en Composer

Buenas prácticas para publicar el paquete en Packagist. Configuración básica de composer.json

{
    "name": "acme/courier",
    "description": "A Laravel courier package",
    "type": "library",
    "license": "MIT",
    "require": {
        "php": "^8.2",
        "illuminate/support": "^11.0||^12.0||^13.0"
    },
    "require-dev": {
        "orchestra/testbench": "^9.0||^10.0",
        "phpunit/phpunit": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "Acme\\Courier\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Acme\\Courier\\Tests\\": "tests/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "Acme\\Courier\\CourierServiceProvider"
            ],
            "aliases": {
                "Courier": "Acme\\Courier\\Facades\\Courier"
            }
        }
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}

Al depender de illuminate/support puedes incluir como dependencia únicamente los componentes de Laravel que necesites, en lugar de todo illuminate/framework. Mantén reducido el árbol de dependencias del paquete.

Ejemplo de estructura de directorios

acme/courier/
├── config/
│   └── courier.php
├── database/
│   └── migrations/
│       └── 2024_01_01_000000_create_courier_logs_table.php
├── lang/
│   └── es/
│       └── messages.php
├── resources/
│   └── views/
│       └── dashboard.blade.php
├── routes/
│   └── web.php
├── src/
│   ├── Console/
│   │   └── Commands/
│   │       └── InstallCommand.php
│   ├── Facades/
│   │   └── Courier.php
│   ├── Http/
│   │   └── Controllers/
│   │       └── TrackingController.php
│   ├── CourierManager.php
│   └── CourierServiceProvider.php
├── tests/
│   ├── Feature/
│   └── TestCase.php
├── composer.json
└── README.md

Páginas relacionadas

Service providers

Revisa los métodos register y boot de los service providers y los detalles de los providers diferidos.

Gestión de compatibilidad de versiones

Explica la estrategia para adaptarse a los cambios de versión mayor de Laravel y PHP y la configuración de la matriz de pruebas en GitHub Actions.

Desarrollo con IA

Patrones de diseño