Configuration

Overview

Basecoat configurations are typically based around associative arrays that assign names to configuration blocks. For example, names are assigned to individual routes and layouts. This allows code to reference items by name, what the name represents can be dynamic based on conditions and events (overloading). This also allows aliasing, where multiple names can be assigned to the same configuration. For example, multi-lingual URLs that all route to the same code.

Basecoat is an "include" framework. You do not need to build your website "inside" the framework, the framework is loaded by your code by instantiating the Basecoat class. This setup allows multiple websites to be built around a single, common install of the framework.

File/Folder Structure

/basecoat basecoat.php /classes content.class.php routing.class.php db.pdo.php /templates messages.tpl.php

/your_site

Initialization

Initializing Basecoat is done by creating and instance of the core Basecoat class. Most implementations will then configure the following:

Configure Layouts and set default layout
$basecoat->view->setLayouts( array );
$basecoat->view->setLayout('layout ID');
Set the Template directory path
$basecoat->view->setTemplatesPath('templates/path');
Configure the Routes
$basecoat->routing->setRoutes( array );

URL Structure

Typically web sites use mod_rewrite or something similar to create friendly/pretty URLs, instead of using URL parameters. Since some websites may be hosted in a shared hosting environment, or have complex development environments where rewrite rules aren't available, the framework can be used in either mode. Switching modes does not require extensive code changes, just a configuration toggle, so it's possible to develop using URL parameters and switch to using "pretty" urls in production.

$basecoat->routing->set('use_pretty_urls', true);
$basecoat->routing->set('route_param', 'page');

The default route parameter is page, but is configureable to be anything. Multiple routes can be specified by using . as the delimiter.

Example of parameter based URL with multiple routes specified:

http://hostname.com/?page=configuration.settings

Example of mod_rewrite based URL with multiple routes specified. Note: an ending / is optional and does not affect processing:

http://hostname.com/configuration/settings

Configuration Options

Basecoat configures some default settings, but also supports registering any name/value pair as a setting. This allows you to centralize your site settings in Basecoat. In general, Basecoat variables and setting are public to allow you to do as you please. Basecoat does not try to protect you from yourself.

$basecoat->setTemplatesPath();

The root directory where the View controller will look for template files. This value prefixes each template specified in the route configuration.

$basecoat->headers( array );

Array of name/value pairs to output as headers. Defaults listed below.
Content-type: text/html; charset=UTF-8
X-Powered-By: Basecoat PHP framework

$basecoat->view;

Primary instance of the View controller. In general, it will be this instance that all other instances of the View controller are merged into.

$basecoat->routing;

Primary instance of the Routing controller. If you want to replace the one that comes with Basecoat, load your own instance into this variable.

$basecoat->routing->set('name', 'value');

Name/value pair settings, add your own in addition to the defaults shown below.
use_pretty_urls: default true. Whether to use mod_rewrite or parameter based routing
route_param: default page. Routing parameter name if using parameter based routing
profiling: default false. Enable/Disable route profiling.

Route Configuration

Routes are configured by declaring an associative array of named routes. The array key is used to map the route name to the route configuration and route meta data. The route name is used to perform an indexed lookup for the proper route to run. This provides a very fast, scalable route processing architecture. Each route has an array of configuration information associated with it that is used to determine how to process the route. Each route can have a function, an include file, or both, associated with it to perform the route processing. Defined route configuration options are as follows:

function (function) a callable function (i.e. anonymous function) to execute for processing
file (string) valid include path and file to load to process the route
template (string) a valid file name in the templates directory. This parameter is used internally by Basecoat for special processing (i.e. servicing static files).
require_secure (integer) automatically redirect the user to the secure version of the URL requested
cacheable (array) provides a way of declaring that a route is cacheable and how to cache.
- expires (string) a valid strtotime string indicating how long to cache the content for. Currently only adds cache headers to the output.
layout (string) name of the layout to use for rendering. Must map to a layout in the defined layouts list.

// Example route configuration array
$routes = array(
	'/' => array(
		'file' => '/path/to/route_file.php',
		'template' => 'index_tpl.php',
	),
	'example' => array(
		'file' => '/path/to/example_route.php',
		'template' => 'route_tpl.php',
		'require_secure' => 1,
	),
	'static' => array(
		'file' => '/path/to/static_route.php',
		'cacheable' => array(
			'expires' => '1 hour'
		)
	),
	'not_found' => array(
		'file' => '/path/to/404_route.php',
		'template' => '404_tpl.php',
	),

);

Aliases

Since the route configuration is just an associative array, configuring multiple names for the same route is very simple. This is helpful when you have multiple URLs that load the same or very similar content. The same route configuration can be assigned aliases. The route itself could then check which name it was loaded under and adjust it's behavior accordingly.

$routes['alias_name'] =& $routes['example'];
$routes['seo_name'] =& $routes['example'];

Meta Data

Basecoat has some predefined route parameters that it checks for, but you can add any meta data as additional array items. This extra meta data can then be referenced by the routes. For example, a require_login meta data item can be configure and a processing hook (next section) can be configure to check for this parameter before allowing route execution. Another example is specifying a canonical URL to support looking up URLs for other routes to support redirects.

Processing Hooks

There are 4 processing hooks available for running custom code at various points of processing. Hooks are added by passing a callable function to the appropriate method. Multiple functions per hook is supported. All hooks for a specific processing point can be cleared by calling the appropriate clear method.

Before processing of each route

$basecoat->routing->addBeforeEach( function );

$basecoat->routing->clearBeforeEach();
After processing of each route

$basecoat->routing->addAfterEach( function );

$basecoat->routing->clearAfterEach();
Before rendering of content for output

$basecoat->addBeforeRender( function );

$basecoat->clearBeforeRender();
After rendering of content for output

$basecoat->addAfterRender( function );

$basecoat->clearAfterRender();

Provide feedback

Saved searches

Use saved searches to filter your results more quickly