Floe applications follow the well worn pathways of PHP best-practices and the conventions of leading web frameworks.

In general, it is straightforward to customize the installation to suit your particular preferences in terms of naming conventions, as long as you bear in mind the constraints described here.

Choice of Environment

Floe applications can be adapted for installation on shared hosts or dedicated project servers. The most important aspect in choosing how to organize files is the sophistication of the deployment environment - some webhosts disallow including PHP files below the web root, while others enable the full possibilities of the Unix or Windows environment. Many webhosts are somewhere in between (see Supported Hosts).

Manual Build

The following folder layout represents the basic architecture of a shared host install:

/.htaccess
/index.php
/app
/dev
/lib
/tmp

If the server is capable, it is preferable to use this alternative folder layout:

/app
/dev
/lib
/tmp
/www
/www/.htaccess
/www/index.php

Applications with an enormous amount of templates or multiple themes could also store templates in a project level space:

/app
/dev
/lib
/tmp
/tpl
/web
/web/.htaccess
/web/index.php

The www or web folders should be pointed to as the DOCUMENT_ROOT of the Apache web server. This folder is often called htdocs or public.

Application Components

The main components of the MVC architecture sit in their usual places within the app folder:

/app/controllers
/app/domain
/app/templates

Development Infrastructure

Configuration files, development tasks, unit tests, build scripts, and database schema files are kept in the dev folder. This folder should not be uploaded to live production servers.

/dev/config
/dev/schema
/dev/tasks
/dev/tests

Sometimes it can be helpful to include a folder for experiments, hacks, and exploratory spikes:

/dev/spikes

Temporary Files

The tmp folder needs to be writeable by the web server. It is a scratch space, often containing the following subsets:

/tmp/logs
/tmp/cache

If your views are based on compiling Smarty templates, it's best to keep them here also:

/tmp/compiled

Library Components

Generally, Floe applications eschew the idea of 'helpers', but in cases where this is useful, they are generally placed in a library folder like:

/lib/helpers

Per-application, many other third party libraries can be checked in to lib. For example, if SimpleTest is not installed on your include_path, you should export it here:

/lib/simpletest

Use of include_path

On shared hosts without include path access, the Floe framework classes should be installed at lib/floe. When full access to the filesystem is available, it is recommended to manage Floe via the PEAR installer, or by manually copying the packages to the lib folder and modifying the include_path setting in php.ini to point to this location.

Floe does not yet provide package loading or __autoload hooks - this is left to developer discretion.

Configuration File

Most of the time, this is included under the web root as config.php, and required directly by the index.php which acts as a request gateway for the entire application. The config.php file should contain all settings that are environment specific - any common initialization code should be inlined in the index.php file itself.

It's a good idea to store environment specific configuration files in the dev/config folder, such as:

/dev/config/default.env.php
/dev/config/staging.env.php
/dev/config/production.env.php

This way, the actual config.php file linked to by index.php can be dynamically installed via a build script, from the appropriate source environment file in dev/config. Basic configuration expected by the Floe runtime is based on string values of the following constants:

Path Settings

• APP_DIR - location of application components
• DEV_DIR - location of development infrastructure
• MOD_DIR - location of domain models
• TMP_DIR - location of temporary scratch space
• TPL_DIR - location of view templates
• WEB_DIR - location of public document root

An example path configuration is given by the default.env.php template, which concatenates the current working directory to the default path settings. Adapting these settings enables you to override the default directory structure and specify your own custom folder layout, or provide different folder layouts for different environments:

define('APP_DIR', dirname(__FILE__).'/app/');
define('DEV_DIR', dirname(__FILE__).'/dev/');
define('LIB_DIR', dirname(__FILE__).'/lib/');
define('TMP_DIR', dirname(__FILE__).'/tmp/');
define('TPL_DIR', dirname(__FILE__).'/app/views/');
define('MOD_DIR', dirname(__FILE__).'/app/domain/');
define('WEB_DIR', dirname(__FILE__).'/web/');

Storage Connection Settings

If you are using the repository package, you will need to specify the database connection constants. Floe does not yet support multiple storage connections in a single request-response cycle.

• DB_HOST - Mysql host server
• DB_NAME - name of the database
• DB_USER - username to connect as
• DB_PASS - password to connect as

Server Environment Settings

• WEB_HOST - HTTP hostname (eg: http://localhost)
• MOMENT - unique per-request nonce

Note, these configuration constants may be deprecated in later versions of Floe, but currently in practice, the use of constants generally involves lower maintainence and lower cognitive load when switching between various environments.