Laravel Package Development

What is a package?

In Laravel, a package is a Composer package that adds functionality to an application. There are two broad categories:

Standalone packages — General-purpose PHP libraries with no Laravel dependency (e.g., Carbon, Pest)
Laravel packages — Packages with routes, controllers, views, config, and other features tightly integrated with Laravel

This guide covers the latter: packages built specifically for Laravel. Package development requires a deep understanding of Laravel internals, including service providers, facades, and config publishing.

When writing tests for a package, use Orchestra Testbench. It lets you write package tests just as you would tests inside a normal Laravel application.

Package auto-discovery

When a package is installed, Laravel reads the extra.laravel section of composer.json and automatically registers service providers and facades.

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

With this configuration in place, users do not need to manually edit bootstrap/providers.php — the package is loaded automatically.

Package auto-discovery internals explains how this auto-discovery is implemented and when the cache is rebuilt.

Disabling auto-discovery

Users who want to disable auto-discovery for a specific package can do so in their application’s composer.json.

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

The role of service providers

A service provider is the entry point for a package. It is where you centralize the registration of views, config, migrations, routes, and other resources with Laravel. Service providers extend Illuminate\Support\ServiceProvider and have two methods: register and boot.

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    /**
     * Register package services.
     */
    public function register(): void
    {
        // Container bindings go here
        $this->mergeConfigFrom(
            __DIR__.'/../config/courier.php', 'courier'
        );

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

    /**
     * Bootstrap package services.
     */
    public function boot(): void
    {
        // Resource registration goes here
        $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');
    }
}

Do not register event listeners, routes, or views inside the register method. You might accidentally use a service from another service provider that has not yet been loaded. Always perform any work beyond bindings in the boot method.

To extend a service without creating it until it is used, and to apply configuration even when it has already been resolved, see Package service resolution hooks. It explains when callAfterResolving() runs and how to design for repeated application. To register services so that no state carries over in Octane or queue workers, see Package service lifetime design. It explains how scoped() works internally and the caveats around dependencies held by singletons.

Publishing config files

publishes() — publish files

Calling publishes() in the boot method allows users to copy config files into their application with the vendor:publish command.

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

Once published, config values are accessible the usual way.

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

mergeConfigFrom() — merge with defaults

Using mergeConfigFrom() in the register method ensures that the package’s default values are used even when users have not published the config file.

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

mergeConfigFrom() does not perform a deep merge for nested arrays. When a config has multi-dimensional arrays, options not defined by the user will not be merged from deeper levels.

For how this differs from Laravel 13’s recursive replace method, how lists with numeric keys are handled, and how to roll out updates when the config cache is in use, see Package config merging and caching.

Organizing with publish tags

Pass a tag as the second argument to publishes() so users can choose which resources to publish.

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');
}

# Publish only the config file
php artisan vendor:publish --tag=courier-config

# Publish everything provided by the service provider
php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider"

Registering routes

Use loadRoutesFrom() to load a routes file. It is automatically skipped when the application’s route cache is active.

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

Reference your package’s controllers inside the routes file.

// 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');
});

For declaring middleware explicitly, avoiding URI and route name collisions, and applying configuration changes to the cache, see Package route registration and caching.

Publishing migrations

Use publishesMigrations() to register migration files for publishing. In the default Laravel 13 configuration, database.migrations.update_date_on_publish is enabled, so Laravel updates the timestamps in the file names when they are published. If the setting is disabled or missing, Laravel does not update them.

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

For when to publish versus load directly, the conditions for timestamp changes, the risks of republishing, and schema changes for existing users, see Publishing and updating package migrations.

Publishing views

loadViewsFrom() — register views

Register a view directory with loadViewsFrom(). Use the namespace passed as the second argument to reference views with the package::view syntax.

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

After registration, reference views using the package namespace.

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

Laravel looks for views in two locations. It first checks resources/views/vendor/courier in the application; if nothing is found there, it falls back to the package’s view directory. This lets users customize views. For the lookup order in the implementation, per-file fallback, how to deliver changes to published templates, and how this differs from the Blade cache, see Overriding and updating package views.

Publishing views

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

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

Registering Blade components

To include components in your package, register them in the boot method.

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

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

You can also register components in bulk using a component namespace.

use Illuminate\Support\Facades\Blade;

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

{{-- Individual registration --}}
<x-courier-alert />

{{-- Namespace registration --}}
<x-courier::alert />

Distributing public assets

To distribute your package’s JavaScript, CSS, and images, use publishes() to register a copy to a location such as public_path('vendor/courier'). Updating the package does not automatically change files that have already been published. Narrowing the selection by tag and provider, the difference between --force and --existing, how deleted files are handled, and updates through laravel-assets are covered in Package public assets and updates.

Publishing translation files

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

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

// Using translations
echo trans('courier::messages.welcome');

For JSON translation files, use loadJsonTranslationsFrom().

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

Partial overrides of PHP translations, the load order and override location of JSON translations, translation key compatibility, and updating published files are covered in Package translation overrides and updates.

Registering commands

Register Artisan commands for your package using the commands() method. It is common practice to register them only in a console environment.

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,
        ]);
    }
}

Integrating with the optimize command

If your package has its own cache, use the optimizes() method to integrate with php artisan optimize and php artisan optimize:clear.

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

