Config Laravel Package

Getting Started

• Update to 6.1.0, run your test suite, and clear cached config before validating behavior:

  composer update vendor/package
  php artisan config:clear
  

• Look first at:
  • Definition in the package source, especially addConfigDirectory().
  • The package service provider / bootstrap code where Definition is configured.
  • The package’s config/ directory and any published config files.
  • Changelog/tests for the new DependencyInjection validations.
• First use case: ship package-level default config from one directory, then let application-level config directories override it without maintaining duplicate config files.
• Register directories in precedence order—lowest priority first, highest priority last:

  // Adjust to the package's actual Definition wiring.
  $definition->addConfigDirectory(__DIR__.'/config/defaults');
  $definition->addConfigDirectory(config_path('vendor/package'));
  

• After boot, verify effective values with config('package.key') rather than assuming merge order.

Implementation Patterns

• Layered config defaults: Put framework/package defaults in an internal config directory and register project-specific or environment-specific directories after them. Later directories should intentionally win.
• Package + app overrides: Use addConfigDirectory() as the package-friendly replacement for ad hoc mergeConfigFrom() calls when you need multiple config layers. Keep publishable config files for users who prefer explicit overrides.
• Environment layering: Register base defaults first, then environment-specific directories, then local/project overrides. Avoid registering the same directory twice.
• Testing merge behavior: Add temporary config directories in tests and assert final config() values. Explicitly test nested keys, associative arrays, and list/array replacement behavior.
• DependencyInjection integration: Define interfaces and bindings before resolving services. Use the improved DI API validations in CI to catch missing bindings, ambiguous implementations, or invalid definitions early.
• Service provider placement: Register config directories during package registration/boot before dependent services read config. If services are resolved too early, they may capture pre-merge values.
• Extension pattern: Wrap Definition configuration in your own package bootstrap helper if you need conditional directory registration based on environment, feature flags, or installed packages.

Gotchas and Tips

• Order is everything: Later config directories override earlier ones. Registering the application override directory before package defaults silently defeats the feature.
• Config cache: New config directories are not reflected in a cached config until you rebuild the cache. Run php artisan config:clear while developing and ensure deployment scripts rebuild config cache after code changes.
• Absolute, existing paths: Prefer absolute paths for config directories. Missing directories may be ignored or may fail depending on package validation—test the exact behavior.
• Merge semantics: “Full merge support” is powerful but can surprise you with nested arrays and numeric lists. Add tests for any deeply nested config structure you rely on.
• DI validations can surface upgrade issues: 6.1.0 is a minor release, but stricter DependencyInjection validations may expose previously hidden misconfigurations. Run a full boot/smoke test, not just unit tests.
• Avoid duplicate registration: Re-registering the same config directory can make precedence and merge behavior harder to reason about.
• Debugging: Log the registered config directories and their order, then dump effective config after boot. If a value is wrong, check directory order first, then cache, then merge semantics.
• Upgrade check: No explicit breaking changes or deprecations are listed, but validate container bindings and package boot after upgrading because DI validation behavior may be stricter.