Composer Config Plugin

Composer plugin for config assembling

Latest Stable Version Total Downloads Build Status Scrutinizer Code Coverage Scrutinizer Code Quality Dependency Status

This Composer plugin provides assembling of configurations distributed with composer packages. This allows to put configuration needed to use package right inside of the package thus implementing plugin system: package becomes a plugin holding both the code and it's configuration.

How it works?

Read more about the general idea behind this plugin in english or russian.


Add to require section of your composer.json:

"hiqdev/composer-config-plugin": "*"

Out of the box this plugin supports configs in PHP and JSON formats.

To enable additional formats require:


List your config files in composer.json like the following:

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

? marks optional files, absence of other files will cause exception.

$common is inclusion - common config will be merged into web.

Define your configs like this:

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

To load assembled configs in your application use require:

$config = require hiqdev\composer\config\Builder::path('web');

Refreshing config

Plugin hangs on composer POST_AUTOLOAD_DUMP event. I.e. composer runs this plugin on install, update and dump-autoload commands. As the result configs are just ready to be used after packages installation or updating.

After you make changes to any of configs you may want to reassemble configs manually - run:

composer dump-autoload

Can be shortened to composer du.

Also, you can force config rebuild from your application like this:

// Don't do it in production, assembling takes it's time
if (ENVIRONMENT === 'dev') {

Files processing order

Config files are processed in proper order to achieve naturally expected behavior:


There are several ways to debug config building internals.

composer dump-autoload --verbose

Can be shortened to composer du -v.

Known issues

This plugin treats configs as simple PHP arrays, no specific structure or semantics are expected and handled. It is simple and straightforward, but I'm in doubt... What about errors and typos? I think about adding config validation rules provided together with plugins. Will it solve all the problems?

Anonymous functions must be used in multiline form only:

return [
    'works' => function () {
        return 'value';
    // this will not work
    'noway' => function () { return 'value'; },


This project is released under the terms of the BSD-3-Clause license. Read more here.

Copyright © 2016-2017, HiQDev (