Download the PHP package ellire/reprocess-templates without Composer
On this page you can find all versions of the php package ellire/reprocess-templates. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download ellire/reprocess-templates
More information about ellire/reprocess-templates
Files in ellire/reprocess-templates
Package reprocess-templates
Short Description Ellire simplifies deployment-specific configuration for your applications
License
Informations about the package reprocess-templates
Ellire - deployment-specific configuration management
Introduction
Ellire simplifies deployment-specific configuration for your applications.
You provide "macro" configuration for all different "profiles" your applications run in (e.g. dev, test, staging, prod) and with that Ellire can process all "template" files where macros are used to generate the final files relevant for the environment/deployment.
These 3 main concepts are covered in depth in the sections below.
Templates
A template file is any file in your application's codebase with the extension as defined in the dist_file_extension
macro (template
by default). Such files will be processed by Ellire and it will generate the non-template files (if you want to exclude certain directories from processing then provide them as a comma-separated list paths relative to the root of your project in the template_exclude_paths
macro).
Any files in your application that change depending on the server/environment they are deployed to should be made into templates.
Let have a look at a simple example. Imagine you have this file in your codebase under app/config/config.php
:
When running this application locally for example, you will have a different domain, you will want to enable debug mode and maybe stop sending emails out altogether or change the sender email.
To achieve this with Ellire you move your file to app/config/config.php.template
(or a different extension if you prefer by changing dist_file_extension
as mentioned earlier) and injecting macros into the new template file:
That's it. The template file is created. Now let's have a look at macros - what they are and where they come from.
Macros
Within Ellire a macro is a piece of config that has a name and a value. Macro values can depend (i.e. contain) other macro values. They are defined primarily in configuration files, but can also be provided via command line parameters and environment variables.
Continuing the example from the previous section imagine you have an ellire.json
file in you application with the following content...:
...your app/config/config.php.template
will be processed and Ellire will generate app/config/config.php
with the following values when using the dev
profile...:
...and the the following values when using the prod
profile:
The process of defining and resolving the macro values has a little more to it, so be sure to check out the macro configuration section.
This last example talks about the profile. This term is explained in the section below.
Profile
A profile in Ellire is essentially an identifier for the environment that your application is running in e.g. dev, staging, prod etc.
A profile is just an arbitrary string, so you can use anything that your prefer or that suits your application framwork (e.g. prod vs. production vs. live). The one exception to that is globals
which has a special meaning - it indicates configuration that applies to all profiles.
Macro values in the system, user and application configuration files are grouped by profile. This means you can pre-define and manage the configuration for all your servers in one file and when running Ellire it will resolve the correct macro values for the profile that applies to the current server you are on.
See the macro configuration section for more details on how the profile is resolved and used.
Macro configuration
Ellire resolves macro values based on the following:
- a system config file (
/etc/ellire.json
) - a user config file (
$HOME/.ellire/ellire.json
) - a local (application-specifc) config file which comes from your verison control system (e.g.
ellire.json
) - an instance-specific config file (e.g.
.ellire-instance.json
) - environment variables
- manual macro override values passed in to
ellire reprocess-templates
Note: the profile
, deploy_path
and config_extension
macro values are resolved first based on the globals
section of the system and user config file, then environment variables and macro overrides. If you provide their values anywhere else these will be ignored.
See below for details on all of these.
Different configuration files
System-wide
The system configuration file defines macro values for all users of the machine. This file is therfore particularly useful if you will be using more than 1 user account on the machine where Ellire is installed.
The system configuration file is in JSON format and needs to be placed in /etc/ellire.json
. It can contain default macro values for all profiles (the globals
section) as well as configuration for each profile your application can run in.
Example:
User-specific
The user configuration file defines macro values for the current user only. It is in JSON format and needs to be placed in $HOME/.ellire/ellire.json
. It can contain default macro values for all profiles (the globals
section) as well as configuration for each profile your application can run in.
Example:
Application-specific
The application specific file is the main configuration file - it is different per each application that you write. It should sit in the root of your project/application and be committed/checked-in to your version control system.
The file name for it is always ellire
however the extension that best suits you/your project can be configured via the config_extension
macro (the possible options are json
, yml
, xml
or ini
) in the system config file or the user config file. It can contain default macro values for all profiles (the globals
section) as well as configuration for each profile your application can run in.
Example:
Instance-specific
The instance file allows you to provide different macro values for the same application deployed on the same machine (e.g. multiple test/development versions of the same application running in parallel on the same machine). This file should never be committed/checked-in to your version control system.
The file name for it is always .ellire-instance
however the extension that best suits you/your project can be configured via the config_extension
macro (the possible options are json
, yml
, xml
or ini
) in the system config file or the user config file. It can only contain configuration for the current profile your application is running in.
Example:
Environment variables
Ellire will check the environment for values of any macros that it is aware of (i.e. you have defined them in the configuration files, or used them in any of the template files).
Macro values are read from variables with the ELLIRE_
prefix. For example:
- macro named
foo
can be set with theELLIRE_FOO
variable - macro named
5%off
can be set with theELLIRE_5_OFF
variable (non alphanumeric chars are replaced with an undererscore)
Macro overrides
Manual overriding of any macro value is also possible. This is done by passing in -m
or --macro
to the ellire reprocess-templates
command.
Each macro passed in has to be in a macroName=macroValue
format e.g.
Installation
Install Ellire globally with composer:
Create system/user configuration files
Once Ellire is installed you need to set up macro configuration specific for your machine/user account. To get you started on that the default config can be installed with an Ellire command:
Note: Installing the system config file requires a privileged user. Ellire will tell you if the installation fails and offer options for manual installation of the file.
Running
Running Ellire is very easy:
This will show you which template files were changed and which ones remained the same (were skipped).
To get more details about what Ellire is doing while running this you can enable the verbose more:
or the debug mode:
Note: in this mode all resolved macros (including any sensitive data you set like passwords, API keys etc.) will be dispayed on STDOUT.
Also as mentiod above you can provide individual macro values when running ellire:
Other commands
Aside from the main command to reprocess templates Ellire also provides the following:
to list all resolved and fully processed macros (templates are not changed) and
to show the profile used for the current deployment only (again templates will not be changed).
License
Ellire is licensed under the MIT License. For details see the LICENSE file.
Acknowledgments
This project is based on the brilliant (but now abandoned) WADF by Tim Jackson.
All versions of reprocess-templates with dependencies
symfony/finder Version ~2.7
symfony/config Version ~2.7
twig/twig Version ~1.0
symfony/console Version ~2.7
psr/log Version ^1.0