Composer plugin and a library for config assembling

Fund package maintenance!
Open Collective

Installs: 4 874

Dependents: 11

Suggesters: 0

Security: 0

Stars: 12

Watchers: 16

Forks: 3

Open Issues: 6


dev-master / 1.0.x-dev 2021-05-12 15:13 UTC




Composer plugin for config assembling.

Latest Stable Version Total Downloads Build status Scrutinizer Code Quality Code Coverage

This [Composer] plugin provides assembling of configurations distributed with composer packages. It allows putting configuration needed to use a package right inside of the package thus implementing a plugin system. The package becomes a plugin holding both the code and its configuration.


composer require "yiisoft/config"

How it works?

The package consist of two parts: Composer plugin and config loader.

After composer updates its autoload file, and that happens after dump-autoload, require, update or remove, Composer plugin:

  • Scans installed packages for config-plugin extra option in their composer.json.
  • Copies missing config files into the project configs.
  • Writes a merge plan into config/packages/merge_plan.php. It includes configuration from each package composer.json.
  • Tracks change to configuration files from the vendor by storing metadata in the config/packages/dist.lock file.
  • In the interactive console mode it asks what to do with modified configs after updating packages in the vendor.

In the application entry point, usually index.php, we create an instance of config loader and require a configuration we need:

$config = new \Yiisoft\Config\Config(dirname(__DIR__));
$webConfig = $config->get('web');

The web in the above is a config group. The config loader obtains it runtime according to the merge plan.

Config groups

Each config group represents a set of configs that is merged into a single array. It is defined per package in each package composer.json:

"extra": {
    "config-plugin": {
        "params": [
        "common": "config/common.php",
        "web": [
        "other": "config/other.php"


  • ? - marks optional files. Absence of files not marked with it will cause exception.

    "params": [

    It's okay if params-local.php will not found, but it's not okay if params.php will be absent.

  • * - marks wildcard path. It means zero or more matches by wildcard mask.

    "web": [

    It will collect all web.php in any sub-folders of src/Modules/ in config folder.

  • $ - reference to another config.

    "params": [
    "params-console": [
    "params-web": [

    Output files params-console.php and params-web.php will contain params.php and params-local.php.

Define your configs like the following:


return [
    'components' => [
        'db' => [
            'class' => \my\Db::class,
            'name' => $params['db.name'],
            'password' => $params['db.password'],

A special variable $params is read from params config.

Using sub-configs

In order to access a sub-config, use the following in your config:

'routes' => $config->get('routes');


A number of options is available both for Composer plugin and a config loader. Composer options are specified in composer.json:

"extra": {
    "config-plugin-output-dir": "/config/packages",
    "config-plugin-source-dir": "/config",
    "config-plugin": {
        // ...


In the above config-plugin-output-dir points to where configs will be copied to. The path is relative to where composer.json is. The option is read for the root package, which is typically an application. Default is "/config/packages".

If you change output directory, don't forget to adjust configs path when creating an instance of Config. Usually that is index.php:

$config = new \Yiisoft\Config\Config(
    '/config/packages', // Configs path.
$webConfig = $config->get('web');

config-plugin-source-dir points to where to read configs from for the package the option is specified for. The option is read for all packages. The value is a path relative to where package composer.json is. Default value is /config.

Warning: config-plugin-source-dir is not implemented yet.


The plugin adds extra config-diffcommand to composer. It displays the difference between the vendor and application configuration files in the console.

# For all config files
composer config-diff

# For the config files of the specified packages
composer config-diff yiisoft/aliases yiisoft/view


The config package is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.


The plugin is heavily inspired by Composer config plugin originally created by HiQDev (http://hiqdev.com/) in 2016 and then adopted by Yii.