Application Configuration

Caution

This page is tagged as a draft and is a work in progress. It is not yet complete and may contain errors or inaccuracies.

The application configuration is the central location for storing all the variable bits and pieces used to drive your application. There are some built-in configuration options that control certain global aspects, such as PHP runtime configuration, but the main purpose of the application configuration is to give your application a place to store it's own settings.

Info

Application configuration files can be in either JSON or INI format, it's entirely up to you. However, JSON is the preferred format as it is more flexible so going forward, this document will only refer to the JSON format. INI files were the original file format used so they are still supported for legacy purposes only and are no longer officially supported.

Configuration is loaded in several steps that allow the config to be overridden based on certain criteria. The main configuration is kept in a file called application.json which loaded from directories searched in the following order:

• The default configuration is loaded. This configuration is hard-coded into the Hazaar\Application class so that the minimum settings are specified in order to run the application.
• The main configuration is loaded from the application\configs directory. This file is broken into sections based on the APPLICATION_ENV environment variable that is defined in your web server config or defaults to development.
• Any server specific configuration is loaded from the application\configs\host directory. This allows server specific configuration to be loaded based on the web server's configured server name.
• Any local configuration is loaded from the application\local directory which allows configuration settings to be overridden for the physical host, useful in multi-host setups or during development to override base settings.

Default Configuration

The default application configuration looks a bit like this:

{
    "app": {
        "root": {{ "/" for CLI and $_SERVER['SCRIPT_NAME'] for HTTP }}
        "defaultController": "Index",
        "useDefaultController": false,
        "favicon": "favicon.png",
        "timezone": "UTC",
        "rewrite": {{ false for CLI and true for HTTP }},
        "files": {
            "bootstrap": "bootstrap.php",
            "shutdown": "shutdown.php",
            "route": "route.php",
            "media": "media.php"
        },
        "responseImageCache": false
    },
    "paths": {
        "model": "models",
        "view": "views",
        "controller": "controllers",
        "service": "services"
    },
    "view": {
        "prepare": false
    }
}

This configuration is hard-coded into the Hazaar\Application class and is the absolute minimum required to get an application running. This configuration will almost always be overridden by a configuration that you have defined in your application config directory.

Main Configuration

The main configuration file supports application environments. The current application environment it defined in the APPLICATION_ENV global constant and is normally set by the web server. The default is always development, but typical values may include:

• staging - For staging servers used to test code prior to deployment.
• production - For production servers.

A good example of using application environment specific configuration is on development and staging servers, you may way to enable PHP error logging with "php": { "display_errors": 1}, but obviously on production this would be set to "php": { "display_errors": 0} so that PHP error messages are hidden.

An example of this setup would look like this:

{
    "production": {
        "app": {
            "name": "Production Settings"
        },
        "php": {
            "display_startup_errors": 0,
            "display_errors": 0
        }
    },
    "staging": {
        "app": {
            "name": "Staging Settings"
        },
        "php": {
            "display_startup_errors": 1,
            "display_errors": 1
        }
    },
    "development": {
        "include": "staging",
        "app": {
            "name": "Development Settings"
        }
    }
}

Info

Rather than defining the php section multiple times with the same settings, above we used the include option to include previously defined configuration settings. We can then override any settings needed in that environment. This is a good methodology to employ. By having production as your master configuration and including it in other configuration environments you can override only what is neccessary.

Server Specific Configuration

Server specific configurtaion files can be stored in a sub-directory of the main config directory named application/configs/host in another sub-directory with the name of the host. This allows an application to have multiple configurations based on the server name. The server name is taken from the $_SERVER['SERVER_NAME'] variable which is configured by your web server. So if the server name is www.yourdomain.com and we are loading the main application config file, it would be stored at application/configs/host/www.yourdomain.com.

An example use of this might be if you have multiple entry points to your application. If someone accesses www.yourdomain.com you can configure the Index controller as your default. However if they access cloud.yourdomain.com they can be automatically routed to the Cloud controller by default.

Info

These configuration files do not use environment specific configurations. The exception is the DBI module which is discussed in it's documentation at "scroly.io/hazaar-dbi":http://scroly.io/hazaar-dbi.

Local Configuration

Local configuration opperates similar to server specific configuration and is stored in the application/configs/local directory. These config files allow settings to be defined for the physical host on which they reside.

This is useful in various situations such as using different cache settings during development, such as the file backend, but then using the redis backend on all other hosts.

