Config Laravel Package

Getting Started

Start by installing the package via Composer (composer require spiral/config). Create a basic config directory (e.g., config/) and define your first config file as PHP-returning-array (e.g., config/app.php returning ['name' => 'MyApp', 'version' => '1.0']). In your app bootstrap, instantiate a ConfigManager and add a source:

use Spiral\Config\ConfigManager;
use Spiral\Config\Loader\PhpLoader;

$manager = new ConfigManager(new PhpLoader(__DIR__ . '/config'));
$config  = $manager->getConfig('app');
echo $config->get('name'); // 'MyApp'

The first use case is typically centralizing app constants (e.g., app name, debug mode, feature flags) — replacing scattered env() calls and untyped globals.

Implementation Patterns

• Modular config with namespaces: Organize configs by feature/module (e.g., config/database.php, config/cache.php). Access via $config->get('database.connections.mysql') using dot-notation.
• Environment overrides: Load environment-specific configs after base configs:

  $manager->addLoader(new PhpLoader(__DIR__ . '/config/env'), priority: 10);
  

  Files like config/env/production/database.php override base values.
• Environment-to-config bridge: Use env() only in a thin config/bridge.php to translate .env keys to PHP arrays, then expose via ConfigManager:

  // config/bridge.php
  return [
      'app' => [
          'debug' => filter_var($_ENV['APP_DEBUG'] ?? 'false', FILTER_VALIDATE_BOOLEAN),
      ],
  ];
  

• Caching in production: Dump a cached config aggregator (e.g., during deployment) by calling $manager->getCacheable()->export() into a PHP file, and load it in production via ArrayLoader to avoid runtime parsing.
• Injectable config: Wrap $config in a dedicated ConfigService or dependency-injection container to avoid tight coupling with ConfigManager.

Gotchas and Tips

• No runtime mutations: Config instances are immutable. Calling set() returns a new config instance — do not expect in-place changes. Use withConfig() or DI factories for runtime overrides.
• Source merge order matters: Later loaders with higher priority override earlier ones per key, not recursively. Use ConfigManager::addLoader($loader, $priority) to control precedence; default priority is 0.
• Dot-notation pitfalls: Ensure config arrays are flat enough for dot access. Nested arrays with numeric keys (e.g., ['db' => [0 => [...] ]]) won’t parse as db.0.connection.
• Environment variables as strings: $_ENV values are strings. Always cast explicitly (e.g., (int)$_ENV['PORT']) in bridge loaders — config package won’t auto-convert.
• Namespace collisions: Use unique prefixes per module to avoid accidental overwrites (e.g., my_package.timeout instead of timeout).
• Testing tip: Mock ConfigInterface directly in tests instead of ConfigManager for speed and isolation. Use $this->mock(ConfigInterface::class)->method('get')->with('key')->willReturn('value');
• No dynamic reloading: Once loaded/config is cached, changes to files won’t reflect in the same request. Implement hot-reload only if you manually reload loaders or use external cache invalidation.