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