Composer Dist Installer
| Type |
Status |
| Build |
  
|
| Packagist |
   
|
Automatically installs .dist files when you run composer install in your project, and optionally populates them with
data using a very simple and intuitive templating syntax., (*1)
This project is designed to be framework-agnostic. All you need is to be using Composer to manage your project's dependencies., (*2)
Installation
Simply use Composer to install by running:, (*3)
composer require cube/composer-dist-installer:~1.0@beta
Usage
Add the following into your root composer.json file:, (*4)
{
"scripts": {
"post-install-cmd": [
"Cube\\ComposerDistInstaller\\Bootstrap::install"
]
},
"extra": {
"dist-installer-params": {
"file": "config/autoload/database.config.php.dist"
}
}
}
The file config/autoload/database.config.php will then be created based on the template provided at
config/autoload/database.config.php.dist and by asking you for any parameters requested in the .dist file., (*5)
By default, the dist file is assumed to be in the same place than the parameters file, suffixed by .dist.
This can be changed in the configuration:, (*6)
{
"extra": {
"dist-installer-params": {
"file": "config/autoload/database.config.php",
"dist-file": "some/other/folder/file/database.dist"
}
}
}
The script handler will ask you interactively for parameters which are requested in the .dist file, using optional
default values., (*7)
If composer is run in a non-interactive mode, the default values will be used for missing parameters., (*8)
Warning: If a configuration file already exists in the destination, you will be promted whether you want to override
it. If you choose to overwrite, a backup file will be created right next to the config file. You're in charge of
manually merging the differences between the new and the old file - and then deleting the old file., (*9)
Multiple Files
You can specify more than one file to be processed by using the following alternate syntax:, (*10)
{
"extra": {
"dist-installer-params": [
{
"file": "config/autoload/database.config.php",
"dist-file": "some/other/folder/file/database.dist"
},
{
"file": "config/autoload/session.config.php",
"dist-file": "some/other/folder/file/session.dist"
}
]
}
}
Template Syntax
Before the template files (.dist files) are copied to the final destination, a processor will look for any parameters
you may have included in the template and ask you for their value., (*11)
The syntax for a parameter is {{QUESTION|DEFAULT}}., (*12)
-
QUESTION: should contain the entire question, including question marks etc. Optionally include [] anywhere in the
string to specify the location of the default value within the question (otherwise there will be no indication that
there IS a default value).
-
DEFAULT: specify the default value. To use an environment variable as default use the following syntax:
=ENV[VARIABLE_NAME]
For example, consider the following template:, (*13)
<?php
return array(
'doctrine' => array(
'connection' => array(
// default connection name
'orm_default' => array(
'driverClass' => 'Doctrine\DBAL\Driver\PDOMySql\Driver',
'params' => array(
'host' => '{{Database host []?|localhost}}',
'port' => '{{Database port []?|3306}}',
'user' => '{{Database user []?|=ENV[USER]}}',
'password' => '{{Database password?}}',
'dbname' => '{{Database name?}}',
)
),
)
),
);
When installing the project, composer will ask you for all the information and use defaults where necessary. The prompt
would look something like this:, (*14)
$ composer install
# .... some composer output
Creating the config/autoload/database.config.php file
Destination file already exists, overwrite (y/n)? y
A copy of the old configuration file was saved to config/autoload/database.config.php.old
Database host [localhost]? test.db.acme.be
Database port [3306]? # <enter> to accept the default
Database user [staging]? # this default value was pulled from
# the "USER" environment variable.
Database password? 1234test
Database name? stage
And the final file will look like this:, (*15)
<?php
return array(
'doctrine' => array(
'connection' => array(
// default connection name
'orm_default' => array(
'driverClass' => 'Doctrine\DBAL\Driver\PDOMySql\Driver',
'params' => array(
'host' => 'test.db.acme.be',
'port' => '3306',
'user' => 'staging',
'password' => '1234test',
'dbname' => 'stage',
)
),
)
),
);
Environment Variables
It is possible to use environment values in order to set default values for parameters. The syntax for that is
{{Question|=ENV[VARIABLE_NAME]}}, where VARIABLE_NAME is the environment value that will provide the default., (*16)
In the example above, the following line used the USER environment variable as a default value:, (*17)
Multiple defaults for a parameter
It is also possible to have multiple default values (eg {{QUESTION|DEFAULT1|DEFAULT2}}.
This can be useful if you want to use environment variables as a default and, in case the environment variable is not set, fall back to a hardcoded default value., (*18)
Hence, you can write in your dis file for instance:, (*19)
myVar: {{"My var []?|=ENV[MY_VAR]|my_default_var}}
If the MY_VAR environment variable is set to 'foobar', the question will be:, (*20)
My var [foobar]?
If the MY_VAR environment variable is not set, the question will be:, (*21)
My var [my_default_var]?
Non-interactive mode
When composer is launched with --no-interaction option, the default value is applied.
This can be a good option for deployment process, in case you use environment variables in your dist file., (*22)
LICENSE
See LICENSE.txt file in this same package., (*23)
Credits
Copyright (c) 2015 by Cu.be Solutions, (*24)
Authors:
* Gabriel Somoza (gabriel.somoza@cu.be), (*25)
Wallogit.com
