[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
   4  
   5  /**
   6   * Class for managing HTTP sessions
   7   *
   8   * Provides access to session-state values as well as session-level
   9   * settings and lifetime management methods.
  10   * Based on the standart PHP session handling mechanism
  11   * it provides for you more advanced features such as
  12   * database container, idle and expire timeouts, etc.
  13   *
  14   * PHP version 4
  15   *
  16   * LICENSE: This source file is subject to version 3.0 of the PHP license
  17   * that is available through the world-wide-web at the following URI:
  18   * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
  19   * the PHP License and are unable to obtain it through the web, please
  20   * send a note to [email protected] so we can mail you a copy immediately.
  21   *
  22   * @category  HTTP
  23   * @package   HTTP_Session
  24   * @author    David Costa <[email protected]>
  25   * @author    Michael Metz <[email protected]>
  26   * @author    Stefan Neufeind <[email protected]>
  27   * @author    Torsten Roehr <[email protected]>
  28   * @copyright 1997-2005 The PHP Group
  29   * @license   http://www.php.net/license/3_0.txt  PHP License 3.0
  30   * @version   CVS: $Id: Session.php,v 1.15 2007/07/14 12:11:54 troehr Exp $
  31   * @link      http://pear.php.net/package/HTTP_Session
  32   * @since     File available since Release 0.4.0
  33   */
  34  
  35  // @const HTTP_SESSION_STARTED - The session was started with the current request
  36  define("HTTP_SESSION_STARTED", 1);
  37  // @const HTTP_SESSION_STARTED - No new session was started with the current request
  38  define("HTTP_SESSION_CONTINUED", 2);
  39  
  40  /**
  41   * Class for managing HTTP sessions
  42   *
  43   * Provides access to session-state values as well as session-level
  44   * settings and lifetime management methods.
  45   * Based on the standart PHP session handling mechanism
  46   * it provides for you more advanced features such as
  47   * database container, idle and expire timeouts, etc.
  48   *
  49   * Example 1:
  50   *
  51   * <code>
  52   * // Setting some options and detecting of a new session
  53   * HTTP_Session::setCookieless(false);
  54   * HTTP_Session::start('MySessionID');
  55   * HTTP_Session::set('variable', 'Tet string');
  56   * if (HTTP_Session::isNew()) {
  57   *     echo('new session was created with the current request');
  58   *     $visitors++; // Increase visitors count
  59   * }
  60   *
  61   * //HTTP_Session::regenerateId();
  62   * </code>
  63   *
  64   * Example 2:
  65   *
  66   * <code>
  67   * // Using database container
  68   * HTTP_Session::setContainer('DB');
  69   * HTTP_Session::start();
  70   * </code>
  71   *
  72   * Example 3:
  73   *
  74   * <code>
  75   * // Setting timeouts
  76   * HTTP_Session::start();
  77   * HTTP_Session::setExpire(time() + 60 * 60); // expires in one hour
  78   * HTTP_Session::setIdle(time()+ 10 * 60);    // idles in ten minutes
  79   * if (HTTP_Session::isExpired()) {
  80   *     // expired
  81   *     echo('Your session is expired!');
  82   *     HTTP_Session::destroy();
  83   * }
  84   * if (HTTP_Session::isIdle()) {
  85   *     // idle
  86   *     echo('You've been idle for too long!');
  87   *     HTTP_Session::destroy();
  88   * }
  89   * HTTP_Session::updateIdle();
  90   * </code>
  91   *
  92   * @category  HTTP
  93   * @package   HTTP_Session
  94   * @author    David Costa <[email protected]>
  95   * @author    Michael Metz <[email protected]>
  96   * @author    Stefan Neufeind <[email protected]>
  97   * @author    Torsten Roehr <[email protected]>
  98   * @copyright 1997-2005 The PHP Group
  99   * @license   http://www.php.net/license/3_0.txt  PHP License 3.0
 100   * @version   Release: @package_version@
 101   * @link      http://pear.php.net/package/HTTP_Session
 102   * @since     Class available since Release 0.4.0
 103   */
 104  class HTTP_Session
 105  {
 106      /**
 107       * Sets user-defined session storage functions
 108       *
 109       * Sets the user-defined session storage functions which are used
 110       * for storing and retrieving data associated with a session.
 111       * This is most useful when a storage method other than
 112       * those supplied by PHP sessions is preferred.
 113       * i.e. Storing the session data in a local database.
 114       *
 115       * @param string $container         Container name
 116       * @param array  $container_options Container options
 117       *
 118       * @static
 119       * @access public
 120       * @return void
 121       * @see    session_set_save_handler()
 122       */
 123      function setContainer($container, $container_options = null)
 124      {
 125          $container_class     = 'HTTP_Session_Container_' . $container;
 126          $container_classfile = 'HTTP/Session/Container/' . $container . '.php';
 127  
 128          include_once $container_classfile;
 129          $container = new $container_class($container_options);
 130  
 131          $container->set();
 132      }
 133  
 134      /**
 135       * Initializes session data
 136       *
 137       * Creates a session (or resumes the current one
 138       * based on the session id being passed
 139       * via a GET variable or a cookie).
 140       * You can provide your own name and/or id for a session.
 141       *
 142       * @param string $name string Name of a session, default is 'SessionID'
 143       * @param string $id   string Id of a session which will be used
 144       *                            only when the session is new
 145       *
 146       * @static
 147       * @access public
 148       * @return void
 149       * @see    session_name()
 150       * @see    session_id()
 151       * @see    session_start()
 152       */
 153      function start($name = 'SessionID', $id = null)
 154      {
 155          HTTP_Session::name($name);
 156          if ($id) {
 157              HTTP_Session::id($id);
 158          } elseif (is_null(HTTP_Session::detectID())) {
 159              HTTP_Session::id($id ? $id : uniqid(dechex(rand())));
 160          }
 161          session_start();
 162          if (!isset($_SESSION['__HTTP_Session_Info'])) {
 163              $_SESSION['__HTTP_Session_Info'] = HTTP_SESSION_STARTED;
 164          } else {
 165              $_SESSION['__HTTP_Session_Info'] = HTTP_SESSION_CONTINUED;
 166          }
 167      }
 168  
 169      /**
 170       * Writes session data and ends session
 171       *
 172       * Session data is usually stored after your script
 173       * terminated without the need to call HTTP_Session::stop(),
 174       * but as session data is locked to prevent concurrent
 175       * writes only one script may operate on a session at any time.
 176       * When using framesets together with sessions you will
 177       * experience the frames loading one by one due to this
 178       * locking. You can reduce the time needed to load all the
 179       * frames by ending the session as soon as all changes
 180       * to session variables are done.
 181       *
 182       * @static
 183       * @access public
 184       * @return void
 185       * @see    session_write_close()
 186       */
 187      function pause()
 188      {
 189          session_write_close();
 190      }
 191  
 192      /**
 193       * Frees all session variables and destroys all data
 194       * registered to a session
 195       *
 196       * This method resets the $_SESSION variable and
 197       * destroys all of the data associated
 198       * with the current session in its storage (file or DB).
 199       * It forces new session to be started after this method
 200       * is called. It does not unset the session cookie.
 201       *
 202       * @static
 203       * @access public
 204       * @return void
 205       * @see    session_unset()
 206       * @see    session_destroy()
 207       */
 208      function destroy()
 209      {
 210          session_unset();
 211          session_destroy();
 212  
 213          // set session handlers again to avoid fatal error in case
 214          // HTTP_Session::start() will be called afterwards
 215          if (isset($GLOBALS['HTTP_Session_Container']) &&
 216              is_a($GLOBALS['HTTP_Session_Container'], 'HTTP_Session_Container')) {
 217              $GLOBALS['HTTP_Session_Container']->set();
 218          }
 219      }
 220  
 221      /**
 222       * Calls session_regenerate_id() if available
 223       *
 224       * @param bool $deleteOldSessionData Whether to delete data of old session
 225       *
 226       * @static
 227       * @access public
 228       * @return bool
 229       */
 230      function regenerateId($deleteOldSessionData = false)
 231      {
 232          if (function_exists('session_regenerate_id')) {
 233              return session_regenerate_id($deleteOldSessionData);
 234  
 235              // emulate session_regenerate_id()
 236          } else {
 237  
 238              do {
 239                  $newId = uniqid(dechex(rand()));
 240              } while ($newId === session_id());
 241  
 242              if ($deleteOldSessionData) {
 243                  session_unset();
 244              }
 245  
 246              session_id($newId);
 247  
 248              return true;
 249          }
 250      }
 251  
 252      /**
 253       * This function copies session data of specified id to specified table
 254       *
 255       * @param string $targetTable Table to replicate data to
 256       * @param string $id          ID of the session
 257       *
 258       * @static
 259       * @access public
 260       * @return bool
 261       */
 262      function replicate($targetTable, $id = null)
 263      {
 264          return $GLOBALS['HTTP_Session_Container']->replicate($targetTable, $id);
 265      }
 266  
 267      /**
 268       * Free all session variables
 269       *
 270       * @todo   TODO Save expire and idle timestamps?
 271       * @static
 272       * @access public
 273       * @return void
 274       */
 275      function clear()
 276      {
 277          $info = $_SESSION['__HTTP_Session_Info'];
 278          session_unset();
 279          $_SESSION['__HTTP_Session_Info'] = $info;
 280      }
 281  
 282      /**
 283       * Tries to find any session id in $_GET, $_POST or $_COOKIE
 284       *
 285       * @static
 286       * @access private
 287       * @return string Session ID (if exists) or null
 288       */
 289      function detectID()
 290      {
 291          if (HTTP_Session::useCookies()) {
 292              if (isset($_COOKIE[HTTP_Session::name()])) {
 293                  return $_COOKIE[HTTP_Session::name()];
 294              }
 295          } else {
 296              if (isset($_GET[HTTP_Session::name()])) {
 297                  return $_GET[HTTP_Session::name()];
 298              }
 299              if (isset($_POST[HTTP_Session::name()])) {
 300                  return $_POST[HTTP_Session::name()];
 301              }
 302          }
 303          return null;
 304      }
 305  
 306      /**
 307       * Sets new name of a session
 308       *
 309       * @param string $name New name of a session
 310       *
 311       * @static
 312       * @access public
 313       * @return string Previous name of a session
 314       * @see    session_name()
 315       */
 316      function name($name = null)
 317      {
 318          return isset($name) ? session_name($name) : session_name();
 319      }
 320  
 321      /**
 322       * Sets new ID of a session
 323       *
 324       * @param string $id New ID of a session
 325       *
 326       * @static
 327       * @access public
 328       * @return string Previous ID of a session
 329       * @see    session_id()
 330       */
 331      function id($id = null)
 332      {
 333          return isset($id) ? session_id($id) : session_id();
 334      }
 335  
 336      /**
 337       * Sets the maximum expire time
 338       *
 339       * @param integer $time Time in seconds
 340       * @param bool    $add  Add time to current expire time or not
 341       *
 342       * @static
 343       * @access public
 344       * @return void
 345       */
 346      function setExpire($time, $add = false)
 347      {
 348          if ($add) {
 349              if (!isset($_SESSION['__HTTP_Session_Expire_TS'])) {
 350                  $_SESSION['__HTTP_Session_Expire_TS'] = time() + $time;
 351              }
 352  
 353              // update session.gc_maxlifetime
 354              $currentGcMaxLifetime = HTTP_Session::setGcMaxLifetime(null);
 355              HTTP_Session::setGcMaxLifetime($currentGcMaxLifetime + $time);
 356  
 357          } elseif (!isset($_SESSION['__HTTP_Session_Expire_TS'])) {
 358              $_SESSION['__HTTP_Session_Expire_TS'] = $time;
 359          }
 360      }
 361  
 362      /**
 363       * Sets the maximum idle time
 364       *
 365       * Sets the time-out period allowed
 366       * between requests before the session-state
 367       * provider terminates the session.
 368       *
 369       * @param int  $time Time in seconds
 370       * @param bool $add  Add time to current maximum idle time or not
 371       *
 372       * @static
 373       * @access public
 374       * @return void
 375       */
 376      function setIdle($time, $add = false)
 377      {
 378          if ($add) {
 379              $_SESSION['__HTTP_Session_Idle'] = $time;
 380          } else {
 381              // substract time again because it doesn't make any sense to provide
 382              // the idle time as a timestamp
 383              // keep $add functionality to provide BC
 384              $_SESSION['__HTTP_Session_Idle'] = $time - time();
 385          }
 386      }
 387  
 388      /**
 389       * Returns the time up to the session is valid
 390       *
 391       * @static
 392       * @access public
 393       * @return integer Time when the session idles
 394       */
 395      function sessionValidThru()
 396      {
 397          if (!isset($_SESSION['__HTTP_Session_Idle_TS']) ||
 398              !isset($_SESSION['__HTTP_Session_Idle'])) {
 399              return 0;
 400          } else {
 401              return $_SESSION['__HTTP_Session_Idle_TS'] +
 402                     $_SESSION['__HTTP_Session_Idle'];
 403          }
 404      }
 405  
 406      /**
 407       * Check if session is expired
 408       *
 409       * @static
 410       * @access public
 411       * @return bool
 412       */
 413      function isExpired()
 414      {
 415          if (isset($_SESSION['__HTTP_Session_Expire_TS']) &&
 416              $_SESSION['__HTTP_Session_Expire_TS'] < time()) {
 417              return true;
 418          } else {
 419              return false;
 420          }
 421      }
 422  
 423      /**
 424       * Check if session is idle
 425       *
 426       * @static
 427       * @access public
 428       * @return bool
 429       */
 430      function isIdle()
 431      {
 432          if (isset($_SESSION['__HTTP_Session_Idle_TS']) &&
 433              (($_SESSION['__HTTP_Session_Idle_TS'] +
 434                $_SESSION['__HTTP_Session_Idle']) < time())) {
 435              return true;
 436          } else {
 437              return false;
 438          }
 439      }
 440  
 441      /**
 442       * Updates the idletime
 443       *
 444       * @static
 445       * @access public
 446       * @return void
 447       */
 448      function updateIdle()
 449      {
 450          $_SESSION['__HTTP_Session_Idle_TS'] = time();
 451      }
 452  
 453      /**
 454       * If optional parameter is specified it indicates
 455       * whether the module will use cookies to store
 456       * the session id on the client side
 457       *
 458       * It returns the previous value of this property
 459       *
 460       * @param bool $useCookies If specified it will replace the previous value
 461       *                         of this property
 462       *
 463       * @static
 464       * @access public
 465       *
 466       * @return bool The previous value of the property
 467       */
 468      function useCookies($useCookies = null)
 469      {
 470          $return = ini_get('session.use_cookies') ? true : false;
 471          if (isset($useCookies)) {
 472              ini_set('session.use_cookies', $useCookies ? 1 : 0);
 473          }
 474          return $return;
 475      }
 476  
 477      /**
 478       * Gets a value indicating whether the session
 479       * was created with the current request
 480       *
 481       * You MUST call this method only after you have started
 482       * the session with the HTTP_Session::start() method.
 483       *
 484       * @static
 485       * @access public
 486       * @return bool   True if the session was created
 487       *                with the current request, false otherwise
 488       */
 489      function isNew()
 490      {
 491          // The best way to check if a session is new is to check
 492          // for existence of a session data storage
 493          // with the current session id, but this is impossible
 494          // with the default PHP module wich is 'files'.
 495          // So we need to emulate it.
 496          return !isset($_SESSION['__HTTP_Session_Info']) ||
 497              $_SESSION['__HTTP_Session_Info'] == HTTP_SESSION_STARTED;
 498      }
 499  
 500      /**
 501       * Register variable with the current session
 502       *
 503       * @param string $name Name of a global variable
 504       *
 505       * @deprecated Use set()/setRef() instead
 506       *
 507       * @static
 508       * @access public
 509       * @return bool
 510       * @see    session_register()
 511       */
 512      function register($name)
 513      {
 514          return session_register($name);
 515      }
 516  
 517      /**
 518       * Unregister a variable from the current session
 519       *
 520       * @param string $name Name of a global variable
 521       *
 522       * @deprecated Use get()/getRef() instead
 523       *
 524       * @static
 525       * @access public
 526       * @return bool
 527       * @see    session_unregister()
 528       */
 529      function unregister($name)
 530      {
 531          return session_unregister($name);
 532      }
 533  
 534      /**
 535       * Checks if a session variable is registered
 536       *
 537       * @param string $name Variable name
 538       *
 539       * @deprecated Use is_set() instead
 540       *
 541       * @static
 542       * @access public
 543       * @return bool
 544       */
 545      function registered($name)
 546      {
 547          return session_is_registered($name);
 548      }
 549  
 550      /**
 551       * Returns session variable
 552       *
 553       * @param string $name    Name of a variable
 554       * @param mixed  $default Default value of a variable if not set
 555       *
 556       * @static
 557       * @access public
 558       * @return mixed  Value of a variable
 559       */
 560      function get($name, $default = null)
 561      {
 562          if (!isset($_SESSION[$name]) && isset($default)) {
 563              $_SESSION[$name] = $default;
 564          }
 565          $return = (isset($_SESSION[$name])) ? $_SESSION[$name] : null;
 566          return $return;
 567      }
 568  
 569      /**
 570       * Returns session variable by reference
 571       *
 572       * @param string $name Name of a variable
 573       *
 574       * @static
 575       * @access public
 576       * @return mixed  Value of a variable
 577       */
 578      function &getRef($name)
 579      {
 580          if (isset($_SESSION[$name])) {
 581              $return =& $_SESSION[$name];
 582          } else {
 583              $return = null;
 584          }
 585  
 586          return $return;
 587      }
 588  
 589      /**
 590       * Sets session variable
 591       *
 592       * @param string $name  Name of a variable
 593       * @param mixed  $value Value of a variable
 594       *
 595       * @static
 596       * @access public
 597       * @return mixed  Old value of a variable
 598       */
 599      function set($name, $value)
 600      {
 601          $return = (isset($_SESSION[$name])) ? $_SESSION[$name] : null;
 602          if (null === $value) {
 603              unset($_SESSION[$name]);
 604          } else {
 605              $_SESSION[$name] = $value;
 606          }
 607          return $return;
 608      }
 609  
 610      /**
 611       * Sets session variable by reference
 612       *
 613       * @param string $name  Name of a variable
 614       * @param mixed  $value Value of a variable
 615       *
 616       * @static
 617       * @access public
 618       * @return mixed  Old value of a variable
 619       */
 620      function setRef($name, &$value)
 621      {
 622          $return = (isset($_SESSION[$name])) ? $_SESSION[$name] : null;
 623  
 624          $_SESSION[$name] =& $value;
 625  
 626          return $return;
 627      }
 628  
 629      /**
 630       * Checks if a session variable is set
 631       *
 632       * @param string $name Variable name
 633       *
 634       * @static
 635       * @access public
 636       * @return bool
 637       */
 638      function is_set($name)
 639      {
 640          return isset($_SESSION[$name]);
 641      }
 642  
 643      /**
 644       * Returns local variable of a script
 645       *
 646       * Two scripts can have local variables with the same names
 647       *
 648       * @param string $name    Name of a variable
 649       * @param mixed  $default Default value of a variable if not set
 650       *
 651       * @static
 652       * @access public
 653       * @return mixed  Value of a local variable
 654       */
 655      function &getLocal($name, $default = null)
 656      {
 657          $local = md5(HTTP_Session::localName());
 658          if (!isset($_SESSION[$local]) || !is_array($_SESSION[$local])) {
 659              $_SESSION[$local] = array();
 660          }
 661          if (!isset($_SESSION[$local][$name]) && isset($default)) {
 662              $_SESSION[$local][$name] = $default;
 663          }
 664          return $_SESSION[$local][$name];
 665      }
 666  
 667      /**
 668       * Sets local variable of a script.
 669       * Two scripts can have local variables with the same names.
 670       *
 671       * @param string $name  Name of a local variable
 672       * @param mixed  $value Value of a local variable
 673       *
 674       * @static
 675       * @access public
 676       * @return mixed  Old value of a local variable
 677       */
 678      function setLocal($name, $value)
 679      {
 680          $local = md5(HTTP_Session::localName());
 681          if (!isset($_SESSION[$local]) || !is_array($_SESSION[$local])) {
 682              $_SESSION[$local] = array();
 683          }
 684          $return = (isset($_SESSION[$local][$name])) ? $_SESSION[$local][$name]
 685                                                      : null;
 686  
 687          if (null === $value) {
 688              unset($_SESSION[$local][$name]);
 689          } else {
 690              $_SESSION[$local][$name] = $value;
 691          }
 692          return $return;
 693      }
 694  
 695      /**
 696       * Sets new local name
 697       *
 698       * @param string $name New local name
 699       *
 700       * @static
 701       * @access public
 702       * @return string Previous local name
 703       */
 704      function localName($name = null)
 705      {
 706          $return = (isset($GLOBALS['__HTTP_Session_Localname'])) ? $GLOBALS['__HTTP_Session_Localname']
 707                                                                  : null;
 708  
 709          if (!empty($name)) {
 710              $GLOBALS['__HTTP_Session_Localname'] = $name;
 711          }
 712          return $return;
 713      }
 714  
 715      /**
 716       * Initialize
 717       *
 718       * @static
 719       * @access private
 720       * @return void
 721       */
 722      function _init()
 723      {
 724          // Disable auto-start of a sesion
 725          ini_set('session.auto_start', 0);
 726  
 727          // Set local name equal to the current script name
 728          HTTP_Session::localName($_SERVER['PHP_SELF']);
 729      }
 730  
 731      /**
 732       * If optional parameter is specified it indicates
 733       * whether the session id will automatically be appended to
 734       * all links
 735       *
 736       * It returns the previous value of this property
 737       *
 738       * @param bool $useTransSID If specified it will replace the previous value
 739       *                          of this property
 740       *
 741       * @static
 742       * @access public
 743       * @return bool   The previous value of the property
 744       */
 745      function useTransSID($useTransSID = null)
 746      {
 747          $return = ini_get('session.use_trans_sid') ? true : false;
 748          if (isset($useTransSID)) {
 749              ini_set('session.use_trans_sid', $useTransSID ? 1 : 0);
 750          }
 751          return $return;
 752      }
 753  
 754      /**
 755       * If optional parameter is specified it determines the number of seconds
 756       * after which session data will be seen as 'garbage' and cleaned up
 757       *
 758       * It returns the previous value of this property
 759       *
 760       * @param bool $gcMaxLifetime If specified it will replace the previous value
 761       *                            of this property
 762       *
 763       * @static
 764       * @access public
 765       * @return bool   The previous value of the property
 766       */
 767      function setGcMaxLifetime($gcMaxLifetime = null)
 768      {
 769          $return = ini_get('session.gc_maxlifetime');
 770          if (isset($gcMaxLifetime) && is_int($gcMaxLifetime) && $gcMaxLifetime >= 1) {
 771              ini_set('session.gc_maxlifetime', $gcMaxLifetime);
 772          }
 773          return $return;
 774      }
 775  
 776      /**
 777       * If optional parameter is specified it determines the
 778       * probability that the gc (garbage collection) routine is started
 779       * and session data is cleaned up
 780       *
 781       * It returns the previous value of this property
 782       *
 783       * @param bool $gcProbability If specified it will replace the previous value
 784       *                            of this property
 785       *
 786       * @static
 787       * @access public
 788       * @return bool   The previous value of the property
 789       */
 790      function setGcProbability($gcProbability = null)
 791      {
 792          $return = ini_get('session.gc_probability');
 793          if (isset($gcProbability)  &&
 794              is_int($gcProbability) &&
 795              $gcProbability >= 1    &&
 796              $gcProbability <= 100) {
 797              ini_set('session.gc_probability', $gcProbability);
 798          }
 799          return $return;
 800      }
 801  }
 802  
 803  HTTP_Session::_init();
 804  ?>