Home

Awesome

What is EnvSettingsTool?

Build Status

Author: Fabrizio Branca

EnvSettingsTool offers a concept to adjust settings for applications. Typically it is used during deployment. The settings for every Environment can be maintained in an CSV file.

CSV File

This is an example CSV file:

HandlerParam1Param2Param3DEFAULTdevboxintegrationstagingproduction
# Database parameters
Est_Handler_XmlFileapp/etc/local.xml/config/global/resources/default_setup/connection/hostlocalhost
# Dev settings
Est_Handler_Magento_CoreConfigDatadefault0dev/debug/profiler01

CSV file

Each row is one setting. A setting is changed by a "handler", and each handler support up to 3 parameters. The next columns represent the values for the environments, and you may use the "DEFAULT" key for a default setting. Empty column values will fall back to the "DEFAULT" column (instead of setting an empty value). If you want to set an empty value instead configure that cell with --empty-- and it will set an empty value instead of falling back.

Usage

The tool comes with 3 commands:

Dry-Run

Just print out the Handler and Values that would be executed:

php dryRun.php devbox ../settings.csv

Apply

Execute the handlers and show status summary:

php apply.php devbox ../settings.csv

Get single value

Returns the value for a certain handler. For example - this can be used to get database values for other scripts:

php value.php devbox ../Settings.csv HandlerName param1 param2 param3

Example

DB_HOST=`EnvSettingsTool/value.php ${ENVIRONMENT} settings.csv Est_Handler_XmlFile app/etc/local.xml /config/global/resources/default_setup/connection/host`

Example setup script snippet

echo "Appling settings"
cd htdocs
php ../Setup/EnvSettingsTool/apply.php ${ENVIRONMENT} ../Setup/Settings.csv || exit 1

Handlers

Special Features

Comments and empty lines

Empty lines or lines starting with '#' or '/' will be ignored. Use this to insert some comments into the csv file.

Skipping rows

If the value field of a row for the current environment is --skip-- this handler will not be executed

Environment variables

The Values also support the special syntax ###ENV:VARIABLE### to read stuff from the (bash) environment Variables.

Reading file content

The special syntax ###FILE:filename### allows to read the content of a file and insert the trimmed value.

Example:

Est_Handler_XmlFile('app/etc/local.xml', '/config/global/cache/id_prefix', '') = x###FILE:../build.txt###_

Will read the content of ../build.txt and insert it in the id_prefix node: x72_

Loops

param1, param2 and param3 can specify loops using this syntax: {{1|2|3}}. In this case the same handler will be executed multiple times using every values. It's also possible to have loops in two or all three parameters. In this case all combinations will be executed.

Example:

Est_Handler_Magento_CoreConfigData('stores', '{{1|2|3}}', 'web/unsecure/base_url') = 'http://www.foo.com'

Is equal to:

Est_Handler_Magento_CoreConfigData('stores', '1', 'web/unsecure/base_url') = 'http://www.foo.com'
Est_Handler_Magento_CoreConfigData('stores', '2', 'web/unsecure/base_url') = 'http://www.foo.com'
Est_Handler_Magento_CoreConfigData('stores', '3', 'web/unsecure/base_url') = 'http://www.foo.com'

This loop resolution now also works within paramters:

Est_Handler_Magento_CoreConfigData('stores', '1', 'a/b/{{c|d|e}}') = 'http://www.foo.com'

Is equal to:

Est_Handler_Magento_CoreConfigData('stores', '1', 'a/b/c') = 'http://www.foo.com'
Est_Handler_Magento_CoreConfigData('stores', '1', 'a/b/d') = 'http://www.foo.com'
Est_Handler_Magento_CoreConfigData('stores', '1', 'a/b/e') = 'http://www.foo.com'

Multiple loops are also support within the same parameter:

Est_Handler_Magento_CoreConfigData('stores', '1', '{{a|b}}_{{c|d}') = 'http://www.foo.com'

Is equal to:

Est_Handler_Magento_CoreConfigData('stores', '1', 'a_c') = 'http://www.foo.com'
Est_Handler_Magento_CoreConfigData('stores', '1', 'a_d') = 'http://www.foo.com'
Est_Handler_Magento_CoreConfigData('stores', '1', 'b_c') = 'http://www.foo.com'
Est_Handler_Magento_CoreConfigData('stores', '1', 'b_d') = 'http://www.foo.com'

Empty values in loops are also allowed:

Est_Handler_Magento_CoreConfigData('stores', '1', 'web/secure/base{{_skin|_media|_js|}}_url') = 'http://www.foo.com'

Is equal to:

Est_Handler_Magento_CoreConfigData('stores', '1', 'web/secure/base_skin_url') = 'http://www.foo.com'
Est_Handler_Magento_CoreConfigData('stores', '1', 'web/secure/base_media_url') = 'http://www.foo.com'
Est_Handler_Magento_CoreConfigData('stores', '1', 'web/secure/base_js_url') = 'http://www.foo.com'
Est_Handler_Magento_CoreConfigData('stores', '1', 'web/secure/base_url') = 'http://www.foo.com'

Fallback

An empty cell falls back the configured DEFAULT column. If you actually need that value to be empty use --empty-- instead.

References to other environments

You can reference to values from another environment by adding this to the value: ###REF:targetenvironment###

Special markers

Ignore errors

If a handler name if prefixed with @ then this error will be ignored and the apply command continues walking through the list.

Groups

The csv settings file can cotain another column labelled with "GROUPS" (all uppercase!). Every value in this column can be a comma separated list of groups (or 'tags' if you like) similar to how PHPUnit handles groups.

When calling the apply.php script you can pass --groups <comma-separated list of groups> or --exclude-groups <comma-separated list of groups>. If --groups is set only the lines will be processed that have at least one of the groups passed as a parameter. If --exclude-groups is set the lines will be skipped if they have at least one group in common with what is specified.

Please note that the argument does not support '=' but only spaces. (use --groups db, not --groups=db)

Example:

# Will only execute rows tagged with 'db'
./apply.php devbox ../Configuration/settings.csv --groups db

# Will skip executing rows tagged with 'db'
./apply.php devbox ../Configuration/settings.csv --exclude-groups db

Tips and tricks

Admin user management

Disable all admin users:

Est_Handler_Magento_AdminUserActivate('%', '%', '%') = 0

Enable user 'john.doe':

Est_Handler_Magento_AdminUserActivate('john.doe', '%', '%') = 1

Enable user with email address 'info@example.com':

Est_Handler_Magento_AdminUserActivate('%', 'info@example.com', '%') = 1

Enable all user with email addresses '...@example.com':

Est_Handler_Magento_AdminUserActivate('%', '%@example.com', '%') = 1

Enable all users with role 'Customer Service':

Est_Handler_Magento_AdminUserActivate('%', '%', 'Customer Service') = 1

Remember that EnvSettingsTool processes the csv file from top to bottom. You can use this to add exact control over what accounts should be enabled or not.

Delete values

If you're setting Magento core_config_data values and you want to be sure that there's no other value that might interfere with your values (e.g. in a different scope) you can delete all values first:

HandlerParam1Param2Param3DEFAULT
Est_Handler_Magento_CoreConfigData%%dev/debug/profiler--delete--
Est_Handler_Magento_CoreConfigDatadefault0dev/debug/profiler0

Use via Composer

Add this to your composer.json to resolve the dependency through composer:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/AOEpeople/EnvSettingsTool"
    }
],
"require": {
    "aoepeople/envsettingstool": "~1.0"
}

Changelog

Version 1.0.0

Version 1.1.0

Version 1.2.0