Apache Zeta Components Manual :: File Source for group_filter.php
Source for file group_filter.php
Documentation is available at group_filter.php
* File containing the ezcAuthenticationGroupFilter class.
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
* @package Authentication
* Group authentication filters together.
* If there are no filters in the group, then the run() method will return
* The way of grouping the filters is specified with the mode option:
* - ezcAuthenticationGroupFilter::MODE_OR (default): at least one filter
* in the group needs to succeed in order for the group to succeed.
* - ezcAuthenticationGroupFilter::MODE_AND: all filters in the group
* need to succeed in order for the group to succeed.
* Example of using the mode option:
* $options = new ezcAuthenticationGroupOptions();
* $options->mode = ezcAuthenticationGroupFilter::MODE_AND;
* // $filter1 and $filter2 are authentication filters which all need to succeed
* // in order for the group to succeed
* $filter = new ezcAuthenticationGroupFilter( array( $filter1, $filter2 ), $options );
* Example of using the group filter with LDAP and Database filters:
* $credentials = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'qwerty' );
* // create a database filter
* $database = new ezcAuthenticationDatabaseInfo( ezcDbInstance::get(), 'users', array( 'user', 'password' ) );
* $databaseFilter = new ezcAuthenticationDatabaseFilter( $database );
* // create an LDAP filter
* $ldap = new ezcAuthenticationLdapInfo( 'localhost', 'uid=%id%', 'dc=example,dc=com', 389 );
* $ldapFilter = new ezcAuthenticationLdapFilter( $ldap );
* $authentication = new ezcAuthentication( $credentials );
* // use the database and LDAP filters in paralel (at least one needs to succeed in
* // order for the user to be authenticated)
* $authentication->addFilter( new ezcAuthenticationGroupFilter( array( $databaseFilter, $ldapFilter ) ) );
* // add more filters if needed
* if ( !$authentication->run() )
* // authentication did not succeed, so inform the user
* $status = $authentication->getStatus();
* array( 'ezcAuthenticationLdapFilter' => array(
* ezcAuthenticationLdapFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
* ezcAuthenticationLdapFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
* array( 'ezcAuthenticationDatabaseFilter' => array(
* ezcAuthenticationDatabaseFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
* ezcAuthenticationDatabaseFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
* foreach ( $status as $line => $error )
* list( $key, $value ) = each( $error );
* echo $err[$line][$key][$value] . "\n";
* // authentication succeeded, so allow the user to see his content
* It is possible to use multiple credentials when grouping filters together, by
* enabling the option multipleCredentials for the Group filter object. When this
* option is enabled, each filter added to the group must have a credentials
* object passed along with it.
* Example of using the Group filter to handle multiple credentials:
* $credentials1 = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'b1b3773a05c0ed0176787a4f1574ff0075f7521e' ); // incorrect password
* $credentials2 = new ezcAuthenticationPasswordCredentials( 'john.doe', 'wpeE20wyWHnLE' ); // correct username + password
* $options = new ezcAuthenticationGroupOptions();
* $options->multipleCredentials = true;
* $options->mode = ezcAuthenticationGroupFilter::MODE_AND;
* $group = new ezcAuthenticationGroupFilter( array(), $options );
* $group->addFilter( new ezcAuthenticationHtpasswdFilter( '../../tests/filters/htpasswd/data/htpasswd' ), $credentials1 );
* $group->addFilter( new ezcAuthenticationHtpasswdFilter( '../../tests/filters/htpasswd/data/htpasswd' ), $credentials2 );
* $authentication = new ezcAuthentication( $credentials1 );
* $authentication->addFilter( $group );
* // add more filters if needed
* if ( !$authentication->run() )
* // authentication did not succeed, so inform the user
* $status = $authentication->getStatus();
* array( 'ezcAuthenticationHtpasswdFilter' => array(
* ezcAuthenticationHtpasswdFilter::STATUS_OK => '',
* ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username ' . $credentials1->id,
* ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password for ' . $credentials1->id
* array( 'ezcAuthenticationHtpasswdFilter' => array(
* ezcAuthenticationHtpasswdFilter::STATUS_OK => '',
* ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username ' . $credentials2->id,
* ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password for ' . $credentials2->id
* foreach ( $status as $line => $error )
* list( $key, $value ) = each( $error );
* echo $err[$line][$key][$value] . "\n";
* // authentication succeeded, so allow the user to see his content
* @property ezcAuthenticationStatus $status
* The status object which holds the status of the run filters.
* @package Authentication
* All or some of the filters in the group failed (depeding on the mode
* At least one filter needs to succeed in order for the group to succeed.
* All the filters need to succeed in order for the group to succeed.
* Authentication filters.
* @var array(ezcAuthenticationFilter)
* The properties of this class.
* @var array(string=>mixed)
private $properties =
array();
* Creates a new object of this class.
* The filters can be specified as an array of filter objects, or as an
* array of array(fiter,credentials) when the multipleCredentials option is
* Example of using multipleCredentials:
* $credentials1 = new ezcAuthenticationPasswordCredentials( 'john.doe', '1234' );
* $credentials1 = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'qwerty' );
* $filter1 = new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd1' );
* $filter2 = new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd2' );
* // enable multiple credentials
* $options = new ezcAuthenticationGroupOptions();
* $options->multipleCredentials = true;
* // add the filters to the group with the constructor
* $group = new ezcAuthenticationGroupFilter( array(
* array( $filter1, $credentials1 ),
* array( $filter2, $credentials2 ) ), $options );
* // the filters can also be added to the group with addFilter()
* @throws ezcAuthenticationException
* if the multipleCredentials option is enabled and a credentials
* object was not specified
* @param array(ezcAuthenticationFilter|mixed)$filters Authentication filters
* @param ezcAuthenticationGroupOptions $options Options for this class
public function __construct( array $filters, ezcAuthenticationGroupOptions $options =
null )
$this->options =
( $options ===
null ) ?
new ezcAuthenticationGroupOptions() :
$options;
foreach ( $filters as $filter )
if ( is_array( $filter ) )
if ( count( $filter ) >
1 )
* Sets the property $name to $value.
* @throws ezcBasePropertyNotFoundException
* if the property $name does not exist
* @throws ezcBaseValueException
* if $value is not correct for the property $name
* @param string $name The name of the property to set
* @param mixed $value The new value of the property
public function __set( $name, $value )
$this->properties[$name] =
$value;
* Returns the value of the property $name.
* @throws ezcBasePropertyNotFoundException
* if the property $name does not exist
* @param string $name The name of the property for which to return the value
public function __get( $name )
return $this->properties[$name];
* Returns true if the property $name is set, otherwise false.
* @param string $name The name of the property to test if it is set
public function __isset( $name )
return isset
( $this->properties[$name] );
* Runs the filter and returns a status code when finished.
* @param ezcAuthenticationCredentials $credentials Authentication credentials
public function run( $credentials )
if ( $this->options->mode ===
self::MODE_OR )
foreach ( $this->filters as $filter )
$credentials =
( $this->options->multipleCredentials ===
true ) ?
$filter[1] :
$code =
$filter[0]->run( $credentials );
$this->status->append( get_class( $filter[0] ), $code );
if ( $code ===
self::STATUS_OK )
if ( $this->options->mode ===
self::MODE_AND )
foreach ( $this->filters as $filter )
$credentials =
( $this->options->multipleCredentials ===
true ) ?
$filter[1] :
$code =
$filter[0]->run( $credentials );
$this->status->append( get_class( $filter[0] ), $code );
if ( $code !==
self::STATUS_OK )
// other modes are not possible due to the way mode is set in __set()
return ( $success ===
true ) ?
self::STATUS_OK :
self::STATUS_GROUP_FAILED;
* Adds an authentication filter at the end of the filter list.
* Example of using multipleCredentials:
* $credentials1 = new ezcAuthenticationPasswordCredentials( 'john.doe', '1234' );
* $credentials1 = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'qwerty' );
* $filter1 = new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd1' );
* $filter2 = new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd2' );
* // enable multiple credentials
* $options = new ezcAuthenticationGroupOptions();
* $options->multipleCredentials = true;
* // add the filters to the group with addFilter()
* $group = new ezcAuthenticationGroupFilter( array(), $options );
* $group->addFilter( $filter1, $credentials1 );
* $group->addFilter( $filter2, $credentials2 );
* // the filters can also be added to the group with the constructor
* @throws ezcAuthenticationGroupException
* if the multipleCredentials option is enabled and a credentials
* object was not specified
* @param ezcAuthenticationFilter $filter The authentication filter to add
* @param ezcAuthenticationCredentials $credentials Credentials object associated
* with $filter if the multipleCredentials
public function addFilter( ezcAuthenticationFilter $filter, ezcAuthenticationCredentials $credentials =
null )
if ( $this->options->multipleCredentials ===
true )
if ( $credentials ===
null )
$this->filters[] =
array( $filter, $credentials );
$this->filters[] =
array( $filter );