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

Source for file authentication_session.php

Documentation is available at authentication_session.php

  1. <?php
  2. /**
  3.  * File containing the ezcAuthenticationSession 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.  * Support for session authentication and saving of authentication information
  30.  * between requests.
  31.  *
  32.  * Contains the methods:
  33.  * - start - starts the session, calling the PHP function session_start()
  34.  * - load - returns the information stored in the session key ezcAuth_id
  35.  * - save - saves information in the session key ezcAuth_id and also saves
  36.  *          the current timestamp in the session key ezcAuth_timestamp
  37.  * - destroy - deletes the information stored in the session keys ezcAuth_id
  38.  *             and ezcAuth_timestamp
  39.  * - regenerateId - regenerates the PHPSESSID value
  40.  *
  41.  * Example of use (combined with the Htpasswd filter):
  42.  * <code>
  43.  * // no headers should be sent before calling $session->start()
  44.  * $session = new ezcAuthenticationSession();
  45.  * $session->start();
  46.  *
  47.  * // retrieve the POST request information
  48.  * $user = isset( $_POST['user'] ) ? $_POST['user'] : $session->load();
  49.  * $password = isset( $_POST['password'] ) ? $_POST['password'] : null;
  50.  * $credentials = new ezcAuthenticationPasswordCredentials( $user, $password );
  51.  * $authentication = new ezcAuthentication( $credentials );
  52.  * $authentication->session = $session;
  53.  * $authentication->addFilter( new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd' ) );
  54.  * // add other filters if needed
  55.  * if ( !$authentication->run() )
  56.  * {
  57.  *     // authentication did not succeed, so inform the user
  58.  *     $status = $authentication->getStatus();
  59.  *     $err = array(
  60.  *             'ezcAuthenticationHtpasswdFilter' => array(
  61.  *                 ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
  62.  *                 ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
  63.  *                 ),
  64.  *             'ezcAuthenticationSession' => array(
  65.  *                 ezcAuthenticationSession::STATUS_EMPTY => '',
  66.  *                 ezcAuthenticationSession::STATUS_EXPIRED => 'Session expired'
  67.  *                 )
  68.  *             );
  69.  *     foreach ( $status as $line )
  70.  *     {
  71.  *         list( $key, $value ) = each( $line );
  72.  *         echo $err[$key][$value] . "\n";
  73.  *     }
  74.  * }
  75.  * else
  76.  * {
  77.  *     // authentication succeeded, so allow the user to see his content
  78.  * }
  79.  * </code>
  80.  *
  81.  * See {@link ezcAuthenticationSessionOptions} for options you can set to
  82.  * session objects.
  83.  *
  84.  * @package Authentication
  85.  * @version //autogen//
  86.  * @mainclass
  87.  */
  88. {
  89.     /**
  90.      * Successful authentication; normal behaviour is to skip the other filters.
  91.      *
  92.      * This should be the same value as ezcAuthenticationFilter::STATUS_OK.
  93.      */
  94.     const STATUS_OK 0;
  95.  
  96.     /**
  97.      * The session is empty; normal behaviour is to continue with the other filters.
  98.      */
  99.     const STATUS_EMPTY 1;
  100.  
  101.     /**
  102.      * The session expired; normal behaviour is to regenerate the session ID.
  103.      */
  104.     const STATUS_EXPIRED 2;
  105.  
  106.     /**
  107.      * Options for authentication filters.
  108.      * 
  109.      * @var ezcAuthenticationFilterOptions 
  110.      */
  111.     protected $options;
  112.  
  113.     /**
  114.      * Creates a new object of this class.
  115.      *
  116.      * @param ezcAuthenticationSessionOptions $options Options for this class
  117.      */
  118.     public function __constructezcAuthenticationSessionOptions $options null )
  119.     {
  120.         $this->options = $options === null new ezcAuthenticationSessionOptions($options;
  121.     }
  122.  
  123.     /**
  124.      * Runs through the session and returns a status code when finished.
  125.      *
  126.      * @param ezcAuthenticationCredentials $credentials Authentication credentials
  127.      * @return int 
  128.      */
  129.     public function run$credentials )
  130.     {
  131.         $this->start();
  132.         if isset$_SESSION[$this->options->timestampKey&& 
  133.              time($_SESSION[$this->options->timestampKey>= $this->options->validity
  134.            )
  135.         {
  136.             $this->destroy();
  137.             $this->regenerateId();
  138.             return self::STATUS_EXPIRED;
  139.         }
  140.         if $this->load(!== null )
  141.         {
  142.             return self::STATUS_OK;
  143.         }
  144.         return self::STATUS_EMPTY;
  145.     }
  146.  
  147.     /**
  148.      * Runs through the session and returns true if the session is correct.
  149.      *
  150.      * When using the session, it is often desirable to take advantage of the
  151.      * fact that the authenticated state of the user is kept in the session and
  152.      * not create and initialize the other filters (which might slow things
  153.      * down on every request).
  154.      *
  155.      * The application can be structured like this:
  156.      * <code>
  157.      * $session = new ezcAuthenticationSession();
  158.      * $session->start();
  159.      *
  160.      * $credentials = new ezcAuthenticationPasswordCredentials( $user, $pass );
  161.      *
  162.      * $authenticated = false;
  163.      * if ( !$session->isValid( $credentials ) )
  164.      * {
  165.      *     // create the authentication object
  166.      *     $authentication = new ezcAuthentication( $credentials );
  167.      *     $authentication->session = $session;
  168.      *
  169.      *     // create filters and add them to the authentication object
  170.      *     $authentication->addFilter( new ezcAuthenticationOpenidFilter() );
  171.      *
  172.      *     // run the authentication object
  173.      *     if ( !$authentication->run() )
  174.      *     {
  175.      *         $status = $authentication->getStatus();
  176.      *         // build an error message based on $status
  177.      *     }
  178.      *     else
  179.      *     {
  180.      *         $authenticated = true;
  181.      *     }
  182.      * }
  183.      * else
  184.      * {
  185.      *     $authenticated = true;
  186.      * }
  187.      *
  188.      * if ( $authenticated )
  189.      * {
  190.      *     // the authentication succeeded and the user can see his content
  191.      * }
  192.      * else
  193.      * {
  194.      *     // inform the user that the authentication failed (with the error
  195.      *     // message that was created earlier)
  196.      * }
  197.      * </code>
  198.      *
  199.      * In this way, the creation and initialization of the authentication
  200.      * filters is not performed if the credentials are stored in the session.
  201.      *
  202.      * @param ezcAuthenticationCredentials $credentials Authentication credentials
  203.      * @return bool 
  204.      */
  205.     public function isValid$credentials )
  206.     {
  207.         return $this->run$credentials === self::STATUS_OK );
  208.     }
  209.  
  210.     /**
  211.      * Starts the session.
  212.      *
  213.      * This function must be called before sending any headers to the client.
  214.      */
  215.     public function start()
  216.     {
  217.         if session_id(=== '' && PHP_SAPI !== 'cli' )
  218.         {
  219.             session_start();
  220.         }
  221.     }
  222.  
  223.     /**
  224.      * Loads the authenticated username from the session or null if it doesn't exist.
  225.      *
  226.      * @return string 
  227.      */
  228.     public function load()
  229.     {
  230.         return isset$_SESSION[$this->options->idKey$_SESSION[$this->options->idKey:
  231.                                                                 null;
  232.     }
  233.  
  234.     /**
  235.      * Saves the authenticated username and the current timestamp in the session
  236.      * variables.
  237.      *
  238.      * @param string $data Information to save in the session, usually username
  239.      */
  240.     public function save$data )
  241.     {
  242.         $_SESSION[$this->options->idKey$data;
  243.         $_SESSION[$this->options->timestampKeytime();
  244.     }
  245.  
  246.     /**
  247.      * Removes the variables used by this class from the session variables.
  248.      */
  249.     public function destroy()
  250.     {
  251.         unset$_SESSION[$this->options->idKey);
  252.         unset$_SESSION[$this->options->timestampKey);
  253.     }
  254.     
  255.     /**
  256.      * Regenerates the session ID.
  257.      */
  258.     public function regenerateId()
  259.     {
  260.         if !headers_sent() )
  261.         {
  262.             // ???? seems that PHPSESSID is not regenerated if session is destroyed first????
  263.             // session_destroy();
  264.             session_regenerate_id();
  265.         }
  266.     }
  267.  
  268.     /**
  269.      * Sets the options of this class to $options.
  270.      *
  271.      * @param ezcAuthenticationSessionOptions $options Options for this class
  272.      */
  273.     public function setOptionsezcAuthenticationSessionOptions $options )
  274.     {
  275.         $this->options = $options;
  276.     }
  277.  
  278.     /**
  279.      * Returns the options of this class.
  280.      *
  281.      * @return ezcAuthenticationSessionOptions 
  282.      */
  283.     public function getOptions()
  284.     {
  285.         return $this->options;
  286.     }
  287. }
  288. ?>
Documentation generated by phpDocumentor 1.4.3