Filters
- Filters are a way for controller action methods to share similar code pre/post execution. Useful applications for filters include authentication and permission checking before actions take place.
- Filters can be in the form of a Class, or a method inside the controller class.
- Classes must be saved in a file named accordingly: "YourClassName.filter.php". That file should reside in the app/filter directory. It needs to contain a process method that takes the controller object and an array of the request data that controller actions receive as parameters, in that order.
- Methods need only be accessible via the superclass, BaseController, and take in an array that is the request data that controller actions receive as their parameter.
-
To apply filters, you just need to override a protected $filters array on your controller. That array contains filter definitions, which are arrays in themselves. An example of a definition of filters is shown below:
protected $filters = array( array('filter' => 'MyFilter') );This would first look for a class named MyFilter located in the file app/filter/MyFilter.filter.php and call the process() method on it. If that class doesn't exist, the framework would try and call a method named "MyFilter" on the current controller.
-
To configure your filter, you may include the following values in your filter definition array:
-
applyTo - the value for this key may be either a string, or an array of strings representing which controller actions to apply the filter to. If applyTo and exclude are omitted from the definition array, all action methods will have the filter applied to them. Keep in mind, for specifying which controller action methods to apply the filter to, you need only include the action name, not the full method name. For example, if I want to apply the filter to my "index" action method, I only need to put "index", not "indexAction". Below are several examples of filter definitions:
//Apply MyFilter to my "indexAction" controller action method protected $filters = array( array('filter' => 'MyFilter', 'applyTo' => 'index') ); //Apply "MyFilter" to my "indexAction" and "testAction" controller action methods protected $filters = array( array('filter' => 'MyFilter', 'applyTo' => array('index', 'test')) );
-
exclude - this works similar to applyTo, accepting a single string, or an array of strings representing action methods in the controller, however, the filter will be applied to any methods except the ones listed. Below are several examples of filter definitions:
//Apply MyFilter to all controller action methods except "indexAction" protected $filters = array( array('filter' => 'MyFilter', 'exclude' => 'index') ); //Apply MyFilter to all controller action methods except "indexAction" and "testAction" protected $filters = array( array('filter' => 'MyFilter', 'exclude' => array('index', 'test')) );
- filter - this value is a string name of the filter class, or method within the controller you wish to have applied.
-
applyTo - the value for this key may be either a string, or an array of strings representing which controller actions to apply the filter to. If applyTo and exclude are omitted from the definition array, all action methods will have the filter applied to them. Keep in mind, for specifying which controller action methods to apply the filter to, you need only include the action name, not the full method name. For example, if I want to apply the filter to my "index" action method, I only need to put "index", not "indexAction". Below are several examples of filter definitions:
-
**Known Issues**
Currently filters are only applied pre controller action. The ability to apply filters pre/post controller action processing will be added added in the future.