Built-in Configuration Directives

There are a number of configuration directive available that control the way certain built-in application functionality operates.

Application Directives

These directives are used throughout the application and affect it's functionality only.

app.name

The short name of the application.

{
    "app": { "name": "Test Application" }
}

app.version

The current version of the application. This is returned when calling Hazaar\Application::getVersion().

{
    "app": { "version": "1.0.1" }
}

app.view

The default view to use for the Hazaar\Controller\Action controller. This controller uses this global view which can set the overall style and layout of the application. A call to $this->getContent() from inside this view will then populate the page with the output from the controller.

{
    "app": { "view": "application" }
}

app.defaultController

This is the controller that is loaded if one is not specified in the URL. Usually 'Index'.

{
    "app": { "defaultController": "Index" }
}

app.errorController

This is the controller that is used if an error occurs. Usually 'error'. See Error for more information.

{
    "app": { "errorController": "Error" }
}

app.compress

If this is true, the application will compress any output that it produces. This includes stylesheets and javascript files.

{
    "app": { "compress": false }
}

app.timer

Enables the built-in application execution timer which is available from inside a controller at

$this->application->timer

This timer is used by the application to track performace during various stages of execution. Below is a list of available timers automatically created by the application during execution. Any timers that are prefixed with an underscore (_) are pre-stage timers, meaning they hold the execution time between the global start time and the start of the timer stage.

• global - The global timer is available in all Hazaar\Timer objects and is the time between when the Hazaar MVC application.php file is loaded (known as the global start time) and now.
• init - The time taken to initialise the Hazaar\Application object. This includes everything that occurs in the Hazaar\Application constructor, such as initialising the class loader, loading the configuration and setting up the application environment.
• _bootstrap - The time taken to get to the bootstrap stage from global start.
• bootstrap - The time taken to bootstrap the application. Bootstrapping the application involves all the steps required to prepare the target controller for execution. This includes setting up the operating locale, determining the requested controller using the request path and any routing aliases/scripts, as well as initialising the target controller so it is ready for execution.
• _exec - The time taken to get to the exec stage from global start.
• exec - The time taken to actually execute the application. At this point the target controller will be loaded and prepared so this is just the stage where the controller performs it's tasks. This can include load/rendering/outputting views, generating and outputting JSON data, etc.
• shutdown - This timer is open ended and is started at the end of the exec stage. Theoretically the Hazaar\Application::shutdown() method should be almost the last thing to execute so using the timer at that point can give an indication of any shutdown issues.

app.timer = true

app.maxload

If this directive exists it will activate load average protection. When the application executes it will check the 1 minute load average and if it is greater than this number the application will return a 503 Too Busy HTTP response.

app.maxload = 3.00

app.*

It's also possible to have custom options, apart from those above. These values can be retrieved from anywhere in the application by referencing the \Hazaar\Application\Config object which is accessible at $this->application->config from inside a controller. Alternatively, if you need to access to the config object outside of a controller you can get an instance of the application with Hazaar\Application::getInstance() and then refer to the config object there.

app.theme = "classic"

This would then be accessible from a controller or view by calling:

$theme = $this->application->config->app['theme'];

Paths Directives

Paths are for setting where various components exist in the application directory. Normally these will never change but have been added for complete flexibility.

paths.model

The path, relative to the root/application path where models are kept. Usually 'models'.

paths.model = "models"

paths.view

The path, relative to the root/application path where models are kept. Usually 'views'.

paths.view = "views"

paths.controller

The path, relative to the root/application path where models are kept. Usually 'controllers'.

paths.controller = "controllers"

PHP Settings Directives

php.*

These config options can be used to configure INI settings in PHP itself.

php.display_startup_errors = 0
php.display_errors = 0

Session Directives

These directives affect the functionality of the PHP session object. These aren't absolutely needed and have adequate default values for most situations.

session.name

The session name to use for PHP. This is what is set in the cookie on the client side. Defaults to the PHP session name of PHPSESSID.

session.name = "MYSESSION"

session.namespace

The default session namespace. This namespace is used if one is not specified in the session object. Defaults to 'default'.

session.namespace = "default"

session.timeout

Specifies the number of seconds of idle time that should pass before a session will expire. Defaults to 180.

session.timeout = 180

View Directives

view.helper.load

