Configuration

The configuration repository is separately maintained at https://github.com/PhpGt/Config

Configuration files are used to store data that can change between environments, such as database connection details, API keys, timezone information, and so on. It is common practice to have different configuration values based on the environment where the application is running.

All configuration files for WebEngine applications are stored in the project's root directory as .ini files, and a default config is supplied by WebEngine to set all config values to meaningful defaults.

Configuration override order

Multiple config files can exist which introduce new config values or override existing values. All values can also be overridden by setting environment variables on the server.

The following order is used to override configuration values:

• The WebEngine default config: /vendor/phpgt/webengine/config.default.ini
• The project's default config: config.ini
• Development config: config.dev.ini
• Deployment config: config.deploy.ini
• Production config: config.prod.ini
• Environment variables

Configuration file contents

The ini file format that WebEngine uses is the default format understood by PHP's parse_ini_file function. All ini files should be split into sections using square bracket notation.

An example config.ini:

[app]
namespace=SuperCoolApp

[database]
host=db.example.com
username=dbuser
password=dbpass

[example-api]
key=aabbccddeeff
secret="a long passphrase"

Then, for example, on the production server we can change the database.host and example-api.key values.

An example overriding config.prod.ini:

[database]
host=live-db.example.com

[example-api]
key=gghhiijjkkll

Only the keys that need to be overridden on the production environment need to be present in the config.prod.ini file. All other keys will be inherited.

Accessing configuration variables

Throughout WebEngine, global variables are not permitted. Config values can usually be seen as global state, meaning that they can be read from anywhere in your code (or your code's dependencies). Rather than passing around important API keys and database passwords to every class in the application, a single instance of the Config class is passed to your Page Logic entrypoint, allowing you to decide which classes of the application get passed the configuration, and which sections of the configuration they have access to.

From within a Logic class, $this->config is set to an instance of the Config object. The config object has two mechanisms for retrieving config data: get and getSection. Both functions retrieve the pre-parsed and overridden values.

Config::get

The get method allows the use of dot-notation to grab the value of some config by name. For example, to obtain the password value from the [database] section of the above example file:

$this->config->get("database.password");

Config::getSection

Sometimes areas of your application may need to load many configuration variables, which would make it difficult to pass around each variable individually.

The getSection function promotes proper encapsulation throughout your application, as it allows you to pass whole config sections individually to the areas of code that need to consume them.

Using this method allows an area of the code to be handed the passwords and secrets that it needs to know about, without being handed all other database and api passwords, for example.

The getSection function returns a ConfigSection object, which implements the Iterator interface and exposes the get method.

Iterating over the returned ConfigSection object allows you to act on each key and value in the section:

foreach($config->getSection("database") as $key => $value) {
	// ...
}

To simply get a single value from within the section, pass its key to the get method:

$databasePassword = $dbConfigSection->get("password");

Environment variables

As an alternative to overriding config keys in separate ini files, keys can be set as environment variables on the system. This can be done in the server configuration file or exported during system boot process.

Important note: environment variables cannot contain periods, so database.password must be replaced by database_password. As all environment variables must be stored within ini sections, the text before the first underscore is always treated as the section name.

If you choose to use environment variables, the best place to set them is in the server's configuration file.

Example of setting database.password variable on nginx - nginx.conf:

location ~ \.php$ {
	fastcgi_pass	unix:/var/run/php/php7.2-fpm.sock;
	fastcgi_param	database_password	super-secret-passw0rd;
	include		fastcgi_params;
}

Generating ini files

As part of your deployment process, you may want to set configuration variables depending on the build pipeline. A common use case is to set an environment variable according to the current branch being deployed.

To achieve this kind of dynamic configuration, it is possible to generate ini files by calling the config-generate script which takes two or more arguments:

1. The suffix; either "dev", "deploy" or "prod"
2. Each individual config key-value pair, wrapped in quotes

For example, to create a config.prod.ini file that overrides the database host and example-api key, run the following command:

vendor/bin/config-generate prod "database.host=live-db.example.com" "example-api.key=gghhiijjkkll"

Ini types

When PHP.Gt/Config parses the ini file, it uses the INI_SCANNER_TYPED scanner mode, allowing for boolean, integer and null values to be preserved.

String values "true", "on" and "yes" are converted to TRUE. "false", "off", "no" and "none" are considered FALSE. "null" is converted to NULL in typed mode. Also, all numeric strings are converted to integer type if it is possible.