Apache Zeta Components Manual :: File Source for group_filter.php

Source for file group_filter.php

Documentation is available at group_filter.php

  1. <?php
  2. /**
  3.  * File containing the ezcAuthenticationGroupFilter class.
  4.  *
  5.  * Licensed to the Apache Software Foundation (ASF) under one
  6.  * or more contributor license agreements.  See the NOTICE file
  7.  * distributed with this work for additional information
  8.  * regarding copyright ownership.  The ASF licenses this file
  9.  * to you under the Apache License, Version 2.0 (the
  10.  * "License"); you may not use this file except in compliance
  11.  * with the License.  You may obtain a copy of the License at
  12.  * 
  13.  *   http://www.apache.org/licenses/LICENSE-2.0
  14.  * 
  15.  * Unless required by applicable law or agreed to in writing,
  16.  * software distributed under the License is distributed on an
  17.  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  18.  * KIND, either express or implied.  See the License for the
  19.  * specific language governing permissions and limitations
  20.  * under the License.
  21.  *
  22.  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
  23.  * @filesource
  24.  * @package Authentication
  25.  * @version //autogen//
  26.  */
  27.  
  28. /**
  29.  * Group authentication filters together.
  30.  *
  31.  * If there are no filters in the group, then the run() method will return
  32.  * STATUS_OK.
  33.  *
  34.  * The way of grouping the filters is specified with the mode option:
  35.  *  - ezcAuthenticationGroupFilter::MODE_OR (default): at least one filter
  36.  *    in the group needs to succeed in order for the group to succeed.
  37.  *  - ezcAuthenticationGroupFilter::MODE_AND: all filters in the group
  38.  *    need to succeed in order for the group to succeed.
  39.  *
  40.  * Example of using the mode option:
  41.  * <code>
  42.  * $options = new ezcAuthenticationGroupOptions();
  43.  * $options->mode = ezcAuthenticationGroupFilter::MODE_AND;
  44.  *
  45.  * // $filter1 and $filter2 are authentication filters which all need to succeed
  46.  * // in order for the group to succeed
  47.  * $filter = new ezcAuthenticationGroupFilter( array( $filter1, $filter2 ), $options );
  48.  * </code>
  49.  *
  50.  * Example of using the group filter with LDAP and Database filters:
  51.  * <code>
  52.  * $credentials = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'qwerty' );
  53.  *
  54.  * // create a database filter
  55.  * $database = new ezcAuthenticationDatabaseInfo( ezcDbInstance::get(), 'users', array( 'user', 'password' ) );
  56.  * $databaseFilter = new ezcAuthenticationDatabaseFilter( $database );
  57.  *
  58.  * // create an LDAP filter
  59.  * $ldap = new ezcAuthenticationLdapInfo( 'localhost', 'uid=%id%', 'dc=example,dc=com', 389 );
  60.  * $ldapFilter = new ezcAuthenticationLdapFilter( $ldap );
  61.  * $authentication = new ezcAuthentication( $credentials );
  62.  *
  63.  * // use the database and LDAP filters in paralel (at least one needs to succeed in
  64.  * // order for the user to be authenticated)
  65.  * $authentication->addFilter( new ezcAuthenticationGroupFilter( array( $databaseFilter, $ldapFilter ) ) );
  66.  * // add more filters if needed
  67.  * if ( !$authentication->run() )
  68.  * {
  69.  *     // authentication did not succeed, so inform the user
  70.  *     $status = $authentication->getStatus();
  71.  *     $err = array(
  72.  *             array( 'ezcAuthenticationLdapFilter' => array(
  73.  *                 ezcAuthenticationLdapFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
  74.  *                 ezcAuthenticationLdapFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
  75.  *                 ) ),
  76.  *             array( 'ezcAuthenticationDatabaseFilter' => array(
  77.  *                 ezcAuthenticationDatabaseFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
  78.  *                 ezcAuthenticationDatabaseFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
  79.  *                 ) )
  80.  *             );
  81.  *     foreach ( $status as $line => $error )
  82.  *     {
  83.  *         list( $key, $value ) = each( $error );
  84.  *         echo $err[$line][$key][$value] . "\n";
  85.  *     }
  86.  * }
  87.  * else
  88.  * {
  89.  *     // authentication succeeded, so allow the user to see his content
  90.  * }
  91.  * </code>
  92.  *
  93.  * It is possible to use multiple credentials when grouping filters together, by
  94.  * enabling the option multipleCredentials for the Group filter object. When this
  95.  * option is enabled, each filter added to the group must have a credentials
  96.  * object passed along with it.
  97.  *
  98.  * Example of using the Group filter to handle multiple credentials:
  99.  * <code>
  100.  * $credentials1 = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'b1b3773a05c0ed0176787a4f1574ff0075f7521e' ); // incorrect password
  101.  * $credentials2 = new ezcAuthenticationPasswordCredentials( 'john.doe', 'wpeE20wyWHnLE' ); // correct username + password
  102.  *
  103.  * $options = new ezcAuthenticationGroupOptions();
  104.  * $options->multipleCredentials = true;
  105.  * $options->mode = ezcAuthenticationGroupFilter::MODE_AND;
  106.  * $group = new ezcAuthenticationGroupFilter( array(), $options );
  107.  *
  108.  * $group->addFilter( new ezcAuthenticationHtpasswdFilter( '../../tests/filters/htpasswd/data/htpasswd' ), $credentials1 );
  109.  * $group->addFilter( new ezcAuthenticationHtpasswdFilter( '../../tests/filters/htpasswd/data/htpasswd' ), $credentials2 );
  110.  *
  111.  * $authentication = new ezcAuthentication( $credentials1 );
  112.  * $authentication->addFilter( $group );
  113.  * // add more filters if needed
  114.  *
  115.  * if ( !$authentication->run() )
  116.  * {
  117.  *     // authentication did not succeed, so inform the user
  118.  *     $status = $authentication->getStatus();
  119.  *
  120.  *     $err = array(
  121.  *                 array( 'ezcAuthenticationHtpasswdFilter' => array(
  122.  *                         ezcAuthenticationHtpasswdFilter::STATUS_OK => '',
  123.  *                         ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username ' . $credentials1->id,
  124.  *                         ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password for ' . $credentials1->id
  125.  *                         ) ),
  126.  *
  127.  *                 array( 'ezcAuthenticationHtpasswdFilter' => array(
  128.  *                         ezcAuthenticationHtpasswdFilter::STATUS_OK => '',
  129.  *                         ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username ' . $credentials2->id,
  130.  *                         ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password for ' . $credentials2->id
  131.  *                         ) )
  132.  *                 );
  133.  *
  134.  *     foreach ( $status as $line => $error )
  135.  *     {
  136.  *         list( $key, $value ) = each( $error );
  137.  *         echo $err[$line][$key][$value] . "\n";
  138.  *     }
  139.  * }
  140.  * else
  141.  * {
  142.  *     // authentication succeeded, so allow the user to see his content
  143.  * }
  144.  * </code>
  145.  *
  146.  * @property ezcAuthenticationStatus $status 
  147.  *            The status object which holds the status of the run filters.
  148.  *
  149.  * @package Authentication
  150.  * @version //autogen//
  151.  * @mainclass
  152.  */
  153. {
  154.     /**
  155.      * All or some of the filters in the group failed (depeding on the mode
  156.      * option).
  157.      */
  158.     const STATUS_GROUP_FAILED = 1;
  159.  
  160.     /**
  161.      * At least one filter needs to succeed in order for the group to succeed.
  162.      */
  163.     const MODE_OR = 1;
  164.  
  165.     /**
  166.      * All the filters need to succeed in order for the group to succeed.
  167.      */
  168.     const MODE_AND = 2;
  169.  
  170.     /**
  171.      * Authentication filters.
  172.      * 
  173.      * @var array(ezcAuthenticationFilter) 
  174.      */
  175.     protected $filters = array();
  176.  
  177.     /**
  178.      * The properties of this class.
  179.      * 
  180.      * @var array(string=>mixed) 
  181.      */
  182.     private $properties array();
  183.  
  184.     /**
  185.      * Creates a new object of this class.
  186.      *
  187.      * The filters can be specified as an array of filter objects, or as an
  188.      * array of array(fiter,credentials) when the multipleCredentials option is
  189.      * enabled.
  190.      *
  191.      * Example of using multipleCredentials:
  192.      * <code>
  193.      * $credentials1 = new ezcAuthenticationPasswordCredentials( 'john.doe', '1234' );
  194.      * $credentials1 = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'qwerty' );
  195.      *
  196.      * $filter1 = new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd1' );
  197.      * $filter2 = new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd2' );
  198.      *
  199.      * // enable multiple credentials
  200.      * $options = new ezcAuthenticationGroupOptions();
  201.      * $options->multipleCredentials = true;
  202.      *
  203.      * // add the filters to the group with the constructor
  204.      * $group = new ezcAuthenticationGroupFilter( array(
  205.      *              array( $filter1, $credentials1 ),
  206.      *              array( $filter2, $credentials2 ) ), $options );
  207.      *
  208.      * // the filters can also be added to the group with addFilter()
  209.      * </code>
  210.      *
  211.      * @throws ezcAuthenticationException
  212.      *          if the multipleCredentials option is enabled and a credentials
  213.      *          object was not specified
  214.      * @param array(ezcAuthenticationFilter|mixed)$filters Authentication filters
  215.      * @param ezcAuthenticationGroupOptions $options Options for this class
  216.      */
  217.     public function __constructarray $filtersezcAuthenticationGroupOptions $options null )
  218.     {
  219.         $this->options $options === null new ezcAuthenticationGroupOptions($options;
  220.  
  221.         foreach $filters as $filter )
  222.         {
  223.             if is_array$filter ) )
  224.             {
  225.                 if count$filter )
  226.                 {
  227.                     $this->addFilter$filter[0]$filter[1);
  228.                 }
  229.                 else
  230.                 {
  231.                     $this->addFilter$filter[0);
  232.                 }
  233.             }
  234.             else
  235.             {
  236.                 $this->addFilter$filter );
  237.             }
  238.         }
  239.  
  240.         $this->status new ezcAuthenticationStatus();
  241.     }
  242.  
  243.     /**
  244.      * Sets the property $name to $value.
  245.      *
  246.      * @throws ezcBasePropertyNotFoundException
  247.      *          if the property $name does not exist
  248.      * @throws ezcBaseValueException
  249.      *          if $value is not correct for the property $name
  250.      * @param string $name The name of the property to set
  251.      * @param mixed $value The new value of the property
  252.      * @ignore
  253.      */
  254.     public function __set$name$value )
  255.     {
  256.         switch $name )
  257.         {
  258.             case 'status':
  259.                 if $value instanceof ezcAuthenticationStatus )
  260.                 {
  261.                     $this->properties[$name$value;
  262.                 }
  263.                 else
  264.                 {
  265.                     throw new ezcBaseValueException$name$value'ezcAuthenticationStatus' );
  266.                 }
  267.                 break;
  268.  
  269.             default:
  270.                 throw new ezcBasePropertyNotFoundException$name );
  271.         }
  272.     }
  273.  
  274.     /**
  275.      * Returns the value of the property $name.
  276.      *
  277.      * @throws ezcBasePropertyNotFoundException
  278.      *          if the property $name does not exist
  279.      * @param string $name The name of the property for which to return the value
  280.      * @return mixed 
  281.      * @ignore
  282.      */
  283.     public function __get$name )
  284.     {
  285.         switch $name )
  286.         {
  287.             case 'status':
  288.                 return $this->properties[$name];
  289.  
  290.             default:
  291.                 throw new ezcBasePropertyNotFoundException$name );
  292.         }
  293.     }
  294.  
  295.     /**
  296.      * Returns true if the property $name is set, otherwise false.
  297.      *
  298.      * @param string $name The name of the property to test if it is set
  299.      * @return bool 
  300.      * @ignore
  301.      */
  302.     public function __isset$name )
  303.     {
  304.         switch $name )
  305.         {
  306.             case 'status':
  307.                 return isset$this->properties[$name);
  308.  
  309.             default:
  310.                 return false;
  311.         }
  312.     }
  313.  
  314.     /**
  315.      * Runs the filter and returns a status code when finished.
  316.      *
  317.      * @param ezcAuthenticationCredentials $credentials Authentication credentials
  318.      * @return int 
  319.      */
  320.     public function run$credentials )
  321.     {
  322.         if count$this->filters === )
  323.         {
  324.             return self::STATUS_OK;
  325.         }
  326.  
  327.         $success false;
  328.  
  329.         if $this->options->mode === self::MODE_OR )
  330.         {
  331.             $success false;
  332.             foreach $this->filters as $filter )
  333.             {
  334.                 $credentials $this->options->multipleCredentials === true $filter[1:
  335.                                                                                   $credentials;
  336.  
  337.                 $code $filter[0]->run$credentials );
  338.                 $this->status->appendget_class$filter[0)$code );
  339.                 if $code === self::STATUS_OK )
  340.                 {
  341.                     $success true;
  342.                 }
  343.             }
  344.         }
  345.  
  346.         if $this->options->mode === self::MODE_AND )
  347.         {
  348.             $success true;
  349.             foreach $this->filters as $filter )
  350.             {
  351.                 $credentials $this->options->multipleCredentials === true $filter[1:
  352.                                                                                   $credentials;
  353.  
  354.                 $code $filter[0]->run$credentials );
  355.                 $this->status->appendget_class$filter[0)$code );
  356.                 if $code !== self::STATUS_OK )
  357.                 {
  358.                     $success false;
  359.                 }
  360.             }
  361.         }
  362.  
  363.         // other modes are not possible due to the way mode is set in __set()
  364.         // in the options class
  365.  
  366.         return $success === true self::STATUS_OK :
  367.                                        self::STATUS_GROUP_FAILED;
  368.     }
  369.  
  370.     /**
  371.      * Adds an authentication filter at the end of the filter list.
  372.      *
  373.      * Example of using multipleCredentials:
  374.      * <code>
  375.      * $credentials1 = new ezcAuthenticationPasswordCredentials( 'john.doe', '1234' );
  376.      * $credentials1 = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'qwerty' );
  377.      *
  378.      * $filter1 = new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd1' );
  379.      * $filter2 = new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd2' );
  380.      *
  381.      * // enable multiple credentials
  382.      * $options = new ezcAuthenticationGroupOptions();
  383.      * $options->multipleCredentials = true;
  384.      *
  385.      * // add the filters to the group with addFilter()
  386.      * $group = new ezcAuthenticationGroupFilter( array(), $options );
  387.      * $group->addFilter( $filter1, $credentials1 );
  388.      * $group->addFilter( $filter2, $credentials2 );
  389.      *
  390.      * // the filters can also be added to the group with the constructor
  391.      * </code>
  392.      *
  393.      * @throws ezcAuthenticationGroupException
  394.      *          if the multipleCredentials option is enabled and a credentials
  395.      *          object was not specified
  396.      * @param ezcAuthenticationFilter $filter The authentication filter to add
  397.      * @param ezcAuthenticationCredentials $credentials Credentials object associated
  398.      *                                                   with $filter if the multipleCredentials
  399.      *                                                   option is enabled
  400.      */
  401.     public function addFilterezcAuthenticationFilter $filterezcAuthenticationCredentials $credentials null )
  402.     {
  403.         if $this->options->multipleCredentials === true )
  404.         {
  405.             if $credentials === null )
  406.             {
  407.                 throw new ezcAuthenticationGroupException'A credentials object must be specified for each filter when the multipleCredentials option is enabled.' );
  408.             }
  409.  
  410.             $this->filters[array$filter$credentials );
  411.         }
  412.         else
  413.         {
  414.             $this->filters[array$filter );
  415.         }
  416.     }
  417. }
  418. ?>
Documentation generated by phpDocumentor 1.4.3