This directive can be used to load one or more view helpers automatically, meaning that the View::addHelper() method call does not need to be called from your within you controllers. This is handy for view helpers that need to be active all the time, such as with the Bootstrap or Google analytics view helpers.

view.helper.load[] = Bootstrap
view.helper.load[] = Google

view.cache

Enables internal caching of external view includes. This means that if an external JavaScript or CSS file is included using the Hazaar\Controller::requires() or Hazaar\Controller::link() methods, then the file will be cached in the application runtime directory. This can be used during development to reduce requests to external servers and allows for working "offline".

{
    "view": { "cache": true }
}

Includes

You can include another configuration if needed.

{
    "include": "production"
}

This is useful for if you have a development server or other stripped down server. You can set all your options up in the [production] configuration, include that config, and then only add the settings that you want to override. For example, you may have debugging off by default, so you could include the production config and then just set debug = true.

Variables

Configuration files can also even reference globally available constants using embedded tags in configuration values encapsulated by the % sign.

For example, to refernce the APPLICATION_ENV constant, your config can contain the value %APPLICATION_ENV%.

{
    "development":{
        "app": {
            "title": "Application Environment - %APPLICATION_ENV%"
        }
    }
}

Any globally available constant defined can be referenced using this method.

Some of global constants supplied by Hazaar MVC include:

• APPLICATION_ENV - The current application environment.
• APPLICATION_PATH - The path on disk in which the application directory exists.
• APPLICATION_BASE - The server relative URL path on the web host.
• APPLICATION_NAME - The name of the application. This is simply the base directory name that the application files are in.
• HAZAAR_EXEC_START - Timestamp when the current request started.
• HAZAAR_VERSION - The current version of Hazaar MVC.

Info

These tags are resolved at runtime, so the constant does not have to exist before the configuration file is loaded. It only needs to exist at the time the value is referenced.

If the constant is an array, such as with those supplied by PHP like $_SERVER, $_COOKIE, etc, then the elements inside these arrays can be referenced to using bracket notation the same as PHP, but omitting the single quotes ('). For example. to reference $_SERVER['REMOTE_ADDR'], then your config value would be %_SERVER[REMOTE_ADDR]%.

Other global constants that are available are:

• $GLOBALS
• $_SERVER
• $_GET
• $_POST
• $_FILES
• $_COOKIE
• $_SESSION
• $_REQUEST
• $_ENV

Setting your locale

For some functions of Hazaar to work correctly you will need to ensure that your locale is set up correctly. By default the locale for Apache 2 is probably ‘C’, which is ok for a generic approach to things, doesn’t tell us much when it comes time to dealing with things like money.

There are a number of methods for setting the locale depending on what you are trying to do and how you want to affect the running of your server.

Setting the Locale for your application (recommended)

To set the locale for your application ONLY, you can simply add the following line to your application.ini file if it is not already there.

app.locale = 'en_AU'

Info

Locales have changed a bit in PHP over the last few releases. Remember that these locales now need to haveUTF-8 or ISO-8859-1 appended to them. Previously you could simply refer to en_AU. This may still work, but if it doesn’t try en_AU.ISO-8859-1 or en_AU.UTF-8 for unicode.

Warning

This locale MUST be enabled on your server. If it is not, then the call will fail and you will receive an error.

Setting the Locale in Apache

As stated, the default locale for Apache 2 is usually ‘C’. This is because it is generic and covers most country applications (I assume). It is then expected that you set your locale in your application (see above).

However, you can set the locale for your entire Apache instance if you choose. To set the locale for your entire Apache instance just look in the file /etc/apache2/envvars and either set the LANG variable to your locale (such as en_AU, or en_US), or set it to use your default system locale by uncommenting the line that loads the locale from /etc/default/locale.

Info

This will set the locale for your entire Apache server and affect everything running on it. However if the application sets a locate separately (as above) then that will override the default locale. Setting the Apache locale will just make sure a locale is set by default.

Caution

I can’t stress this enough so I’ll repeat. These locales MUST be enabled on your server. If they are not, then the call will fail and you will get an error.

Setting System Locale on Debian

Just as an aid to get some people going, here’s how to set a locale on a debian-based system (including ubuntu, etc).

Just run sudo dpkg-reconfigure locales and select the locales you want enabled on your system. This process will also rebuild the locale database for you. If that fails because you don’t have the locales package installed (really, you should have it) then install it by:

# sudo apt-get update
# sudo apt-get install locales