Show
Ignore:
Timestamp:
02/28/06 12:49:52 (6 years ago)
Author:
haas
Message:

more documentation

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • trunk/trax/vendor/trax/session.php

    r138 r155  
    3030 
    3131/** 
    32  * 
    33  *  @todo document this class 
    34  *  @package PHPonTrax 
     32 *  Keep track of state of the client's session with the server 
     33 * 
     34 *  Since there is no continuous connection between the client and the 
     35 *  web server, there must be some way to carry information forward 
     36 *  from one page to the next.  PHP does this with a global array variable 
     37 *  {@link http://www.php.net/manual/en/reserved.variables.php#reserved.variables.session $_SESSION} 
     38 *  which is automatically restored from an area of the server's hard disk 
     39 *  indicated by the contents of a cookie stored on the client's computer. 
     40 *  This class is a static class with convenience methods for accessing the  
     41 *  contents of $_SESSION. 
     42 *   @tutorial PHPonTrax/Session.cls 
    3543 */ 
    3644class Session { 
    3745 
    38     # Name of the session (used as cookie name). 
     46    /** 
     47     *  Name of the session (used as cookie name). 
     48     */ 
    3949    const TRAX_SESSION_NAME = "TRAXSESSID"; 
    40     # Lifetime in seconds of cookie or, if 0, until browser is restarted. 
     50 
     51    /** 
     52     *  Lifetime in seconds of cookie or, if 0, until browser is restarted. 
     53     */ 
    4154    const TRAX_SESSION_LIFETIME = "0"; 
    42     # After this number of minutes, stored data will be seen as 'garbage' and 
    43     # cleaned up by the garbage collection process. 
     55 
     56    /** 
     57     *  After this number of minutes, stored data will be seen as 
     58     *  'garbage' and cleaned up by the garbage collection process. 
     59     */ 
    4460    const TRAX_SESSION_MAXLIFETIME_MINUTES = "20"; 
    4561 
    46     private static 
    47         # IP Address of client 
    48         $ip = null, 
    49         # User Agent (OS, Browser, etc) of client 
    50         $user_agent = null; 
    51  
    52     public static 
    53         # Session ID 
    54         $id = null; 
    55  
    56     /** 
    57      * 
    58      *  @todo document this method 
     62    /** 
     63     *  IP Address of client 
     64     *  @var string 
     65     */ 
     66    private static $ip = null; 
     67 
     68    /** 
     69     *  User Agent (OS, Browser, etc) of client 
     70     *  @var string 
     71     */ 
     72    private static $user_agent = null; 
     73 
     74    /** 
     75     *  Session ID 
     76     *  @var string 
     77     */ 
     78    public static $id = null; 
     79 
     80    /** 
     81     *  Get a session variable 
     82     * 
     83     *  Fetch the contents from a specified element of 
     84     *  {@link http://www.php.net/manual/en/reserved.variables.php#reserved.variables.session $_SESSION} 
     85     *  @param mixed $key Key to identify one particular session variable 
     86     *                    of potentially many for this session 
     87     *  @return mixed Content of the session variable with the specified 
     88     *                key if the variable exists; otherwise null. 
     89     *  @uses get_hash() 
     90     *  @uses is_valid_host() 
    5991     */ 
    6092    function get($key) { 
    … …  
    6698 
    6799    /** 
    68      * 
    69      *  @todo document this method 
     100     *  Set a session variable 
     101     * 
     102     *  Store a value in a specified element of 
     103     *  {@link http://www.php.net/manual/en/reserved.variables.php#reserved.variables.session $_SESSION} 
     104     *  @param mixed $key Key to identify one particular session variable 
     105     *                    of potentially many for this session 
     106     *  @param string $value Value to store in the session variable 
     107     *                       identified by $key   
     108     *  @uses get_hash() 
     109     *  @uses is_valid_host() 
     110     *   
    70111     */ 
    71112    function set($key, $value) { 
    … …  
    76117 
    77118    /** 
    78      * 
    79      *  @todo document this method 
    80      */ 
    81     function is_valid_host() { 
     119     *  Test whether the user host is as expected for this session 
     120     * 
     121     *  Compare the REMOTE_ADDR and HTTP_USER_AGENT elements of  
     122     *  {@link http://www.php.net/manual/en/reserved.variables.php#reserved.variables.server $_SERVER} 
     123     *  to the expected values for this session. 
     124     *  @uses $ip 
     125     *  @uses is_aol_host() 
     126     *  @uses $user_agent 
     127     *  @return boolean 
     128     *          <ul> 
     129     *            <li>true =>  User host is as expected</li> 
     130     *            <li>false => User host NOT as expected</li> 
     131     *          </ul> 
     132     */ 
     133 
    82134        if(($_SERVER['REMOTE_ADDR'] == self::$ip || self::is_aol_host()) && 
    83135           $_SERVER['HTTP_USER_AGENT'] == self::$user_agent) { 
    … …  
    88140 
    89141    /** 
    90      * 
    91      *  @todo document this method 
     142     *  Test whether the client is an AOL user 
     143     * 
     144     *  Check whether the domain name of the client's IP ends in 
     145     *  "proxy.aol.com" or the client's user agent name includes "AOL" 
     146     *  @return boolean 
     147     *          <ul> 
     148     *            <li>true =>  Client is on AOL</li> 
     149     *            <li>false => Client from some other ISP</li> 
     150     *          </ul> 
    92151     */ 
    93152    function is_aol_host() { 
    … …  
    100159 
    101160    /** 
    102      * 
    103      *  @todo document this method 
     161     *  Get key that uniquely identifies this session 
     162     * 
     163     *  Calculate a unique session key based on the session ID and 
     164     *  user agent, plus the user's IP address if not on AOL. 
     165     *  @uses is_aol_host() 
     166     *  @uses md5() 
     167     *  @uses session_id() 
    104168     */ 
    105169    function get_hash() { 
    … …  
    112176 
    113177    /** 
    114      * 
    115      *  @todo document this method 
     178     *  Start or continue a session 
     179     * 
     180     *  @uses ini_set() 
     181     *  @uses $ip 
     182     *  @uses is_valid_host() 
     183     *  @uses session_id() 
     184     *  @uses session_start() 
     185     *  @uses $user_agent 
    116186     */ 
    117187    function start() { 
    … …  
    132202        self::$user_agent = $_SERVER['HTTP_USER_AGENT']; 
    133203 
    134         if(self::is_valid_host() && $_REQUEST['sess_id']) { 
     204        if(self::is_valid_host() && array_key_exists('sess_id',$_REQUEST)) { 
    135205            session_id($_REQUEST['sess_id']); 
    136206        } 
    … …  
    142212 
    143213    /** 
    144      * 
    145      *  @todo document this method 
     214     *  Destroy the user's session 
     215     * 
     216     *  Destroy all data registered to a session 
     217     * 
     218     *  @uses session_destroy() 
    146219     */ 
    147220    function destory_session() { 
    … …  
    150223 
    151224    /** 
    152      * 
    153      *  @todo document this method 
     225     *  Free all session variables currently registered 
     226     * 
     227     *  @uses get_hash() 
     228     *  @uses session_unset() 
    154229     */ 
    155230    function unset_session() { 
    … …  
    158233 
    159234    /** 
    160      * 
    161      *  @todo document this method 
     235     *  Unset a session variable 
     236     * 
     237     *  Unset the variable in  
     238     *  {@link http://www.php.net/manual/en/reserved.variables.php#reserved.variables.session $_SESSION} 
     239     *  identified by key $key 
     240     *  @uses get_hash() 
     241     *  @uses is_valid_host() 
    162242     */ 
    163243    function unset_var($key) { 
    … …  
    168248 
    169249    /** 
    170      * 
    171      *  @todo document this method 
     250     *  Test whether a session variable is defined in $_SESSION 
     251     * 
     252     *  Check the  
     253     *  {@link http://www.php.net/manual/en/reserved.variables.php#reserved.variables.session $_SESSION} 
     254     *  array for the existance of a variable identified by $key 
     255     *  @param mixed $key Key to identify one particular session variable 
     256     *                    of potentially many for this session 
     257     *  @return boolean 
     258     *          <ul> 
     259     *            <li>true =>  The specified session variable is 
     260     *                         defined.</li> 
     261     *            <li>false => The specified session variable is 
     262     *                         not defined.</li> 
     263     *          </ul> 
     264     *  @uses get_hash() 
     265     *  @uses is_valid_host() 
    172266     */ 
    173267    function isset_var($key) { 
    … …  
    181275 
    182276    /** 
    183      * 
    184      *  @todo document this method 
     277     *  Test whether there is a flash message to be shown 
     278     * 
     279     *  Check whether the 
     280     *  {@link http://www.php.net/manual/en/reserved.variables.php#reserved.variables.session $_SESSION} 
     281     *  array for this session contains a 
     282     *  flash message to be shown to the user. 
     283     *  @param mixed $key Key to identify one particular flash message 
     284     *                    of potentially many for this session 
     285     *  @return boolean 
     286     *          <ul> 
     287     *            <li>true =>  A flash message is present</li> 
     288     *            <li>false => No flash message is present</li> 
     289     *          </ul> 
     290     *  @uses get_hash() 
     291     *  @uses is_valid_host() 
    185292     */ 
    186293    function isset_flash($key) { 
    … …  
    194301 
    195302    /** 
    196      * 
    197      *  @todo document this method 
     303     *  Get or set a flash message 
     304     * 
     305     *  A flash message is a message that will appear prominently on 
     306     *  the next screen to be sent to the user. Flash 
     307     *  messages are intended to be shown to the user once then erased.  
     308     *  They are stored in the 
     309     *  {@link http://www.php.net/manual/en/reserved.variables.php#reserved.variables.session $_SESSION} 
     310     *  array for the user's session. 
     311     * 
     312     *  @param mixed $key Key to identify one particular flash message 
     313     *                    of potentially many for this session 
     314     *  @param string $value Content of the flash message if present 
     315     *  @return mixed Content of the flash message with the specified 
     316     *                key if $value is null; otherwise null. 
     317     *  @uses get_hash() 
     318     *  @uses is_valid_host() 
    198319     */ 
    199320    function flash($key, $value = null) { 
    … …  
    210331} 
    211332 
     333// -- set Emacs parameters -- 
     334// Local variables: 
     335// tab-width: 4 
     336// c-basic-offset: 4 
     337// c-hanging-comment-ender-p: nil 
     338// indent-tabs-mode: nil 
     339// End: 
    212340?>