This document is created to list all options for solving Symphony Issue 669. The goal is to find a way to make the config.php file aware of the environment on which it runs and to make it sharable between developers. Most of the configuration settings are the same for all environments, so only a subset needs to be changeable to deal with the differences between multiple local environments during development and releasing to T/A/P.
- Allow environment specific configuration
- Allow configuration to be shared between developers
- require minimal core changes
- require no breaking changes to the Configuration class
- be relatively backwards compatible with the ability to update the old format to the new format
- be secure
- implement the minimum, and allow an extension to take care of the edge cases
There are several ways to solve this problem. Below is a list of four possible implementations with their pros and cons.
- Private sections in config.php
- Environment specific sections in config.php
- Environment specific configuration files (included on naming convention)
- JAVA style property replacement
At the end of the config.php there will be a private section which will not be overwritten when the document is saved by the Configuration class. A preset marker will be used to separate the two sections.
Default configuration should go in the regular config.php and settings should be overwritten by the private section.
- Meets requirements 3,4,5,7. Requirement 6 is only met when this feature is used by smart people.
- Single configuration file
- Allows any type of custom PHP code to be added
- It does not meet requirement 1 & 2: this only works in a single-user setting. The contents of this file will still live in version control. Changes are shared with all team members. In order for everybody to be able to work with the project, they will need to adjust their local environment to match the settings in the config.php file.
- Teams can still meet requirement 1 & 2 if they are smart enough to use this ability to implement propasal 3: including environment specific config files which are not in version control and contain settings specific to that environment. So why not just do that in the first place?
- It is potentially insecure: environment specific information could end up in version control.
At the end of the config.php there will be a environment specific section which will not be overwritten when the document is saved by the Configuration class. A marker based on the host name will be used to separate the multiple configuration sections.
Default configuration should go in the regular config sections and settings should be overwritten by the environment specific section.
- Meets requirements 1,2,3,4,5,7
- Single configuration file
- Allows any type of custom PHP code to be added
- Configuration file can become unmanageable in case of large number of environments.
- Insecure: environment specific information is committed to version control and available to all team members.
The environment specific configuration lives in a separate file. This can included based on fixed name (environment.php), a file named after the host (MyLocalHostName.php) or pattern inclusion (config.*.php). The environment specific configuration files can live outside version control and are thus truly independent.
Default configuration should go in the regular config.php and settings should be overwritten by the included files.
- Meets requirements 1,2,3,4,5,6,7
- Allows any type of custom PHP code to be added
- Creates multiple sources for configuration: If a developer only adds a config setting to their local file and not to the generic config.php, this will not be available in other environments.
The config.php file will contain variables (properties) which will be replaced on runtime by the configuration class. This technique is borrowed from JAVA programming. The value of the variable will be place in a separate file which is a CRLF-separated key/value pair list (*.properties files).
Config settings that contain variables will not be replaced by the configuration class upon saving. This will exclude those settings from being updated programmatically. Developers will need to create a default.properties file to ensure that the variables will be replaced on runtime if no environment specific information is available.
JAVA properties can be nested, but their value is immutable. The order in which the property files are included determines the runtime value of the variable. This allows for sophisticated, sometimes overly complex, configuration. The inclusion order should be set in the config.php file, and will contain something like 'default.properties;local.properties' where the 'local.properties' file will not be placed under version control and is thus truly independent.
- Meets requirements 1,2,4,5,6,7
- Single configuration file
- JAVA properties allow complex configuration. This is both a pro and a con
- Although this can be made backwards compatible, and does not require breaking changes to the configuration class, it will include major changes to this class. JAVA properties are not natively supported in PHP. This means an additional class will be created to deal with the parsing of property files.
- It is not common for PHP projects to use JAVA style properties. Even though they are easy to understand and to implement, there will be a learning curve for most developers.
- JAVA properties allow complex configuration. This is both a pro and a con
- If you forget to create a property for a variable in the config file, it will not be replaced on runtime, and it could potentially break your project.
- Config settings that contain variables will not be replaced by the configuration class upon saving