Configuration

Scope of this document

This document is intended to cover the following information:

how to apply SCM to Phoebius-based application
how Phoebius bootstraps and handles incoming requests
how Phoebius-based application can be configured

It will tell you everything about configuration, which is very important when dealing with SCM of the huge projects. This covers (but not limited by) application environment and tuning.

Installation

The first thing you should know when starting a new Phoebius project is that the application is tied with a specific framework distribution, but certainly they are independent and thus may be located separately.

Imagine that you've downloaded the latest Phoebius tarball and extracted it to $base (say, /var/www/phoebius-v1.2.0). Then you get the application sandbox and extract it to $app (say, /var/www/sites/phoebius.org). There is only the one thing you should consider when tying the application with the framework: the absolute path to the framework, which is /var/www/phoebius-v1.2.0s. This gives you the following pros:

you can host multiple applications using a single framework distribution. This simplifies deployment and updates;
an application depends on a specific framework version. This protects you from compatibility issues when the application becomes incompatible with the newer version of the framework

So, to tie and application with the framework, all you need is to include the framework init-script at the beginning of the front controller:

// $base contains the absolute path to the framework, e.g.:
// $base = realpath(dirname(__FILE__) . '/../../phoebius-v1.2.0');
require $base . '/etc/app.init.php';

and that is all! Now you can use the core Phoebius library.

Front-controller lifetime

In typical application a HTTP-request is passed to front-controller (which is usually $app/www/index.php), and it does the following:

sets up an absolute path to a directory where the application resides, and assigns it to the APP_ROOT constant:
```
define('APP_ROOT', realpath(dirname(__FILE__) . '/..'));				
```
invokes the framework's init-script:
```
require (APP_ROOT . '/phoebius/etc/app.init.php'));
```
This stage helps to automate the process of bootstrapping the framework environment:
- an absolute path to $base/lib is set up
- transparent class autoloader invoked
- various configuration constants set up to be used in the application config
applies the application config:
```
require (APP_ROOT . '/etc/config.php');
```
This config is environment-independed: it sets up only application-wide settings, like additional paths where class autoloader looks up the invoked classes;
(optionally) applies a host config, which is environment-dependant. This config may define a database connections, caching and debugging policies, and so on and so forth;
passes the request to the handler, usually to SiteApplication which wraps the environment state with coherent object API. Learn more

Configuration

Activating front-controller

When your front controller is written down and is located in a HTTP public folder, it is time to direct the web server to it.

If you are using Apache, you can do this by a simple rewrite rule within .htaccess:

$app/www/.htaccess

RewriteEngine On

RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule .* index.php [L,QSA]

Application config

An application config (an $app/etc/config.php script) is the application init script intended to set up environment-independent application settings. These are settings that extend the application possibilities, can be relative and can be used on any server. In other words, these settings are the same even for completely different development and production environments.

The following settings can be treated as environment-independent:

relative path to the directories where classes are looked up. Application stub expands the include_path specifying two more directories for user classes: $app/lib and $app/var/lib (autogenerated classes).
maintainer's email where the crash dumps would be sent (a BUGS_EMAIL constant)
bootstrap of various dependant libraries, if any

This config can be easily tracked by the SCM you use.

Host config

A host config is a PHP script, which defines host-dependant settings. It shall be different for development and production environments. In most cases you put here the following:

slot configuration setting which affects framework performance. There are three predefined presets:
1. SLOT_PRESET_DEVELOPMENT defines non-optimized configuration and maximizes the verbosity of crash dumps and logs;
2. SLOT_PRESET_TEST is currently not used;
3. SLOT_PRESET_PRODUCTION defines maximum optimization
To use the desired slot preset, just assign it to APP_SLOT_CONFIGURATION constant:
```
define ('APP_SLOT_CONFIGURATION', SLOT_PRESET_DEVELOPMENT);
```

define the database connections:

DBPool::add(
	"default", 
	MySqlDB::create()
		->setName("mydb1')
		->setUser('mysql')
		->setPassword('')
);

DBPool::add(
	"additional", 
	PgSqlDb::create()
		->setName("mydb2')
		->setUser('postgres')
		->setPassword('postgres')
		->setHost('') // use UDP instead of TCP/IP @ linux
);

tune autoloader to use or to skip cache:

// important during development
Autoloader::getInstance()->clearCache();

There are various ways to force the application to use the corresponding host config. We appreciate using environment variable APP_SLOT to set the name of the host config and the following naming to separate host configs: $app/cfg/<host config name>/config.php. Then we just invoke the corresponding host config using the environment variable:

require APP_ROOT . '/cfg/' . APP_SLOT . '/config.php';

If APP_SLOT environment variable is not passed to the script then the framework init-script defines an APP_SLOT with the default value.

Tips and tricks

Autoloading 3rdparty libraries

Many times you need to use the 3rdparty libraries, that certainly do not follow the notations introduced by Phoebius, particularly an autoloading notation. Of course, you can force autoloader to find the requested classes from 3rdparty libraries easily by providing a class resolver that understands the notation your 3rdpary library follows.

Say, you want to use a library that follows PEAR naming style. Phoebius already provides a class resolver for that purposes. To use it, do the following:

locate you library to $app/3rdparty/pear

expand the include_path:

set_include_path(
	get_include_path()
	. PATH_SEPARATOR . APP_ROOT . '/3rdparty/pear'
);

add the corresponding class resolver to autoloader within the application config:
$app/etc/config.php
```
Autoloader::getInstance()
	->addResolver(new PearStyleClassResolver)
```

Conclusion

You have understood how the application can be preconfigured and expanded to fit the SCM requirements. Now it is time to prepare the OO-environment of the application and run it all -- see the application init document.

Configuration

Contents

Scope of this document

Installation

Front-controller lifetime

Configuration

Activating front-controller

$app/www/.htaccess

Application config

Host config

Tips and tricks

Autoloading 3rdparty libraries

$app/etc/config.php

Conclusion