Naming Configuration Keys in Laravel Packages

When you publish a Laravel package, users may copy its configuration file into their application and set values that the package reads later. Users rely on those names when they set values for your package. Choose names that clearly describe each setting, follow one consistent style, and remain stable across releases.

Laravel lets packages publish and read configuration, but it does not require every package to use the same naming style. In a path such as search.request_timeout, search is the package’s configuration namespace and request_timeout is an individual key. The full dotted path tells Laravel which value to retrieve.

Give the package its own namespace

Use a recognizable package name as the top-level configuration namespace, the first part of a configuration path. Laravel’s package-development example publishes config/courier.php and reads a value with config('courier.option'), showing how the filename, namespace, and dotted path relate. The package author chooses the names within that structure.

For example, a search package could use:

// config/search.php
return [
    'request_timeout' => 10,
];

Package code can read the setting with:

config('search.request_timeout');

A package-specific namespace helps users identify which package owns a setting. Avoid broad names such as settings, options, or api as the top-level namespace; another package or the application itself could use the same name.

Choose configuration filenames and keys separately. Spatie’s Laravel style guide recommends kebab-case filenames, such as pdf-generator.php, and snake_case keys, such as chrome_path. Spatie documents this convention; Laravel leaves the choice to package authors. Pick a convention your package can apply consistently, then document it.

Make each key explain what it controls

A good key tells users what value they are setting without requiring them to read the package code. Prefer api_token to key, and request_timeout to timeout when the package might expose more than one timeout. Avoid abbreviations such as req_to unless their meaning is already clear to package users.

Consistency also helps users spot mistakes. Do not mix requestTimeout, request_timeout, and request-timeout in the same configuration file. If related settings need grouping, use names that remain readable at each level:

return [
    'retry' => [
        'max_attempts' => 3,
    ],
];

For every option users can set, document its purpose, expected type, and default. That gives users enough information to set it correctly and helps package authors preserve the setting’s meaning as features grow.

Keep published keys compatible

After users publish a package’s configuration file, their applications may rely on its keys. Renaming search.request_timeout to search.timeout breaks those references unless the package continues to accept the old key.

Semantic Versioning says that backward-incompatible changes to a declared public API require a major version increment. Applying this rule to published configuration keys is a package-design choice. SemVer does not specifically classify Laravel config keys, but users who set them rely on them.

When a rename is necessary, introduce the new key while continuing to accept the old one for a transition period. Document which value takes precedence if users set both. Remove the old key in a release that clearly signals the breaking change.

Design nested arrays carefully. They group related options, but Laravel’s 10.x package documentation says mergeConfigFrom merges only the first level of a configuration array. Laravel does not necessarily fill missing values inside a user-defined nested array from the package defaults. Choose a structure that users can override predictably, and test that behavior against the Laravel versions your package supports.

Keep environment names separate from config paths

An environment variable is an external value, often supplied through deployment settings. A Laravel config path is the key package code uses to retrieve a value. Keep the two names distinct:

// config/search.php
return [
    'api_token' => env('SEARCH_API_TOKEN'),
];

Package code should then read config('search.api_token'). Laravel’s configuration documentation advises calling env() from configuration files and using the config system elsewhere. This separation also matters when configuration is cached, because Laravel does not load the .env file during requests or Artisan commands after configuration is cached.

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