Configuration is a central part of any project. It allows to externalize settings like database credentials or session settings or even how errors should be handled. Without using a central point for configuration, you would have to hard-code the values directly in your application. This is not a good thing, especially when the configuration settings need to vary from one host to another.
There is a lot of ways to store configuration settings, PHP code, database table, files with various formats. In Web:Extend the configuration depends on a file.
The format of the file is very simple. The settings are organized into pair/value combinations. Here is an example configuration file revealing the syntax and all the statements available.
db.host = localhost db.user = wee db.password = wee db.dbname = wee_tests $(os Darwin).on_darwin = 1 include ./another_config_file.cnf
Those files use Perl-like comments. Any line beginning with # is a comment.
# this is a comment
The include statements' syntax is fairly straightforward.
To include a file, simply put its name next to the include statement, as parameter.
If the file path begins with //, the path will be relative to APP_PATH;
if it begins with ./, the path will be relative to the current config file being parsed;
otherwise it will be relative to the current working directory.
In most cases, APP_PATH is the current working directory, but you shouldn't count on it.
include //relative_to_app_path include ./relative_to_current_file include relative_to_current_working_directory
Target instructions permits the developer to configure the application conditionally, allowing some configuration settings to vary from one host or operating system to another. For example, you may have two environments, one for development and one for production.
Your configuration file could look like this:
db.password = default_password $(host dev.example.org).db.password = a_pass_easy_to_remember_for_the_dev_environment $(host test.example.org).db.password = a_fairly_secure_password
The second line will only be read by the application if the hostname matches dev.example.org.
Otherwise it will be ignored. Same for the third line, it will only be read if the hostname matches test.example.org.
It is good pratice to put the production value by default and to override the production settings by your specific environment's settings.
The production value will only be overrided if there is a matching target.
The general syntax for target instructions is as follow.
$(function [param1] [param2] [...] target).key = value
Instead of a key-value setting, you can also write an include statement to conditionally include another configuration file.
$(function [param1] [param2] [...] target).include //path/to/file
Here is a list of all supported targets:
Table 5.1. List of configuration targets
| Function | Parameters | Description |
|---|---|---|
os | None. | Operating System name, e.g. NetBSD. The equivalent PHP call is php_uname('s'). |
host | None. | Hostname, like localhost or example.com. The equivalent PHP call is php_uname('n'). |
phpver | None. | The version of PHP which is executing the script. The function executed is php_version(). |
extver | Name of the PHP extension. | The version of the given PHP extension. The equivalent PHP function is php_version() with the name of the PHP extension as its argument. |
sapi | None. | The type of the interface running PHP. The equivalent PHP function is php_sapi_name(). |
In our previous example, all the settings beginning by db. are part of the db namespace.
You can retrieve values from the namespace either by retrieving a single value:
<?php echo weeApp()->cnf('db.host'); // echoes localhost
Or by retrieving the whole namespace as an array:
<?php $aDbParams = weeApp()->cnfArray('db'); echo $aDbParams['host']; // echoes localhost
Note that the namespace's name is removed from the key name in the returned array.
Here, the db.host value is stored in the host key of the returned array.
Web:Extend provides a sample configuration file located in share/conf/sample.cnf.
This file contains default values that you can use when starting a project.
The application framework automatically loads a configuration file.
The configuration file is the one specified by WEE_CONF_FILE which defaults to ROOT_PATH/app/conf/wee.cnf.
You may want to change the location of this file.
You can do it by manually defining the constant prior to calling weeApplication::instance() in your bootstrap file:
<?php
define('WEE_CONF_FILE', '/a/more/fitting/location/for/wee.cnf');
The application module will initialize a few things after reading the configuration. It will look for the following parameters:
Table 5.2. Parameters for application configuration
| Name | Default value | Description |
|---|---|---|
app.timezone | None. | The default timezone of the application. |
app.toppage | toppage | The default frame of the application. |
app.autoload.path | None. | A string of colon-separated paths to autoload. Paths starting with // are relative to APP_PATH. |
See the routing section for information about the routing configuration parameters. See below for the driver-specific configuration parameters.
A driver is an object defined in the configuration file for use in your application. It can be any class, as long as it accepts one parameter for its constructor. This parameter will be an array containing the configuration for the driver.
To add a driver, simply add this to your configuration file:
mydriver.driver = myDriverClass
You can then access this driver in the following way. The driver will be automatically loaded the first time you try to access it.
<?php weeApp()->mydriver->myMethod();
To specify parameters for the constructor, simply add a few more lines in the configuration file.
Everything under the mydriver. namespace will be sent to the constructor of the driver.
mydriver.driver = myDriverClass mydriver.param = example parameter mydriver.another = and another one!
The driver's object isn't created when the application starts,
to prevent wasting resources on objects that won't be needed.
However you might sometimes need one to be started for each request.
To start it automatically, you can use the start. configuration namespace.
For example, you could force start the driver mydriver defined earlier by adding this line to the configuration file:
start.mydriver = 1