Filter :: Adventure PHP Framework (APF)

Filter

1. Introduction

"Filter" play an important role within the apdventure php framework. In the releases prior to the 1.9 branch, filters were already there to secure input and input data, but hidden. Since the 1.9 release, they can be configured via the registry. Moreover, filters to safeguard form input is included now.

2. Input filter

The input filter group cares about the analysis of the user input, that is embedded in the URL or the HTTP protocol (aka POST data). For this reason, the framework includes a set of filter, that handle the input in case of url rewriting and normal url usage.

The core of the framework has no knowledge about the url layout, because the components rely on the $_REQUEST array. This abstraction makes it possible to operate in different url layout environments using input filter.

The filters can be grouped as follows:

2.1. Page controller with standard urls

The easiest typ of filter is used in conjunction with the page controller and normal urls. The StandardRequestFilter from the core::filter::input namespace replaces the input values with their HTML entities (see htmlspecialchars()) and executes a stripcslashes(), if magic_quotes_gpc is set to 1 to ensure, that form input is displayed correctly.

2.2. Page controller with rewrite urls

In case of rewritten urls, the PagecontrollerRewriteRequestFilter from the core::filter::input namespace handles the user input. This filter decomposes the rewrite url and regenerates the $_REQUEST out of this pieces. The filter assumes, that the rewritten url uses "/" as an seperator between the key-value-pairs. After that, the request array is filterd as with the StandardRequestFilter to safeguard the input.

2.3. Front controller with standard urls

The front controller input filter for default urls analyzes the request, extracts action instructions and applies the actions to the front controller. Normal url params are treated identically to the page controller filters above. This job is done by the FrontcontrollerRequestFilter from the core::filter::input namespace.

2.4. Front controller rewrite urls

Similar to the PagecontrollerRewriteRequestFilter the FrontcontrollerRewriteRequestFilter from the core::filter::input namespace filters the url whet using the front controller. Thereby, the rewritten action instructions and normal url params are extracted and applied to the $_REQUEST array or to the front controller.

3. Output filter

The output filter care about the HTML formatting. Due to the fact, that in this case no differentiation between front and page controller must be done, the APF includes only one output filter. In case of url rewriting active, the filter rewrites the links and form actions included in the HTML output code. This task is done by the HtmlLinkRewriteFilter class, that resides in the core::filter::output namespace. In order to explicitly exclude links, the link attribute linkrewrite can be set to false. As of release 1.10, mailto: links are excluded by default.

The OutputFilter deliverd with the APF (Class: GenericOutputFilter) uses the XmlParser to analyze the HTML links. For this reason, it is necessary that the attributes of a HTML anchor are delimited using >>"<< and the tag definitions must not include TAB characters. Otherwise you will be faced with endless loop effects described under 99% CPU-Last bei aktiviertem UrlRewriting (German language forum).

4. Design and function

An APF filter is represented by a class, that is derived from the AbstractFilter class. It must also implement the filter() method, that takes one argument: the input. The function must return the output at the end.

A sample implementation is shown in the subsequent code box:

PHP-Code

class MySpecialFilter extends AbstractFilter {

   public function filter($input){
      return $this->__replaceAWithB($input);
   }

   private function __replaceAWithB($string){
      return str_replace('a','b',$input);
   }

}

In order to use the filter, it must be created using the FilterFactory. The static getFilter() method expects one argument, that represents the filter definition. This parameter must be an instance of the FilterDefinition including the namespace and the filter's (class- and file-)name.

The following example explains the usage of a filter:

PHP-Code

// define the filter
$filterDef = new FilterDefinition('my::filter::namespace','MySpecialFilter');

// create the filter
$filter = FilterFactory::getFilter($filterDef);

// gather the input
$input = /* ... */

// apply the filter
$output = $filter->filter($input);

The internal structure of a filter is completely delegated to the developer's responsibility.

Details on the included default filters can be taken from the API documentation included in every release presented on the downloads page.

5. Configuration

The configuration of the input and output filters can be done using the registry. For this reaons, the registry namespace apf::core::filter contains the following directives:

PageControllerInputFilter: is executed on page creation while using the page controller.
FrontControllerInputFilter: is executed on front controller start. Includes the functionality of the PageControllerInputFilter concerning the url rewriting feature.
OutputFilter: is applied to the generated HTML code after the page is transformed.

If the developer considers to use his own url layout, this can be achieved using an own filter, that is defined as the page controller or front controller input filter. Due to the fact, that the configuration is done using the registry, the bootstrap file can be used to apply changes to the filter definition. The code box below shows, how the page controller input filter can be adapted:

PHP-Code

// include page controller
include('./apps/core/pagecontroller/pagecontroller.php');

// configure registry
Registry::register(
   'apf::core::filter',
   'PageControllerInputFilter',
   new FilterDefinition('my::filter::namespace','MyPageControllerInputFilter')
);

// create page and display page
$page = new Page();
$page->loadDesign('namespace::of::my::webpage','mytemplate');
echo $page->transform();

In case of the front controller, the adjustment works as follows:

PHP-Code

// include page controller
include('./apps/core/pagecontroller/pagecontroller.php');

// include front controller
import('core::frontcontroller','Frontcontroller');

// configure registry
Registry::register(
   'apf::core::filter',
   'FrontControllerInputFilter',
   new FilterDefinition('my::filter::namespace','MyFrontControllerInputFilter')
);

// create front controller and start it
$fC = &Singleton::getInstance('Frontcontroller');
$fC->start('namespace::of::my::webpage','mytemplate');

Please note: the configuration of the filter must be done before the page or front controller is created!

The manipulation of the output filter is identically to the examples above. In this case, the registry directove OutputFilter must be provided with a new FilterDefinition.

If you want to disable the built-in filters, the configuration directives must be set to null:

PHP-Code

// include page controller
include('./apps/core/pagecontroller/pagecontroller.php');

// include front controller
import('core::frontcontroller','Frontcontroller');

// disable all filters (or just parts of it)
Registry::register('apf::core::filter','PageControllerInputFilter',null);
Registry::register('apf::core::filter','FrontControllerInputFilter',null);
Registry::register('apf::core::filter','OutputFilter',null);

...

6. Form filters

Based on the filter definition descibed in chapter 4, the 1.9 branch includes filters on form elements. The usage and adaption of these filters is described in the documentation section usage of form filters.

Comments

Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.

There are no comments belonging to this article.

Filter

Comments

QUICKNAVI