Registering a command class and registering an optimize task are separate operations. For registration key collisions, exclusion with --except, execution order relative to the built-in tasks, and exit codes on failure, see Integrating package caches with optimize.

Adding information to the `about` command

Use AboutCommand::add() to include package information in the output of php artisan about.

use Illuminate\Foundation\Console\AboutCommand;

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

For when the data is evaluated, --only and JSON output, designs that keep secrets out of the output, and registration state in tests, see Adding package diagnostics to about.

Creating a facade

A facade lets you call service container bindings as if they were static methods.

Create the service class

<?php

namespace Acme\Courier;

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

    public function send(string $to, string $message): bool
    {
        // Message sending logic
        return true;
    }

    public function track(string $id): array
    {
        // Tracking information retrieval logic
        return ['status' => 'delivered'];
    }
}

Create the facade class

Extend Illuminate\Support\Facades\Facade and return the service container binding key from 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;
    }
}

Bind it in the service provider

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

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

Adding @method PHPDoc annotations to the facade enables IDE auto-completion.

// Calling the service through the facade
use Acme\Courier\Facades\Courier;

Courier::send('[email protected]', 'Your package has arrived');
$status = Courier::track('ABC-123');

DeferrableProvider — implementing deferred loading

Providers that only perform service container bindings can implement the DeferrableProvider interface to achieve deferred loading. The provider is not loaded until the service is actually needed, improving application performance.

<?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']);
        });
    }

    /**
     * Get the services provided by the provider.
     *
     * @return array<int, string>
     */
    public function provides(): array
    {
        return [CourierManager::class];
    }
}

Laravel compiles and stores the list of services provided by deferred providers. The provider is loaded only when one of the services listed in provides() is resolved.

Do not use DeferrableProvider for providers that need to register resources (views, routes, event listeners, etc.). If the provider is deferred, those resources will never be registered.

Testing a package

Use Orchestra Testbench to test your package in isolation. It lets you write tests as if you were inside a normal Laravel application.

composer require --dev orchestra/testbench

Override getPackageProviders() in your test case to register the package’s service provider.

<?php

namespace Acme\Courier\Tests;

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

class TestCase extends BaseTestCase
{
    /**
     * Register the package's service providers.
     */
    protected function getPackageProviders($app): array
    {
        return [
            CourierServiceProvider::class,
        ];
    }

    /**
     * Register the package's facade aliases.
     */
    protected function getPackageAliases($app): array
    {
        return [
            'Courier' => \Acme\Courier\Facades\Courier::class,
        ];
    }

    /**
     * Define the test environment configuration.
     */
    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]', 'Test message');

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

Publishing to Composer

Best practices for publishing your package to Packagist. Basic composer.json configuration

{
    "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
}

Depending on illuminate/support rather than illuminate/framework keeps the dependency tree smaller by pulling in only the Laravel components you actually need.

Example directory structure

acme/courier/
├── config/
│   └── courier.php
├── database/
│   └── migrations/
│       └── 2024_01_01_000000_create_courier_logs_table.php
├── lang/
│   └── en/
│       └── 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

Service providers

Learn about the register and boot methods of service providers and the details of deferred providers.

Package auto-discovery internals

Learn how extra.laravel is collected, cached, and loaded through PackageManifest.

Package version compatibility

Learn how to manage Laravel and PHP version compatibility for your packages, including GitHub Actions test matrix configuration.

AI Development

Design Patterns

Package Development

Application Structure

Laravel 13 New Features

Eloquent Deep Dive

Validation Extensions

Authentication Extensions

Security

Queues

Testing

Realtime

What is a package?

Package auto-discovery

Disabling auto-discovery

The role of service providers

Publishing config files

publishes() — publish files

mergeConfigFrom() — merge with defaults

Organizing with publish tags

Registering routes

Publishing migrations

Publishing views

loadViewsFrom() — register views

Publishing views

Registering Blade components

Distributing public assets

Publishing translation files

Registering commands

Integrating with the optimize command

Adding information to the `about` command

Creating a facade

DeferrableProvider — implementing deferred loading

Testing a package

Publishing to Composer

Service providers

Package auto-discovery internals

Package version compatibility

​What is a package?

​Package auto-discovery

​Disabling auto-discovery

​The role of service providers

​Publishing config files

​publishes() — publish files

​mergeConfigFrom() — merge with defaults

​Organizing with publish tags

​Registering routes

​Publishing migrations

​Publishing views

​loadViewsFrom() — register views

​Publishing views

​Registering Blade components

​Distributing public assets

​Publishing translation files

​Registering commands

​Integrating with the optimize command

​Adding information to the about command

​Creating a facade

​DeferrableProvider — implementing deferred loading

​Testing a package

​Publishing to Composer

​Related pages

Service providers

Package auto-discovery internals

Package version compatibility

What is a package?

Package auto-discovery

Disabling auto-discovery

The role of service providers

Publishing config files

publishes() — publish files

mergeConfigFrom() — merge with defaults

Organizing with publish tags

Registering routes

Publishing migrations

Publishing views

loadViewsFrom() — register views

Publishing views

Registering Blade components

Distributing public assets

Publishing translation files

Registering commands

Integrating with the optimize command

Adding information to the `about` command

Creating a facade

DeferrableProvider — implementing deferred loading

Testing a package

Publishing to Composer

Related pages