yiisoft / composer-config-plugin
Composer plugin for config assembling
Fund package maintenance!
Open Collective
yiisoft
Installs: 81 829
Dependents: 38
Suggesters: 0
Security: 0
Stars: 30
Watchers: 9
Forks: 14
Open Issues: 19
Type:composer-plugin
Requires
- php: ^7.4|^8.0
- composer-plugin-api: ^1.0|^2.0
- ext-json: *
- composer/composer: ^1.0|^2.0
- opis/closure: 3.6.x-dev@dev
- riimu/kit-phpencoder: ^2.4
- yiisoft/files: ^1.0
Requires (Dev)
- phpunit/phpunit: ^9.4
- roave/infection-static-analysis-plugin: ^1.6
- spatie/phpunit-watcher: ^1.23
- vimeo/psalm: ^4.3
Suggests
- symfony/yaml: ^2.0 || ^3.0 || ^4.0 for YAML files support
- vlucas/phpdotenv: ^2.0 for `.env` files support
- dev-master / 1.0.x-dev
- 0.6.0
- 0.5.1
- 0.5.0
- 0.4.0
- 0.3.0
- 0.2.5
- 0.2.4
- 0.2.3
- 0.2.2
- 0.2.1
- 0.2.0
- 0.1.0
- 0.0.9
- 0.0.8
- 0.0.7
- 0.0.6
- 0.0.5
- 0.0.4
- 0.0.3
- 0.0.2
- 0.0.1
- dev-dependabot/composer/yiisoft/files-tw-2.0
- dev-dependabot/github_actions/actions/cache-3.0.1
- dev-dependabot/github_actions/actions/checkout-3
- dev-ga-builds-on-schedule
- dev-dependabot/github_actions/shivammathur/setup-php-2.11.0
This package is auto-updated.
Last update: 2022-08-06 05:27:29 UTC
README
Composer Config Plugin
Composer plugin for config assembling.
⚠️ The plugin is no longer supported in favor of yiisoft/config.
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.
Documentation
How it works?
- Scans installed packages for
config-plugin
extra option in theircomposer.json
. - Loads
.env
files to set$_ENV
variables. - Requires
constants
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/yiisoft/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.
Installation
composer require "yiisoft/composer-config-plugin"
Out of the box this plugin supports configs in PHP and JSON formats.
To enable additional formats require:
- vlucas/phpdotenv - for
.env
files. - symfony/yaml - for YAML files,
.yml
and.yaml
.
Usage
List your config files in composer.json
like the following:
"extra": { "config-plugin-output-dir": "path/relative-to-composer-json", "config-plugin": { "envs": "db.env", "params": [ "config/params.php", "?config/params-local.php" ], "common": "config/common.php", "web": [ "$common", "config/web.php" "../src/Modules/*/config/web.php" ], "other": "config/other.php" } },
Markers
-
?
- marks optional files. Absence of files not marked with it will cause exception."params": [ "params.php", "?params-local.php" ]
It's okay if
params-local.php
will not found, but it's not okay ifparams.php
will be absent. -
*
- marks wildcard path. It means zero or more matches by wildcard mask."web": [ "../src/Modules/*/config/web.php" ]
It will collect all
web.php
in any subfolders ofsrc/Modules/
inconfig
folder. -
$
- reference to another config."params": [ "params.php", "?params-local.php" ], "params-console": [ "$params", "params-console.php" ], "params-web": [ "$params", "params-web.php" ]
Output files
params-console.php
andparams-web.php
will containparams.php
andparams-local.php
.
Define your configs like the following:
<?php return [ 'components' => [ 'db' => [ 'class' => \my\Db::class, 'name' => $params['db.name'], 'password' => $params['db.password'], ], ], ];
A special variable $params
is read from params
config.
To load assembled configs in your application use require
:
$config = require Yiisoft\Composer\Config\Builder::path('web');
Using sub-configs
In some cases it is convenient to extract part of your config into another file. For example, we want to extract database
configuration into db.php
. To do it add the config to composer.json
:
"extra": { "config-plugin-output-dir": "path/relative-to-composer-json", "config-plugin": { "envs": "db.env", "params": [ "config/params.php", "?config/params-local.php" ], "common": "config/common.php", "web": [ "$common", "config/web.php" ], "other": "config/other.php", "db": "config/db.php" } },
Create db.php
:
<?php return [ 'class' => \my\Db::class, 'name' => $params['db.name'], 'password' => $params['db.password'], ];
Then in the config use Builder::require()
:
<?php use Yiisoft\Composer\Config\Builder; return [ 'components' => [ 'db' => Builder::require('db'), ], ];
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 rebuilding from your application, you can do it like the following:
// Don't do it in production, assembling takes it's time if (getenv('APP_ENV') === 'dev') { Yiisoft\Composer\Config\Builder::rebuild(); }
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
envs
. - Constants from
constants
. - Parameters from
params
. - Configs are processed last of all.
- Environment variables from
Debugging
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 assembled configs in the output directory which is
vendor/yiisoft/composer-config-plugin-output
by default and can be configured withconfig-plugin-output-dir
extra option incomposer.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?
License
This project is released under the terms of the BSD-3-Clause license. Read more here.
Copyright © 2016-2020, HiQDev (http://hiqdev.com/) Copyright © 2020, Yiisoft (https://www.yiiframework.com/)