Skip to content
Composer plugin for config assembling
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add issue and pull request templates Jul 31, 2019
src Config::putFile() should throw an exception when dir can not be created Aug 28, 2019
tests Greatly simplified export of closures Aug 1, 2019
.gitignore csfixed Jul 25, 2018
.scrutinizer.yml csfixed Jul 25, 2018
.travis.yml Redone travis config and require-dev phpunit Jul 31, 2019 version bump to 0.3.0 Apr 11, 2019
LICENSE Update Aug 20, 2019
chkipper.json version bump to 0.2.0 Mar 15, 2017
composer.json Fix #39: use opis/closure for dumping closure code Aug 1, 2019
hidev.yml Changed plugin versions to all dev-master Apr 11, 2019 version bump to 0.3.0 Apr 11, 2019
logo.png Improved readme Oct 8, 2018
phpunit.xml.dist csfixed Jul 25, 2018
version minor Sep 27, 2017

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. 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.

How it works?

  • Scans installed packages for config-plugin extra option in their composer.json
  • Loads .env files to set $_ENV variables
  • Requires defines files to set constants
  • Requires params files
  • Requires config files
  • Options collected during earlier steps could and should be used in later steps, e.g. $_ENV should be used for constants and parameters, which in turn should be used for configs
  • File processing order is crucial to achieve expected behavior: options in root package have priority over options from included packages. It is described below in File processing order section.
  • Collected configs are written as PHP files in vendor/hiqdev/composer-config-plugin-output directory along with information needed to rebuild configs on demand
  • Then assembled configs are ready to be loaded into application using require

Read more about the general idea behind this plugin in English or Russian.


composer require "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-output-dir": "path/relative-to-composer-json",
    "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.

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

Define your configs like the following:

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 uses composer POST_AUTOLOAD_DUMP event i.e. composer runs this plugin on install, update and dump-autoload commands. As the result configs are ready to be used right after package installation or update.

When you make changes to any of configs you may want to reassemble configs manually. In order to do it run:

composer dump-autoload

Above can be shortened to composer du.

If you need to force config rebuildign from your application, you can do it like the following:

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

File processing order

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

  • Options in outer packages override options from inner packages
  • Plugin respects the order your configs are listed in composer.json with
  • Different types of options are processed in the following order:
    • Environment variables from dotenv
    • Constants from defines
    • Parameters from params
    • Configs are processed last of all


There are several ways to debug config building internals.

  • Plugin can show detected package dependencies hierarchy by running:
composer dump-autoload --verbose

Above can be shortened to composer du -v.

  • You can see the list of configs and files that plugin has detected and uses to build configs. It is located in vendor/hiqdev/composer-config-plugin-output/__files.php.

  • You can see the assembled configs in the output directory which is vendor/hiqdev/composer-config-plugin-output by default and can be configured with config-plugin-output-dir extra option in composer.json.

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-2018, HiQDev (

You can’t perform that action at this time.