PHP Classes

Output Filter: Filter scalars, arrays, data objects recursively

Recommend this page to a friend!
  Info   View files View files (26)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not enough user ratingsTotal: 483 All time: 5,899 This week: 423Up
Version License PHP version Categories
outputfilter 1.0.1BSD License5.2.5PHP 5, Data types, Validation
Description Author

This package can be used to filter the values of scalars, arrays, data objects recursively.

It can take an arbitrary value and apply filtering operations implemented by separate filter classes.

Arrays and objects can be traversed recursively to filter all their member values.

Multiple filter objects can be arranged in a chain to perform several types of filtering operations.

Currently the package includes filter classes for encoding text as HTML with entities, convert new line characters to HTML line break tags, etc..

This package also provides wrappers to use the filters with the Zend Framework and Smarty template engine.

Innovation Award
PHP Programming Innovation award nominee
July 2010
Number 5


Prize: One book of choice by Packt
Data filtering is often used to prevent security problems related with receiving data in incorrect formats from the user or external systems.

This class provides a solution for performing filtering, not only to simple text or numeric values, but also to complex array or object structures.

Manuel Lemos
Picture of Fabian Schmengler
  Performance   Level  
Name: Fabian Schmengler is available for providing paid consulting. Contact Fabian Schmengler .
Classes: 6 packages by
Country: Germany Germany
Age: 39
All time rank: 105365 in Germany Germany
Week rank: 587 Up32 in Germany Germany Up
Innovation award
Innovation award
Nominee: 4x

