Filtering function

Filters allow calling before and/or after processing the action, which can vastly simplify your code itself and provide excellent opportunities for code reuse.



Introduction of build-in filters
  • Application filter :
    This filter helps to implement emulated application variable function. Application variable can be accessed and modified by every session. In PHP, there is no application variable like ASP. This filter emulates application function by saving all application variables in one temp file. By default, this temp file locates in "<framework main folder>/temp/application.data".

    Configuration of Application filter :
    You can change the location and file name of application temp file by following steps:
     
    1. Find this line from "components.xml".

      <filter filterPath="filter/ApplicationFilter.php" name="Application" className="ApplicationFilter"/>

    2. We can add parameter (appTempFile) in this filter.
      • appTempFile – defines the relative location(start from project root) of application temp file.
        *Note: This parameter is optional.

      Here is a example:
      <filter filterPath="filter/ApplicationFilter.php" name="Application" className="ApplicationFilter">
            <param name="appTempFile">class/test.tmp</param>
      </filter>

  • Validation filter:
    This filter helps to perform validation. All condition of validation is defined in XML file. If one action class wants to perform this filter, you should create one XML file to store all condition of validation and it should be named in "<Action class name>-validator.xml" format.

    Configuration of Validation filter:
    You can change the root folder which is used to store all validation XML files by following steps :
    1. Find this line from "filters.xml".
      <filter filterPath="filter/ValidationFilter.php" name="Validation" className="ValidationFilter"/>


    2. We can add parameter (validatorDir) in this filter.
      • validatorDir – define the relative location(start from project root) of folder which is used to store all validation XML files.
        *Note: This parameter is optional.

      Here is example:
      <filter filterPath="filter/ValidationFilter.php" name="Validation" className="ValidationFilter">    <param name="validatorDir">lib/kevix/config/validator/</param>
      </filter>

    Structure in XML file for validation :
    Coming soon...


  • IoC component filter :
    This filter helps to implement the type 2 of IOC (Inversion of Control). IOC is a design pattern that alleviates application objects from the responsibility of creating, and managing their dependencies. Type 2 of IOC uses setters for setting dependent components. All IoC components are defined in one XML file. By default, this XML file is located in "<main framework folder>/config/" and the name of IoC component XML file is "components.xml". By considering the performance of reading component XML file, KEVIX will cache the component setting into one temp file after every updating component XML file. By default, this file is located in "<main framework folder>/temp/component.tmp".

    Configuration of IoC component filter :
    You can change the name of IoC component XML file, the location of this XML file and the location of cache file by following steps:
    1. Find this line from "filters.xml".
      <filter filterPath="filter/IoCcomponentFilter.php" name="IoC" className="IoCcomponentFilter"/>

    2. We can add two parameters (xmlFile, cacheFile) in this filter.
      • xmlFile – define the relative location(start from project root) of component XML file.
      • cacheFile – define the relative location(start from project root) of component cache file.
        *Note: These two parameters are optional.

      Here is example:
      <filter filterPath="filter/IoCcomponentFilter.php" name="IoC" className="IoCcomponentFilter">
            <param name="XMLFile">lib/kevix/config/components.xml</param>
            <param name="cacheFile">lib/kevix/temp/components.tmp</param>
      </filter>

    Add IoC component to action class:
    All IoC components are defined in one XML file. By default, this XML file is located in "<main framework folder>/config/" and the name of IoC component XML file is "components.xml".
    1. Add filter to action class
      In action mapping file, we add <ref-filter> tag in this action class.

      Here is an example :
      <action actionPath="XXXAction.php" name="XXX" className="XXXAction">
            <rel-filter name="IoC"/>
            ……
      </action>

    2. Defines component in IoC component XML file
      By default, the name of this XML file is "components.xml".
      Here is the example of IoC component XML file:
      <?xml version="1.0" encoding="UTF-8"?>
      <components>
         <component scope="request" classPath="class/action/test.php" className="Test" enabler="TestAware">
            <property name="string">str</property>
            <property name="email">email</property>
            <constructor-arg>Init's string ...</constructor-arg>
            <constructor-arg>Init's email ...</constructor-arg>
         </component>
         ……
      </components>

      Each component must have the following three attributes:
      • scope – Valid values are session and request. This determines the component's lifetime. Session scoped components exist for the duration of a user session, while components in request scope only last for the duration of a single client request.
      • class – This specifies the component's class. An instance of this object will live for the duration of the specified scope, and will be made available to any actions (or other code) as required.
      • enabler – Any actions that are an instanceof the enabler class or interface will be passed an instance of the component.

      Each "component" tag can include the following two types of tag :
      • property – indicate that when Component Manager initiates component object, it will also perform some "set" method(s) of this object to set value(s). The "name" attribute defines "set" method in component object which want to perform it to set value. The content of "property" tag is the value which you want to set into variable. In this example, Component Manager will call "setString" and "setEmail" methods of "Test" class (component object) to set values.
      • constructor-arg – defines value of init argument of component object. The order of "constructor-arg" tag is order of argument. In this example, Component Manager will initiates component object by following code :
        componentObject = new Test ( "Init's string ..." , "Init's email ...");

    3. Write interface class to use as enabler
      We should write an interface class and its name must be same as the value of "enabler" attribute which is defined in IoC component XML file. In this interface, we should define one set method in this interface class. This set method is used to set IoC component object into action class by this filter. In this example, we should write interface class which is called "TestAware" and defines "setTest" method in interface class.

      TestAware.php :
      <?php
      interface TestAware {
            public function setTest($test);
      }
      ?>

    4. Modify action class to implement that interface class
      Action class should implement relative interface class so that the IoC component filter can know which component object should be set into action class. Now, you can call the object in action class directly.

      Here is an example of action class:
      <?php
      include_once ("ActionBase.php");
      include_once ("class/implement/TestAware.php");

      class XXXAction extends ActionBase implements TestAware {
         private $test;

         public function execute() {
            $this->test->setString("Execute");
            return "form";
         }

         public function setTest($object) {
            $this->test = $object;
         }
         ……
      }

  • File upload filter:
    This filter helps to check and limited file type and file size of every upload file. It also checks the total file size of all upload files.

    Configuration of file upload filter:
    You can configure the rule of checking upload file by following steps :
    1. Find this line from "components.xml".
      <filter filterPath="filter/FileUploadFilter.php" name="FileUpload" className="FileUploadFilter"/>

    2. We can add following parameters in this filter.
      • allowedTypes – define all accept file types of all upload files.
      • allowedTypesErrMsg – define error message of disallowing file types of upload file.
      • eachMaxSize – define maximum file size (in byte) of each upload file.
      • eachMaxSizeErrMsg – define error message of exceeding maximum file size of each upload file.
      • totalMaxSize – define maximum total of file size (in byte) of all upload files.
      • totalMaxSizeErrField – define variable name which is used to store the error message of exceeding maximum total of file size of all upload files.
      • totalMaxSizeErrMsg – define the error message of exceeding maximum total of file size of all upload files.
        *Note: All parameters are optional.

      Here is example:
      <filter filterPath="filter/FileUploadFilter.php" name="FileUpload" className="FileUploadFilter">
            <param name="allowedTypes">text/plain,image/pjpeg</param>
            <param name="allowedTypesErrMsg">Not in type!</param>
            <param name="eachMaxSize">0</param>
            <param name="eachMaxSizeErrMsg">Max file size!</param>
            <param name="totalMaxSize">300000</param>
            <param name="totalMaxSizeErrField">test2</param>
            <param name="totalMaxSizeErrMsg">Max total file size!</param>
      </filter>

  • I18N filter:
    This filter does not complete.


  • Log filter:
    This filter does not complete.
