tangra logo
   
[ class tree: tangra_lib ] [ index: tangra_lib ] [ all elements ]
 

Source for file vars_manager.class.php

Documentation is available at vars_manager.class.php

  1. <?php
  2. // *** Tangra (Application Framework and Tools for PHP)
  3. //  $Id$
  4. //
  5.  
  6. /**
  7.  * Contains class Vars_Manager
  8.  * @package  tangra_lib
  9.  * @subpackage  core
  10.  */
  11.  
  12. /**
  13.  * Loading exception
  14.  */
  15. require_once(TANGRA_MAIN_DIR.'exceptions/te_var_already_exists.class.php');
  16. /**
  17.  * Loading exception
  18.  */
  19. require_once(TANGRA_MAIN_DIR.'exceptions/te_var_not_exists.class.php');
  20.  
  21.  
  22. /**
  23.  * Container for values that provides unified access.
  24.  *
  25.  * Class Vars_Manager and it's descendants are used to provide container for variables.
  26.  * Objects of class Vars_Manager are intended to be stored in $_SESSION that is way they have garbage_collector() - to clean up old data.
  27.  *
  28.  * @see Session_Vars_Manager, Thread_Vars_Manager
  29.  * @package  tangra_lib
  30.  * @subpackage  core
  31.  */
  32. class Vars_Manager extends Tangra_Class {
  33.     /**
  34.      * Storage for the values
  35.      *
  36.      * @var array simple associative array
  37.      */
  38.     private $vars = array();
  39.  
  40.     /**
  41.      * Holds last access time for each variable
  42.      *
  43.      * @var array 
  44.      */
  45.     private $atimes = array();
  46.  
  47.     /**
  48.      * Maximum life time for the variables. If (time() - $atime) > $gc_maxlifetime variable will be seen as garbage.
  49.      *
  50.      * @var unknown_type 
  51.      */
  52.     private $gc_maxlifetime; // maximum time (in seconds) that var will "live" if not used
  53.  
  54.  
  55.     /**
  56.      * Constructor
  57.      *
  58.      * @param integer $gc_maxlifetime Maximum life time for variables after which will be seen as garbage.
  59.      */
  60.     function __construct($gc_maxlifetime = 1440) {
  61.         tangra_if_not_int_throw_e($gc_maxlifetime);
  62.         $this->gc_maxlifetime = $gc_maxlifetime;
  63.     }
  64.  
  65.  
  66.     /**
  67.      * Registers variable. You have first to register variable before using Vars_Manager::set_var()
  68.      *
  69.      * @param string $var_name 
  70.      * @param boolean $expires - if false variable will be never seen as garbage. Default is true.
  71.      */
  72.     public function register_var($var_name, $expires = false) {
  73.         $this->garbage_collector();
  74.         if (!array_key_exists($var_name, $this->vars)) {
  75.             $this->vars[$var_name] = NULL;
  76.             if ($expires) {
  77.                 $this->atimes[$var_name] = time();
  78.             } else {
  79.                 // 0 means - never expire
  80.                 $this->atimes[$var_name] = 0;
  81.             }
  82.         }
  83.     }
  84.  
  85.  
  86.     /**
  87.      * Adds new variable. Shortcut for register_var() and set_var()
  88.      *
  89.      * @param string $var_name 
  90.      * @param any $value must be a variable not reference. Use temporary variables if needed.
  91.      */
  92.     public function add_var($var_name, &$value) {
  93.         $this->register_var($var_name);
  94.         $this->set_var($var_name, $value);
  95.  
  96.     }
  97.  
  98.  
  99.     /**
  100.      * Sets variable.
  101.      * Variable must be already registered - if not - throws exception.
  102.      *
  103.      * @param string $var_name 
  104.      * @param any $value 
  105.      * @throws  TE_Var_Not_Exists
  106.      */
  107.     public function set_var($var_name, &$value) {
  108.         $this->garbage_collector();
  109.         if (array_key_exists($var_name, $this->vars)) {
  110.             $this->vars[$var_name] = &$value;
  111.             if ($this->atimes[$var_name]) {
  112.                 $this->atimes[$var_name] = time();
  113.             }
  114.         } else {
  115.             throw new TE_Var_Not_Exists($var_name);
  116.         }
  117.     }
  118.  
  119.  
  120.     /**
  121.      * Gets variable as reference. Use this function if you intend to change the value.
  122.      * If variable is not found - throws exception.
  123.      *
  124.      * @param string $var_name 
  125.      * @return any  rvalue is eturned as reference
  126.      * @throws  TE_Var_Not_Exists
  127.      */
  128.     public function &get_var($var_name) {
  129.         $this->garbage_collector();
  130.         if (array_key_exists($var_name, $this->vars)) {
  131.             $ret = &$this->vars[$var_name];
  132.             if ($this->atimes[$var_name]) {
  133.                 $this->atimes[$var_name] = time();
  134.             }
  135.             return $ret;
  136.         } else {
  137.             throw new TE_Var_Not_Exists($var_name);
  138.         }
  139.     }
  140.  
  141.  
  142.     /**
  143.      * Query variable. Similar to {@link get_var}() but returns copy of the variable, not reference. Use this function instead of get_var() if you are not intending to change the value.
  144.      * If variable is not found - throws exception.
  145.      * @param string $var_name 
  146.      * @return any 
  147.      * @throws  TE_Var_Not_Exists
  148.      */
  149.     public function query_var($var_name) {
  150.         $this->garbage_collector();
  151.         if (array_key_exists($var_name, $this->vars)) {
  152.             $ret = $this->vars[$var_name];
  153.             if ($this->atimes[$var_name]) {
  154.                 $this->atimes[$var_name] = time();
  155.             }
  156.             return $ret;
  157.         } else {
  158.             throw new TE_Var_Not_Exists($var_name);
  159.         }
  160.     }
  161.  
  162.  
  163.     /**
  164.      * Removes/unregisters variable.
  165.      * If variable is not found - throws exception.
  166.      * @param string $var_name 
  167.      * @throws  TE_Var_Not_Exists
  168.      */
  169.     public function remove_var($var_name) {
  170.         if (array_key_exists($var_name, $this->vars)) {
  171.             unset($this->vars[$var_name]);
  172.             unset($this->atimes[$var_name]);
  173.         } else {
  174.             throw new TE_Var_Not_Exists($var_name);
  175.         }
  176.     }
  177.  
  178.  
  179.     /**
  180.      * Checks if variable with name provided by $var_name exists.
  181.      *
  182.      * @param string $var_name 
  183.      * @return boolean 
  184.      */
  185.     public function is_var_registered($var_name) {
  186.         $this->garbage_collector();
  187.         return array_key_exists($var_name, $this->vars);
  188.     }
  189.  
  190.  
  191.     /**
  192.      * Collects the garbage.
  193.      * Normally this function is not called directly by the user.
  194.      *
  195.      */
  196.     public function garbage_collector() {
  197.         $time = time();
  198.         foreach($this->atimes as $key => $value) {
  199.             if ($value) { //procces only expirable, e.g. <> 0
  200.                 if (($value + $this->gc_maxlifetime) < $time) {
  201.                     $this->remove_var($key);
  202.                 }
  203.             }
  204.         }
  205.     }
  206. }