Details
+-----------------------------------------------------------------------------+ | OutputFilter | +-----------------------------------------------------------------------------+ - Synopsis - Requirements - Version - Files - Simple Usage - Extended Usage: Wrapper Constraints - Extended Usage: Wrapper Behaviour - Extended Usage: Nested Wrappers - Extended Usage: Integrations - Technical Remarks Synopsis -------- Often you have to call some filter function like htmlspecialchars() to all of your output data (or at least to most of it). With OutputFilter this can be done all at once. It can filter a whole object, that is all of its properties and even all method results like from getter methods. It can also filter all elements of an array and all this is done recursively. In fact it acts as a wrapper that wraps the original object/array and replaces it. Should you need the unfiltered value, just call unfiltered() on it. There are integrations for Zend_View and Smarty where everything gets wrapped automatically. Requirements ------------ The package requires PHP 5.2.5 or later because it relies on the Typesafe Enum package (http://www.phpclasses.org/package/6021). To use the package, just include outputfilter.lib.php (also edit that file to include the Typesafe Enum package properly). Version ------- This file refers to OutputFilter 1.0.1. See changelog.txt for details. Files ----- readme.txt - the file you are reading right now license.txt - BSD license outputfilter.lib.php - library loader, include this file to use the package OutputFilterWrapper.php - class file: main class OutputFilterWrapperInterface.php - class file: interface OutputFilterWrapperConstraints - class file: filter contraints OutputFilterWrapperBehaviour - class file: filter behaviour on scalars OutputFilterWrapperChain - class file: class for nested wrappers FilteredAbstract.php - class file: abstract class for filtered variables FilteredIterator.php - class file: abstract class for filtered iterators FilteredObject.php - class file: class for filtered objects FilteredArray.php - class file: class for filtered arrays FilteredArrayObject.php - class file: class for filtered objects with ArrayAccess FilteredScalar.php - class file: class for filtered scalars example/filter.example.php - executable example example/data.example.php - data for filter.example.php Filters/FilterChain.php - class file: filter that combines multiple filters Filters/HtmlEntitiesFilter.php - class file: htmlentities() filter Filters/Nl2BrFilter.php - class file: nl2br() filter Filters/NullFilter.php - class file: dummy filter Integrations/Smarty/prefilter.wrapper.php - smarty plugin Integrations/ZendView/FilteredZendView.php - Zend_View extension test/OutputFilterTestSuite.php - PHPUnit test suite test/OutputFilterWrapperTest.php - PHPUnit test case test/OutputFilterWrapperConstraintsTest.php - PHPUnit test case Simple Usage ------------ First initialize the wrapper with any filter. The package brings some useful filter classes (HtmlEntitiesFilter, Nl2BrFilter, FilterChain) but you can easily implement your own filters or use filters from the Zend_Filter package. $wrapper = new OutputFilterWrapper(new HtmlEntitiesFilter); Then you can use it like this: $wrapper->wrap($var1); $wrapper->wrap($var2); $wrapper->wrap($var3); ... $var may be anything, from a simple scalar value to arrays and objects to even resources (the latter being untouched). But the wrapper shows its strengths when used with complex object and array structures. In general the wrapped variables can be used just like the originals, but every string values are returned filtered. For example, if $var1 was an object with the respective properties and methods, the following is possible and will output filtered strings: echo $var1->getFoo(); echo $var1->foo; echo $var1->fooArray[0]; echo $var1->fooObject->bar; If you need single values unfiltered, no problem: echo $var1->foo->unfiltered(); If you have to compare filtered values, they should be converted to strings explicitly (see also: Extended Usage: Wrapper Behaviour), for example: echo ((string)$var1->foo) === '') ? 'empty' : $var1->foo; The same goes for usage of string functions like: strlen((string)$var1->foo) - Extended Usage: Wrapper Constraints ------------------------------------- You can constrain the wrapper to include or exclude certain methods, properties and array keys from being filtered. You can modify these constraints via the getConstraints() method like that: $wrapper->getConstraints()->includeProperties = '/.../'; $wrapper->getConstraints()->excludeProperties = '/.../'; $wrapper->getConstraints()->includeMethods = '/.../'; $wrapper->getConstraints()->excludeMethods = '/.../'; $wrapper->getConstraints()->includeArrayKeys = '/.../'; $wrapper->getConstraints()->excludeArrayKeys = '/.../'; or set them via constructor: $constraints = array( 'includeProperties' => '/.../', 'excludeProperties' => '/.../', 'includeMethods' => '/.../', 'excludeMethods' =>'/.../', 'includeArrayKeys' =>'/.../', 'excludeArrayKeys' =>'/.../', ); $wrapper = new OutputFilterWrapper($filter, $constraints); Insert any regular expression instead of '/.../'. Constraints have the following priority: - If the include-pattern is set and does not match, no filtering happens - If the include-pattern is set and matches but the exclude-pattern also is set and matches, no filtering happens - If the include-pattern is not set but the exclude-pattern is set and matches, no filtering happens. - All other cases: Filtering happens :) Extended Usage: Wrapper Behaviour --------------------------------- By default, the wrapper handles scalars as follows: strings are being wrapped into FilteredScalar objects, whose __toString() method returns the filtered value, whereas integers, booleans and null values are not filtered at all. For all of these types you can specify the behaviour individually via the following methods of OutputFilterWrapper: setStringFilterBehaviour($behaviour) setIntFilterBehaviour($behaviour) setDoubleFilterBehaviour($behaviour) setBoolFilterBehaviour($behaviour) setNullFilterBehaviour($behaviour) where the $behaviour parameter has one of the following values: OutputFilterWrapperBehaviour::FILTER() OutputFilterWrapperBehaviour::WRAP() OutputFilterWrapperBehaviour::NONE() notice the parantheses issued from the TypeSafeEnum package! In detail: FILTER: the value will be filtered directly WRAP: the value will be wrapped into a FilteredScalar object (see above) NONE: the value will be returned unchanged Extended Usage: Nested Wrappers ------------------------------- It is possible to use multiple wrappers on a variable. This might sound useless because if you just want to use multiple filters in a row, you can chain them with the FilterChain class: $filter = new FilterChain; $filter->pushFilter(new HtmlEntitiesFilter) ->pushFilter(new Nl2BrFilter); But it makes sense as soon as the wrappers use different constraints! Let's say you pass an array of variables to your view script and all keys starting with 'bb' are BBCode that should be translated to HTML (You have written a filter class BBCodeFilter for this purpose) $standardWrapper = new OutputFilterWrapper(new HtmlEntitiesFilter); $bbCodeWrapper = new OutputFilterWrapper(new BBCodeFilter); $bbCodeWrapper->getConstraints()->includeArrayKeys = '/^bb/'; $bbCodeWrapper->getConstraints()->includeProperties = OutputFilterWrapperConstraints::NONE; $bbCodeWrapper->getConstraints()->includeMethods = OutputFilterWrapperConstraints::NONE; $bbCodeWrapper->wrap($vars); $standardWrapper->wrap($vars); Now first every special characters get converted to html entities and then, if the array key started with 'bb', the BBCode gets translated to HTML. This order is important; notice that the wrapping order is the other way around, the first (innermost) wrapper gets called last when it comes to filtering. If you want to use the same nesting repeatedly, you can do it easily with the OutputFilterWrapperChain class: $nestedWrapper = new OutputFilterWrapperChain; $nestedWrapper->pushWrapper($bbCodeWrapper) ->pushWrapper($standardWrapper); $nestedWrapper->wrap($vars); // ... This is especially useful for the framework integrations (see next section). Instead of adding wrappers at the end of the chain with pushWrapper() it is also possible to add them at the beginning with appendWrapper(). Extended Usage: Integrations ---------------------------- The package is easily integrable into existing frameworks, two examples are supplied in the Integrations directory. Smarty: just put prefilter.wrapper.php in your plugins folder and include the library loader (outputfilter.lib.php) anywhere. By default, all smarty variables are filtered with HtmlEntitiesFilter, for customization see the comment section of the plugin file. Zend Framework (Zend_View): in your view initalization replace Zend_View with FilteredZendView which is a direct descendant of Zend_View and assign a wrapper with $view->setOutputFilterWrapper($wrapper); Both implementations rely on a single wrapper instance, but this may also be a OutputFilterWrapperChain instance with nested wrappers. Technical Remarks ----------------- __1.__ unfiltered() __ echo $var1->foo->unfiltered(); is equivalent to: echo $var1->unfiltered()->foo; Calling unfiltered() at a higher level has the same result but is a bit faster! __2.__ wrap() and filterRecursive() __ $wrapper->wrap($var) is a shortcut for: $var = $wrapper->filterRecursive($var); If you do not want to replace the original variable, use filterRecursive! __3.__ filter method __ The filtering always happens on demand, not on wrapping. Only exception is the direct wrapping of a scalar value if the respective behaviour is set to FILTER. __4.__ special objects __ Wrapped instances of ArrayAccess or Iterator will retain these interfaces and thus still can be used accordingly. __5.__ scalar() __ If you have a filter that returns not only strings and you need to get the filtered variable with its exact type, you can use the scalar() method of FilteredScalar: $var->foo->scalar() it does the same as the __toString() method but without casting the filtered value to a string. Unlike unfiltered() this only works on filtered scalars not on complex variables (i.e. $var->scalar()->foo is not possible - remember that the real filtering only happens at the end, on scalar values)
  Files folder image Files  
File Role Description
Files folder imageexample (2 files)
Files folder imageFilters (4 files)
Files folder imageIntegrations (2 directories)
Files folder imagetest (3 files)
Plain text file changelog.txt Doc. Changelog
Plain text file license.txt Lic. BSD License
Accessible without login Plain text file readme.txt Doc. Full documentation
Plain text file outputfilter.lib.php Aux. library loader, include this file to use the package
Plain text file OutputFilterWrapper.php Class Main class
Plain text file OutputFilterWrapperBehaviour.php Class filter behaviour on scalars
Plain text file OutputFilterWrapperChain.php Class class for nested wrappers
Plain text file OutputFilterWrapperConstraints.php Class filter constraints
Plain text file OutputFilterWrapperInterface.php Class interface
Plain text file FilteredAbstract.php Class abstract class for filtered variables
Plain text file FilteredArray.php Class class for filtered arrays
Plain text file FilteredArrayObject.php Class class for filtered objects with ArrayAccess
Plain text file FilteredIterator.php Class abstract class for filtered iterators
Plain text file FilteredObject.php Class class for filtered objects
Plain text file FilteredScalar.php Class class for filtered scalars

  Files folder image Files  /  example  
File Role Description
  Plain text file data.example.php Example data for filter.example.php
  Accessible without login Plain text file filter.example.php Example executable example

  Files folder image Files  /  Filters  
File Role Description
  Plain text file FilterChain.php Class filter that combines multiple filters
  Plain text file HtmlEntitiesFilter.php Class htmlentities() filter
  Plain text file Nl2BrFilter.php Class nl2br() filter
  Plain text file NullFilter.php Class dummy filter

  Files folder image Files  /  Integrations  
File Role Description
Files folder imageSmarty (1 file)
Files folder imageZendView (1 file)

  Files folder image Files  /  Integrations  /  Smarty  
File Role Description
  Plain text file prefilter.wrapper.php Aux. Smarty plugin

  Files folder image Files  /  Integrations  /  ZendView  
File Role Description
  Plain text file FilteredZendView.php Class Zend_View extension

  Files folder image Files  /  test  
File Role Description
  Plain text file OutputFilterTestSuite.php Test PHPUnit test suite
  Plain text file OutputFilterWrapperConstraintsTest.php Test PHPUnit test case
  Plain text file OutputFilterWrapperTest.php Test PHPUnit test case

Downloadoutputfilter-2010-10-21.zip
Downloadoutputfilter-2010-10-21.tar.gz 12KB
Install with ComposerInstall with Composer
Needed packages  
Class DownloadWhy it is needed Dependency
Typesafe Enum Download .zip .tar.gz Enumeration data type Required
 Version Control Unique User Downloads Download Rankings  
 0%
Total:483
This week:0
All time:5,899
This week:423Up