Adding Publishable Configuration to a Laravel Package

When you add configuration to a Laravel package, make sure the package works before an application owner copies any files. Keep the package’s default settings available at runtime. Users can publish a copy when they want to change those settings.

A package service provider is the class Laravel uses to connect a package to the framework. In the provider, call mergeConfigFrom in register to load the package’s default settings. Then call publishes in boot to let users copy the config file into the application’s config directory. Users can edit that copy, and the package still supplies defaults for settings they leave out.

Load defaults and register the publishable file

Use the package’s config file as the source of defaults. The provider’s register method adds those defaults to Laravel’s runtime configuration. In boot, the provider tells Laravel which file users can copy and where to put it.

mergeConfigFrom(
            __DIR__.'/../config/package.php',
            'package'
        );
    }

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

Laravel uses the second argument to mergeConfigFrom as the configuration key, the name package code uses to access these settings. With package as the key, package code reads a setting with a call such as config('package.key'). This configuration pattern uses mergeConfigFrom to load defaults and publishes to register the config file for copying.

Keep the default config file valid and usable on its own. Laravel can then read the package settings as soon as the package is installed, even if the user has not published a copy. Choose defaults that let the package handle its intended basic use. Each package needs values suited to its feature; no single set of defaults fits every package.

Let users publish and override settings

Users copy the package config file into the application with:

php artisan vendor:publish --tag=config

Laravel writes the file to the path the provider declares, such as config/package.php. Users edit that copy to override the package’s settings. At runtime, mergeConfigFrom uses each value the user supplied and fills in missing values with the package defaults.

The merge updates Laravel’s runtime configuration in memory, leaving the published file on disk unchanged. This documented distinction between runtime merging and file editing matters when a package author expects a provider to change a config file.

Avoid publishing with --force as a routine update command:

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

The --force switch overwrites existing files, including a user’s edited config copy. The publishing command guidance explains this option. Use it only when you intend to replace the existing file.

If Laravel reports No publishable resources for tag [config]., check that the provider maps the package config file to the application’s destination and registers that mapping with the config tag. Without the mapping, Laravel’s publish command has no matching file to copy, as this Laravel Modules issue illustrates.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com