Getting Started

Install the Plugin:
```
composer require yiisoft/composer-config-plugin
```
Ensure you also install required format parsers (e.g., vlucas/phpdotenv for .env files).

Configure composer.json: Add a config-plugin section under extra to define your config files:

"extra": {
    "config-plugin": {
        "envs": "app.env",
        "params": ["config/params.php"],
        "web": ["config/web.php"]
    }
}

First Use Case: Run composer dump-autoload (or composer du). The plugin generates PHP config files in:
```
vendor/yiisoft/composer-config-plugin-output/
```
Load configs in your app via:
```
$config = require Yiisoft\Composer\Config\Builder::path('web');
```

Implementation Patterns

Environment-Aware Configs: Use .env files for environment-specific settings (e.g., db.env for database credentials). Reference them in envs:
```
"envs": ["app.env", "?.env.local"]
```
Modular Configs: Split configs into reusable sub-configs (e.g., db.php, mail.php). Reference them in other configs:
```
return [
    'components' => [
        'db' => Yiisoft\Composer\Config\Builder::require('db'),
    ],
];
```

Wildcard Inclusion: Dynamically include configs from modules or plugins:

"web": [
    "config/base.php",
    "../src/Modules/*/config/web.php"
]

Conditional Loading: Use optional files (?file.php) for dev-only configs or overrides:
```
"params": ["config/params.php", "?config/params-dev.php"]
```

Service Provider Bootstrapping: Load configs in a service provider’s boot() method:

public function boot()
{
    $config = require Yiisoft\Composer\Config\Builder::path('web');
    config($config);
}

Cache Configs: Store generated configs in Laravel’s cache (e.g., config('cache.store')) to avoid rebuilding on every request.

Environment Detection: Use Laravel’s env() helper to conditionally load configs:

if (app()->environment('local')) {
    Yiisoft\Composer\Config\Builder::rebuild();
}

File Processing Order:
- Configs in the root package override those in dependencies.
- Order matters: Later files in composer.json arrays overwrite earlier ones.
- Type hierarchy: envs → constants → params → configs.
Circular Dependencies: Avoid circular references between configs (e.g., web.php requiring db.php, which requires web.php). Use Builder::require() sparingly.
Windows Paths: Use forward slashes (/) or double backslashes (\\) in paths to avoid issues:
```
"web": ["config/web.php", "../src\\Modules\\*\\config\\web.php"]
```
Missing Optional Files: Omitting ? on required files (e.g., "params": ["missing.php"]) throws an error during composer du.
Output Directory Permissions: Ensure vendor/yiisoft/composer-config-plugin-output/ is writable. Configure a custom path in composer.json:
```
"extra": {
    "config-plugin-output-dir": "config/generated"
}
```

Verbose Mode: Run composer du -v to see the dependency hierarchy and debug missing files.
Inspect Generated Files: Check vendor/yiisoft/composer-config-plugin-output/ for raw config outputs. Useful for troubleshooting merges or typos.

Rebuilding: Force a rebuild in development:

if (app()->isLocal()) {
    Yiisoft\Composer\Config\Builder::rebuild();
}

Custom Formats: Extend support for formats like TOML or XML by implementing a parser and registering it with the plugin’s ConfigAssembler.
Post-Processing: Override config values after loading using Laravel’s config() mutators or package-specific logic:

$config = require Yiisoft\Composer\Config\Builder::path('web');
$config['components']['cache']['driver'] = 'redis';

Validation: Validate configs post-assembly using Laravel’s Validator or a library like spatie/laravel-data.
Dynamic Configs: Use Laravel’s config() helper to merge dynamic values (e.g., from API calls) into the assembled configs:

$config = require Yiisoft\Composer\Config\Builder::path('web');
$config['api']['timeout'] = request()->input('timeout');