[Summary view] [Print] [Text view]

   1  <?php
   2  /*
   3   * Limb PHP Framework
   4   *
   5   * @link http://limb-project.com 
   6   * @copyright  Copyright &copy; 2004-2007 BIT(http://bit-creative.com)
   7   * @license    LGPL http://www.gnu.org/copyleft/lesser.html 
   8   */
   9  lmb_require(dirname(__FILE__) . '/lmbToolkitTools.interface.php');
  10  lmb_require(dirname(__FILE__) . '/lmbRegistry.class.php');
  11  lmb_require(dirname(__FILE__) . '/lmbEmptyToolkitTools.class.php');
  12  lmb_require(dirname(__FILE__) . '/lmbCompositeToolkitTools.class.php');
  13  lmb_require(dirname(__FILE__) . '/lmbCompositeNonItersectingToolkitTools.class.php');
  14  
  15  /**
  16   * Toolkit is an implementation of Dinamic Service Locator pattern
  17   * The idea behind lmbToolkit class is simple:
  18   *  1) lmbToolkit is a Singleton
  19   *  2) lmbToolkit consists of so called tools. Tools is an object of any class that supports {@link lmbToolkitTools} interface
  20   *  3) lmbToolkit redirects all non existing methods via magic __call to tools if these methods were named in $tools :: getToolsSignatures() result.
  21   *  4) lmbToolkit also acts as a registry. You can put any data into toolkit and get them out at any place of your application
  22   * As a result we get an easily accessible object that we can extend with any methods we need.
  23   * We can also replace one tools with others thus we can return to client code completely different results from the same toolkit methods.
  24   * lmbToolkit also supports magic getters and setters. Say you have tools with getVar() method and you call $toolkit->get('var') then tools->getVar() will be actually called
  25   * Example of usage:
  26   * <code>
  27   * lmb_require('limb/net/src/lmbNetTools.class.php');
  28   * lmbToolkit :: merge(new lmbNetTools());
  29   * lmb_require('limb/net/src/toolkit/lmbDbTools.class.php');
  30   * lmbToolkit :: merge(new lmbDbTools());
  31   * // somethere in client code
  32   * $toolkit = lmbToolkit :: instance();
  33   * $toolkit->set('my_var', $value)'
  34   * $request = $toolkit->getRequest(); // supported by lmbNetTools
  35   * $same_request = $toolkit->get('requets'); // will delegate to getRequest()
  36   * $db_connection = $toolkit->getDefaultDbConnection(); // supported by lmbDbTools
  37   * $toolkit->get('my_var'); // returns $value value
  38   * </code>
  39   * @see lmbToolkitTools
  40   * @package toolkit
  41   * @version $Id: lmbToolkit.class.php 5945 2007-06-06 08:31:43Z pachanga $
  42   */
  43  class lmbToolkit
  44  {
  45    /**

  46    * @var lmbToolkitTools Current tools

  47    */
  48    protected $tools;
  49    /**

  50    * @var array Current set of toolkit data

  51    */
  52    protected $properties = array();
  53    /**

  54    * @var array Cached tools signatures that is methods supported by tools

  55    */
  56    protected $tools_signatures = array();
  57    /**

  58    * @var boolean Flag if tools signatures were precached

  59    */
  60    protected $signatures_loaded = false;
  61  
  62    /**

  63    * Sets new tools object and clear signatures cache

  64    * @param lmbToolkitTools

  65    */
  66    protected function setTools($tools)
  67    {
  68      $this->tools = $tools;
  69      $this->tools_signatures = array();
  70      $this->signatures_loaded = false;
  71    }
  72  
  73    /**

  74    * Sets new set of toolkit data

  75    * @param array

  76    */
  77    protected function setProperties($properties)
  78    {
  79      $this->properties = $properties;
  80    }
  81    /**

  82    * Follows Singleton pattern interface

  83    * Returns toolkit instance. Takes instance from {@link lmbRegistry)

  84    * If instance is not initialized yet - creates one with empty tools

  85    * @see lmbRegistry

  86    * @return lmbToolkit The only instance of lmbToolkit class

  87    */
  88    static function instance()
  89    {
  90      self :: _ensureInstance();
  91      return lmbRegistry :: get(__CLASS__);
  92    }
  93  
  94    /**

  95    * Ensures that instance of lmbToolkit class is exists.

  96    * If instance is not initialized yet - creates one with empty tools

  97    * @see lmbRegistry

  98    * @return void

  99    */
 100    static protected function _ensureInstance()
 101    {
 102      $instance = lmbRegistry :: get(__CLASS__);
 103  
 104      if(is_object($instance))
 105        return;
 106  
 107      $instance = new lmbToolkit();
 108      lmbRegistry :: set(__CLASS__, $instance);
 109  
 110      $instance->setTools($tools = new lmbEmptyToolkitTools());
 111  
 112      lmbRegistry :: set('lmbToolkitTools', $tools);
 113      lmbRegistry :: set('lmbToolkitToolsCopy', clone($tools));
 114      lmbRegistry :: set('lmbToolkitProperties', array());
 115    }
 116  
 117    /**

 118    * Fills toolkit instance with suggested tools and registers this tools in {@ling lmbRegisty}

 119    * @see lmbRegistry

 120    * @return lmbToolkit The only instance of lmbToolkit class

 121    */
 122    static function setup($tools)
 123    {
 124      $toolkit = lmbToolkit :: instance();
 125      $toolkit->setTools($tools);
 126  
 127      lmbRegistry :: set('lmbToolkitTools', $tools);
 128      lmbRegistry :: set('lmbToolkitToolsCopy', clone($tools));
 129  
 130      return $toolkit;
 131    }
 132  
 133    /**

 134    * Save current tools object in registry stack and creates a new one using currently saved empty copy of tools object

 135    * @see lmbRegistry :: save()

 136    * @return lmbToolkit The only instance of lmbToolkit class

 137    */
 138    static function save()
 139    {
 140      $toolkit = lmbToolkit :: instance();
 141  
 142      $tools = lmbRegistry :: get('lmbToolkitToolsCopy');
 143      $tools_copy = clone($tools);
 144  
 145      $toolkit->setTools($tools_copy);
 146  
 147      lmbRegistry :: save('lmbToolkitTools');
 148      lmbRegistry :: save('lmbToolkitToolsCopy');
 149  
 150      lmbRegistry :: set('lmbToolkitTools', $tools);
 151      lmbRegistry :: set('lmbToolkitToolsCopy', $tools_copy);
 152  
 153      lmbRegistry :: set('lmbToolkitProperties', $toolkit->properties);
 154      lmbRegistry :: save('lmbToolkitProperties');
 155      $toolkit->setProperties(array());
 156  
 157      return $toolkit;
 158    }
 159  
 160    /**

 161    * Restores previously saved tools object instance from {@link lmbRegistry} stack and sets this tools into toolkit instance

 162    * @return lmbToolkit The only instance of lmbToolkit class

 163    */
 164    static function restore()
 165    {
 166      $toolkit = lmbToolkit :: instance();
 167  
 168      lmbRegistry :: restore('lmbToolkitTools');
 169      lmbRegistry :: restore('lmbToolkitToolsCopy');
 170      lmbRegistry :: restore('lmbToolkitProperties');
 171  
 172      $tools = lmbRegistry :: get('lmbToolkitTools');
 173      $toolkit->setTools($tools);
 174  
 175      $properties = lmbRegistry :: get('lmbToolkitProperties');
 176      $toolkit->setProperties($properties);
 177  
 178      return $toolkit;
 179    }
 180  
 181    /**

 182    * Extends current tools with new tools

 183    * Merges tools together using {@link lmbCompositeNonItersectingToolkitTools} that doesn't allow tools methods intersection

 184    * @see lmbCompositeNonItersectingToolkitTools

 185    * @return lmbToolkit The only instance of lmbToolkit class

 186    */
 187    static function extend($tools)
 188    {
 189      self :: _ensureInstance();
 190  
 191      $tools_copy = lmbRegistry :: get('lmbToolkitToolsCopy');
 192      return self :: setup(new lmbCompositeNonItersectingToolkitTools($tools_copy, $tools));
 193    }
 194  
 195    /**

 196    * Extends current tools with new tools

 197    * Merges tools together using {@link lmbCompositeToolkitTools}

 198    * @see lmbCompositeToolkitTools

 199    * @return lmbToolkit The only instance of lmbToolkit class

 200    */
 201    static function merge($tools)
 202    {
 203      self :: _ensureInstance();
 204  
 205      $tools_copy = lmbRegistry :: get('lmbToolkitToolsCopy');
 206      return self :: setup(new lmbCompositeToolkitTools($tools_copy, $tools));
 207    }
 208  
 209    /**

 210    * Sets variable into toolkit

 211    * Checks if appropriate setter method in tools exists to delegate to

 212    * @return void

 213    */
 214    function set($var, $value)
 215    {
 216      if($method = $this->_mapPropertyToSetMethod($var))
 217        return $this->$method($value);
 218      else
 219        $this->setRaw($var, $value);
 220    }
 221  
 222    /**

 223    * Gets variable from toolkit

 224    * Checks if appropriate getter method in tools exists to delegate to

 225    * @return void

 226    */
 227    function get($var)
 228    {
 229      if($method = $this->_mapPropertyToGetMethod($var))
 230        return $this->$method();
 231      else
 232        return $this->getRaw($var);
 233    }
 234  
 235    /**

 236    * Sets variable from toolkit

 237    * Doesn't check if appropriate setter method in tools exists to delegate to

 238    * @return void

 239    */
 240    function setRaw($var, $value)
 241    {
 242      $this->properties[$var] = $value;
 243    }
 244  
 245    /**

 246    * Gets variable from toolkit

 247    * Doesn't check if appropriate getter method in tools exists to delegate to

 248    * @return void

 249    */
 250    function getRaw($var)
 251    {
 252      if(isset($this->properties[$var]))
 253        return $this->properties[$var];
 254    }
 255  
 256    /**

 257    * Magic caller. Delegates to {@link $tools} if $tools_signatures has required method

 258    * @param string Method name

 259    * @param array Method arguments

 260    * @return mixed

 261    */
 262    function __call($method, $args)
 263    {
 264      $this->_ensureSignatures();
 265  
 266      if(!isset($this->tools_signatures[$method]))
 267        throw new lmbException('toolkit does not support method "' . $method . '" (no such signature)',
 268                                array('method' => $method));
 269  
 270  
 271      return call_user_func_array(array($this->tools_signatures[$method], $method), $args);
 272    }
 273  
 274    /**

 275    * Caches tools signatures. Fills {@link $tools_signatures}.

 276    * @see lmbToolkitTools :: getToolsSignatures()

 277    * @return void

 278    */
 279    protected function _ensureSignatures()
 280    {
 281      if($this->signatures_loaded)
 282        return;
 283  
 284      $this->tools_signatures = $this->tools->getToolsSignatures();
 285      $this->signatures_loaded = true;
 286    }
 287  
 288    protected function _mapPropertyToGetMethod($property)
 289    {
 290      $this->_ensureSignatures();
 291  
 292      $capsed = lmb_camel_case($property);
 293      $method = 'get' . $capsed;
 294      if(isset($this->tools_signatures[$method]))
 295        return $method;
 296    }
 297  
 298    protected function _mapPropertyToSetMethod($property)
 299    {
 300      $this->_ensureSignatures();
 301  
 302      $method = 'set' . lmb_camel_case($property);
 303      if(isset($this->tools_signatures[$method]))
 304        return $method;
 305    }
 306  
 307  }
 308  ?>