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

Source for file authentication.php

Documentation is available at authentication.php

  1. <?php
  2. /**
  3.  * File containing the ezcAuthentication 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.  * Container for authentication filters.
  30.  *
  31.  * This is the main class of the authentication component. Filters are added to
  32.  * an object of this class, which will run the filters in sequence. At the end of
  33.  * this process, the status property will contain the statuses of the filters, and
  34.  * the developer can use those statuses to display to the user messages such as
  35.  * "Password incorrect".
  36.  *
  37.  * The session property is optional and it is used to store the authentication
  38.  * information between requests.
  39.  *
  40.  * The credentials property will be passed to all the filters in the queue.
  41.  *
  42.  * Example (using the Htpasswd filter):
  43.  * <code>
  44.  * $credentials = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'b1b3773a05c0ed0176787a4f1574ff0075f7521e' );
  45.  * $authentication = new ezcAuthentication( $credentials );
  46.  * $authentication->session = new ezcAuthenticationSession();
  47.  * $authentication->addFilter( new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd' ) );
  48.  * // add other filters if needed
  49.  * if ( !$authentication->run() )
  50.  * {
  51.  *     // authentication did not succeed, so inform the user
  52.  *     $status = $authentication->getStatus();
  53.  *     $err = array(
  54.  *             'ezcAuthenticationHtpasswdFilter' => array(
  55.  *                 ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
  56.  *                 ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
  57.  *                 )
  58.  *             );
  59.  *     foreach ( $status as $line )
  60.  *     {
  61.  *         list( $key, $value ) = each( $line );
  62.  *         echo $err[$key][$value] . "\n";
  63.  *     }
  64.  * }
  65.  * else
  66.  * {
  67.  *     // authentication succeeded, so allow the user to see his content
  68.  * }
  69.  * </code>
  70.  *
  71.  * @property ezcAuthenticationSession $session 
  72.  *            The session object to use during authentication to store the
  73.  *            authentication information between requests.
  74.  * @property ezcAuthenticationStatus $status 
  75.  *            The status object which holds the status of the run filters.
  76.  * @property ezcAuthenticationCredentials $credentials 
  77.  *            The user credentials to pass to the authentication filters.
  78.  *
  79.  * @package Authentication
  80.  * @version //autogen//
  81.  * @mainclass
  82.  */
  83. {
  84.     /**
  85.      * The filter queue of the authentication process.
  86.      * 
  87.      * @var array(ezcAuthenticationFilter) 
  88.      */
  89.     protected $filters = array();
  90.  
  91.     /**
  92.      * Options for the Authentication object.
  93.      * 
  94.      * @var ezcAuthenticationOptions 
  95.      */
  96.     protected $options;
  97.  
  98.     /**
  99.      * The properties of this class.
  100.      * 
  101.      * @var array(string=>mixed) 
  102.      */
  103.     private $properties array();
  104.  
  105.     /**
  106.      * Creates a new object of this class.
  107.      *
  108.      * @param ezcAuthenticationCredentials $credentials Authentication credentials
  109.      * @param ezcAuthenticationOptions $options Options for this class
  110.      */
  111.     public function __constructezcAuthenticationCredentials $credentialsezcAuthenticationOptions $options null )
  112.     {
  113.         $this->credentials $credentials;
  114.         $this->status new ezcAuthenticationStatus();
  115.         $this->options = $options === null new ezcAuthenticationOptions($options;
  116.     }
  117.  
  118.     /**
  119.      * Sets the property $name to $value.
  120.      *
  121.      * @throws ezcBasePropertyNotFoundException
  122.      *          if the property $name does not exist
  123.      * @throws ezcBaseValueException
  124.      *          if $value is not correct for the property $name
  125.      * @param string $name The name of the property to set
  126.      * @param mixed $value The new value of the property
  127.      * @ignore
  128.      */
  129.     public function __set$name$value )
  130.     {
  131.         switch $name )
  132.         {
  133.             case 'session':
  134.                 if $value instanceof ezcAuthenticationSession )
  135.                 {
  136.                     $this->properties[$name$value;
  137.                 }
  138.                 else
  139.                 {
  140.                     throw new ezcBaseValueException$name$value'ezcAuthenticationSession' );
  141.                 }
  142.                 break;
  143.  
  144.             case 'status':
  145.                 if $value instanceof ezcAuthenticationStatus )
  146.                 {
  147.                     $this->properties[$name$value;
  148.                 }
  149.                 else
  150.                 {
  151.                     throw new ezcBaseValueException$name$value'ezcAuthenticationStatus' );
  152.                 }
  153.                 break;
  154.  
  155.             case 'credentials':
  156.                 if $value instanceof ezcAuthenticationCredentials )
  157.                 {
  158.                     $this->properties[$name$value;
  159.                 }
  160.                 else
  161.                 {
  162.                     throw new ezcBaseValueException$name$value'ezcAuthenticationCredentials' );
  163.                 }
  164.                 break;
  165.  
  166.             default:
  167.                 throw new ezcBasePropertyNotFoundException$name );
  168.         }
  169.     }
  170.  
  171.     /**
  172.      * Returns the value of the property $name.
  173.      *
  174.      * @throws ezcBasePropertyNotFoundException
  175.      *          if the property $name does not exist
  176.      * @param string $name The name of the property for which to return the value
  177.      * @return mixed 
  178.      * @ignore
  179.      */
  180.     public function __get$name )
  181.     {
  182.         switch $name )
  183.         {
  184.             case 'session':
  185.             case 'status':
  186.             case 'credentials':
  187.                 return $this->properties[$name];
  188.  
  189.             default:
  190.                 throw new ezcBasePropertyNotFoundException$name );
  191.         }
  192.     }
  193.  
  194.     /**
  195.      * Returns true if the property $name is set, otherwise false.
  196.      *
  197.      * @param string $name The name of the property to test if it is set
  198.      * @return bool 
  199.      * @ignore
  200.      */
  201.     public function __isset$name )
  202.     {
  203.         switch $name )
  204.         {
  205.             case 'session':
  206.             case 'status':
  207.             case 'credentials':
  208.                 return isset$this->properties[$name);
  209.  
  210.             default:
  211.                 return false;
  212.         }
  213.     }
  214.  
  215.     /**
  216.      * Sets the options of this class to $options.
  217.      *
  218.      * @param ezcAuthenticationOptions $options Options for this class
  219.      */
  220.     public function setOptionsezcAuthenticationOptions $options )
  221.     {
  222.         $this->options = $options;
  223.     }
  224.  
  225.     /**
  226.      * Returns the options of this class.
  227.      *
  228.      * @return ezcAuthenticationOptions 
  229.      */
  230.     public function getOptions()
  231.     {
  232.         return $this->options;
  233.     }
  234.  
  235.     /**
  236.      * Runs through all the filters in the filter list.
  237.      *
  238.      * @return bool 
  239.      */
  240.     public function run()
  241.     {
  242.         $code ezcAuthenticationFilter::STATUS_OK;
  243.  
  244.         $credentials $this->credentials;
  245.  
  246.         if isset$this->session ) )
  247.         {
  248.             $code $this->session->run$credentials );
  249.             $this->status->appendget_class$this->session )$code );
  250.         }
  251.  
  252.         if !isset$this->session || $code === ezcAuthenticationSession::STATUS_EMPTY )
  253.         {
  254.             foreach $this->filters as $filter )
  255.             {
  256.                 $code $filter[0]->run$credentials );
  257.                 if $filter[0instanceof ezcAuthenticationGroupFilter )
  258.                 {
  259.                     $statuses $filter[0]->status->get();
  260.  
  261.                     // append the statuses from the filters in the group to the
  262.                     // status of the Authentication object
  263.                     foreach $statuses as $status )
  264.                     {
  265.                         list$key$value each$status );
  266.                         $this->status->append$key$value );
  267.                     }
  268.                 }
  269.                 else
  270.                 {
  271.                     $this->status->appendget_class$filter[0)$code );
  272.                 }
  273.  
  274.                 if ( ( $filter[1=== true && $code !== ezcAuthenticationFilter::STATUS_OK ) )
  275.                 {
  276.                     return false;
  277.                 }
  278.  
  279.                 if $filter[1=== true && $code === ezcAuthenticationFilter::STATUS_OK )
  280.                 {
  281.                     break;
  282.                 }
  283.             }
  284.         }
  285.         elseif $code === ezcAuthenticationSession::STATUS_EXPIRED )
  286.         {
  287.             return false;
  288.         }
  289.  
  290.         if $code !== ezcAuthenticationFilter::STATUS_OK )
  291.         {
  292.             return false;
  293.         }
  294.  
  295.         if isset$this->session ) )
  296.         {
  297.             $this->session->save$credentials->__toString() );
  298.         }
  299.  
  300.         return true;
  301.     }
  302.  
  303.     /**
  304.      * Adds an authentication filter at the end of the filter list.
  305.      *
  306.      * By specifying the second parameter as true, the authentication process
  307.      * (triggered by calling the run() method) will stop after processing this
  308.      * filter regardless of its success.
  309.      *
  310.      * @param ezcAuthenticationFilter $filter The authentication filter to add
  311.      * @param bool $stop If authentication should continue past this filter
  312.      */
  313.     public function addFilterezcAuthenticationFilter $filter$stop false )
  314.     {
  315.         $this->filters[array$filter$stop );
  316.     }
  317.  
  318.     /**
  319.      * Returns the status of authentication.
  320.      *
  321.      * The format of the returned array is array( array( class => code ) ).
  322.      *
  323.      * Example:
  324.      * <code>
  325.      * array(
  326.      *        array( 'ezcAuthenticationSession' => ezcAuthenticationSession::STATUS_EMPTY ),
  327.      *        array( 'ezcAuthenticationDatabaseFilter' => ezcAuthenticationDatabaseFilter::STATUS_PASSWORD_INCORRECT )
  328.      *      );
  329.      * </code>
  330.      * 
  331.      * @return array(string=>mixed) 
  332.      */
  333.     public function getStatus()
  334.     {
  335.         return $this->status->get();
  336.     }
  337. }
  338. ?>
Documentation generated by phpDocumentor 1.4.3