Config Laravel Package

Getting Started

Start by installing the package via Composer: composer require league/config. Then, define your configuration schema using League\Config\Configuration and Nette’s Expect helpers (auto-imported from nette/schema). The first use case is typically creating a centralized config container for your app’s core services (e.g., database, logging, mailer). Begin with a simple schema in a dedicated config class or service provider:

use League\Config\Configuration;
use Nette\Schema\Expect;

$config = new Configuration([
    'app' => Expect::structure([
        'name' => Expect::string()->required(),
        'debug' => Expect::bool()->default(false),
    ]),
]);

Merge initial values (e.g., from .env or arrays), and access validated config with dot notation: $config->get('app.name'). Refer to the basic usage docs for immediate hands-on examples.

Implementation Patterns

• Service Provider / Config Class: Encapsulate schema definition and merging in a singleton or service class (e.g., AppConfig). Use addSchema() to modularize schemas across domains (e.g., DatabaseConfig::schema(), QueueConfig::schema()).
• Environment-Based Merging: Merge config conditionally based on environment:

  $config->merge($_ENV); // Simple flat env import
  if ($env === 'prod') {
      $config->set('database.ssl', true);
  }
  

• Validation Assertions: Use custom assertions for runtime constraints (e.g., directory existence, dependency checks):

  'log_path' => Expect::string()
      ->assert(fn ($path) => is_dir($path) || is_writable(dirname($path)))
      ->required()
  

• Lazy Loading Pattern: Deliberately avoid fetching config until needed—validation runs only on get(), enabling safe config setup before dependencies are ready (e.g., before Doctrine/bootstrap).
• Dependency Injection: Inject Configuration into services that require config, or expose a typed accessor (e.g., $dbConfig = $config->get('database')) to decouple from the library.

Gotchas and Tips

• Immutable Schemas: Schema changes must be done at setup time—set()/merge() only affect values, not schema structure. Trying to add a new key beyond the schema throws InvalidConfigurationException.
• Lazy Processing Side Effects: Defaults/validations fire on read, not write. Ensure assertions (e.g., is_writeable()) don’t fail silently if paths aren’t created yet. Always test validation in production-like environments.
• Dot vs. Slash Notation: Both config.get('foo.bar') and config.get('foo/bar') work, but mixing conventions in large apps can cause confusion. Pick one and enforce it in code review.
• Nette Schema Quirks: Use Expect::string()->nullable() explicitly for optional strings (missing vs. null). default(null) alone doesn’t make a field nullable—schema validation will reject null unless declared.
• Extension Points: For advanced needs, wrap Configuration in your own class to add validation helpers or typed getters (e.g., getDbDriver(): string). Avoid extending Configuration directly—its API is stable but internal behavior isn’t guaranteed.
• No File Loading Built In: Unlike symfony/config, this package doesn’t load YAML/JSON. Implement your own loader if needed (e.g., parse .env with vlucas/phpdotenv, convert to arrays, then merge()).