Config Laravel Package

Getting Started

Confirm the gate before you write any code. This package's major version tracks the Laravel major, and v6.0.0 exists to add Laravel 8 support. If the app is on Laravel 9+, Composer will not resolve and nothing application-side fixes it. Start with:

composer why-not orchestra/config ^6.0   # tells you the blocker in one line
composer show orchestra/config           # PHP range and illuminate/* constraint

Install and read, in this order:

1. composer.json — the illuminate/* constraint is the compatibility statement. There is no upgrade guide, so the constraint is the contract.
2. The service provider in src/ — this is the whole package's behaviour in a few dozen lines.
3. The Repository class — almost certainly a subclass of Illuminate\Config\Repository. Everything else is a thin shell around it.
4. Any published config stub, diffed against nothing yet.

The mental model. This is not a new config system. It rebinds Laravel's config container entry to a repository with extra surface, so config(), the Config facade, and every third-party package keep working unchanged. Your job is to not fight that.

First use case. Modular config with defaults plus app-level overrides. Your package ships config/billing.php defaults; the host app publishes and edits a copy; the app value wins. That precedence ladder — library default → package default → environment → tenant → runtime override — is the one thing worth writing down on day one and testing.

Implementation Patterns

Rebinding the repository. Register after the framework's own config provider so the binding actually takes effect, and keep the swapped class thin:

$this->app->singleton('config', fn ($app) => new \Orchestra\Config\Repository(
    new \Illuminate\Config\FileLoader($app['files'], $app->configPath()),
    $app->environmentPath(),
    $app->environment()
));

Anything that reads config during register() before this runs gets the stock repository. If a feature silently ignores your override, provider order is the first suspect.

Layering, not replacing. Prefer mergeConfigFrom() in your own module providers for defaults, and reserve this package for the cases where you need repository-level behaviour (runtime writes, per-tenant resolution, inspection). Two mechanisms doing the same merge is how you get drift.

Runtime overrides per request. The natural fit is tenant/brand/plan variation:

// in a middleware, before the request hits domain code
foreach ($tenant->configOverrides() as $key => $value) {
    config([$key => $value]);
}

Under Octane or any long-lived worker, reset overrides per request — a scoped binding or a middleware terminate() that restores the original array. Otherwise tenant A's discount rate leaks into tenant B's response, and it will be the hardest bug of your quarter.

Feature flags. Config files are a fine home for kill switches and per-account enablement until you need an audit trail or an admin UI. Decide that explicitly: file-based flags have a deploy cost; DB-backed flags have a caching and permissions cost. Don't discover the answer during an incident.

Testing. Point the container at a plain Illuminate\Config\Repository in setUp() with a fixture array, and assert on resolved values, not on the presence of files. Add one test that asserts the key set of each published config file — that catches renamed keys, which is the failure mode this package is most likely to hand you.

Caching. php artisan config:cache flattens everything into a single array. Runtime overrides still work (they're in memory), but any override logic that runs at boot must run after the cached file loads. Always config:clear after installing or bumping the package.

Gotchas and Tips

• Renamed keys fail silently. A key renamed between majors with an unchanged default produces no error — just wrong behaviour in production. Diff the published config against your app's copy by hand on every bump; never republish over it.
• The blast radius is the whole app. Config loads at boot and is read everywhere. A defect here doesn't stay in the feature that adopted it. Keep business logic out of the repository subclass.
• You are the QA. Zero dependents means nobody else is exercising this in production. Ship a smoke test that boots the app and asserts a handful of critical config values resolve as expected; that's your regression net.
• Pin the major to the Laravel major. Schedule the package bump as a line item in the framework-upgrade program, not as a surprise. Record it in the dependency risk register with a named owner — an unowned dependency with stale framework support is how you get locked out of an upgrade later.
• Don't cache objects or closures. Anything unserializable in a config array breaks config:cache at deploy time, usually in CI on a Friday.
• Queue workers and artisan serve hold stale config. Restart long-running processes after any config change; in dev this looks like "my change didn't apply."
• Extension point. Subclass the repository when you need an accessor (typed getters, a config()->tenant() helper) rather than adding global helper functions. Keep the parent contract intact so framework code and other packages keep working.
• When it's overkill. Single-tenant, single-environment, a handful of config files — Laravel's native config/ directory is already the answer, and adding a layering concept gives you a precedence order to get wrong for no benefit.
• Debugging. Log the resolved value of your overridden keys once at boot in staging. Reading the source is the support model here; make your own visibility good.