How to write your own filter
  1. Write filter class and extends to "FilterBase" class.
    All filters must extend to "FilterBase" abstract class. In "FilterBase" class, it provides the following methods to use:
    • getFilterParameters() – return all parameters of filter which are defined in filters.xml. The return value is in PHP Array format. (i.e. $parameters["<param name>"] = "<param value>")
    • getParameters() – return all parameters which are came from "request" data. (POST/GET method in HTML Form). The return value is in PHP Array format. (i.e. $parameters["<param name>"] = "<param value>")
    • getActionObject() – return the reference object of action class which is called.

  2. Defines "init", "destroy", "filterIn" and "filterOut" methods in your filter class.
    As "FilterBase" class defines these four abstract methods, each filter must define these four methods.
    • init() – this method will be run when the filter is initiated.
    • filterIn() – this method is run before performing action in action class. This method can return string value which is represented "return" string value of template file. If it returns value, all following filters and action class will not run.
    • filterOut() –this method is run after performing action in action class.
    • destroy() - this method will be run before the filter is unset.

  3. Registers your filter in "filters.xml" file.
    All filters must be registered in "filters.xml" by using "filter" tag. Several attributes must be defined in "filter" tag:
    • filterPath – defines the location of filter class file.
    • Name – defines the keyword of filter. It will be referred by "ref-filter" tag in action mapping file.
    • className – defines the class name of filter.

    Some filter may have parameter(s) to decide some action. In "filter" tag, "param" tag is used to set value of filter parameter. In filter class, you can call "getFilterParameters()" method to get all filter parameters.

    <filters>
       ……
       <filter filterPath="xxx.php" name="xxx" className="xxx">
          <param name="xxx">……</param>
          <param name="xxx">……</param>
          ……
       </filter>
       ……
    </filters>