Core Package

Core is the base package for almost all other WACT packages. The core package consists of the single file, wact.inc.php. The core package has two responsibilities:

• Contain the support infrastructure for WACT packages to locate classes and files to include.
• Contain the support infrastructure for WACT packages to report and handle errors.

wact.inc.php must typically be included before any other WACT packages. There are two methods for including wact.inc.php.

You may place the WACT framework at a known location and include it with an absolute path:

require_once '/path/to/wact.inc.php';

After loading wact.inc.php, the constant WACT_ROOT will be available. You may include other framework classes relative to this constant. For example:

require_once WACT_ROOT . '/template/template.inc.php';

You may place wact in your include_path and call it with a relative path:

require_once 'wact/wact.inc.php';

You may then load other WACT packages using include_path:

require_once 'wact/template/template.inc.php

Note that WACT_ROOT is still available even when you use the include_path to load WACT packages, but mixing styles is not recommended.

The wact core package includes WactClassFinder for keeping track of which file a class is located in and for loading class files. WactClassFinder can make classes easier to use because you need not know the specific location of the class. WactClassFinder also facilitates lazy loading of class definitions.

The static setLocation method of WactClassFinder records the file location of a given class for later use. The first parameter is the class name and the second parameter is the path name of the file location.

WactClassFinder::setLocation('Template', WACT_ROOT . '/template/template.inc.php'); // absolute style
WactClassFinder::setLocation('Template', 'wact/template/template.inc.php'); // include_path style

Only the location is recorded. The actual class file is not loaded until needed.

Rather than pre-populate the WactClassFinder with class locations, you can use addLocator to register a class loader that the WactClassFinder can use to find the class files when they are requested.

This works like the __autoload function in php5, except that class locators are objects, there can be more than one, and they work under php 4.

Use the static requireClass method of WactClassFinder to ensure that a class definition is available just before use. For example:

WactClassFinder::requireClass('Template');

The file location of the class must already be recorded with the WactClassFinder using setLocation or the WactClassFinder must have a class locator registered which can find the appropriate file on demand.

including php files is one of the more time consuming tasks that a typical PHP application performs. The WactClassFinder is designed to facilitate lazy loading of class files so that only code that gets used is included into the running program.

To implement lazy loaded classes in WACT, use WactClassFinder::setLocation at the top of your file to declare the location of classes that you might use. Or, use WactClassFinder::addLocator to register a locator object that can find the appropriate file.

Then, later, just before use, call WactClassFinder::requireClass just before using the class to trigger the actual loading of the class.

require_once is a handy function, but the second call to require_once is surprisingly expensive. Thats because the file system must be consulted in order to determine if the file has already been loaded. WactClassFinder::requireClass uses the name of the class to determine if a class has been loaded instead of a file system check and thus can be faster than require_once.

WactClassFinder::requireClass can accept a file location as an optional second parameter. This eliminates the two step process of recording the location of the class in the class registry, but still allowing the faster WactClassFinder::requireClass to be used in its place.

WactClassFinder::requireClass('Template', 'wact/template/template.inc.php');

This is equivalent to

if (!class_exists('Template')) {
   require_once 'wact/template/template.inc.php';
}

If you think that its likely that you will only try to include a particular file once, then go ahead and use require_once to include that file to avoid the extra class_exists check.

Since WactClassFinder::requireClass includes files inside of a function any variables you declare with global scope in the loaded file will no longer have global scope. This can be avoided by always using the $GLOBALS super global to access global variables:

$GLOBALS['myGlobal'] = 'blah';

The WACT class registry can be used in conjunction with the PHP 5 __autoload function. Call WactClassFinder:autoload from from your __autoload function. For example:

function __autoload($class) {
    WactClassFinder::autoload($class);
}

WACT does not automatically take over your __autoload function. that would be presumptuous and rude.

All WACT packages call the function WactRaiseError when they encounter an error. WactRaiseError accepts three parameters, a error group, an error message id, and an array of additional information about the error.

WactRaiseError('TEMPLATE', 'NOT_FOUND', array('filename' => $filename));

Control flow is not generally expected to return after a call to RaiseError.

You may wish to call RaiseError to report errors in your own application, but it is not required.

By default, WactRaiseError calls trigger_error with a rather Spartan error message. You can register an error factory to achieve a more advanced error triggering capability. Some possibilities include:

• Longer, more descriptive error messages
• Internationalizable error messages
• Raise an exception instead of calling trigger_error
• integrate with other error solutions such as PEAR_Error

Since encountering an error should (hopefully) be a rare activity in your application, WACT uses the lazy loading mechanism of the Class Registry to only load the appropriate error factory when an error occurs.

Registering an error factory is a two step process. First, specify the location of the Error Factory class that you wish to use. Second, register it with the framework.

WactRegisterClassLocation('MyErrorFactory', '/path/to/myfactory.inc.php');
WactSetErrorFactory('MyErrorFactory');

Optionally, you may also pass additional configuration information to the error factory:

WactSetErrorFactory('MyErrorFactory', array('setting' => 'value'));

Since errors in your application are hopefully rare, WACT provides a lightweight way to lazy load an error handler into your application.

WACT does not set an error handler for you by default. That would be presumptuous and rude.

Setting an error handler is a two step process:

WactRegisterClassLocation('MyErrorHandler', '/path/to/myhandler.inc.php');
WactSetErrorHandler('MyErrorHandler');

As with error factories, you may also configure the error handler:

WactSetErrorHandler('MyErrorHandler', array('setting' => 'value'));

You will typically want to call WactSetErrorFactory and WactSetErrorHandler just after including wact.inc.php.