sources/Registry.php

   1 <?php
   2 /**
   3  * The Zend Framework is covered by the new BSD Licence.
   4  * This File is part of irBot and subject to the GPLv3
   5  *
   6  * Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
   7  * Copyright (c) 2008 Bellière Ludovic
   8  *
   9  *  This program is free software: you can redistribute it and/or modify
  10  *  it under the terms of the GNU General Public License as published by
  11  *  the Free Software Foundation, either version 3 of the License, or
  12  *  (at your option) any later version.
  13  *
  14  *  This program is distributed in the hope that it will be useful,
  15  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  *  GNU General Public License for more details.
  18  *
  19  *  You should have received a copy of the GNU General Public License
  20  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  21  */
  22
  23 /**
  24  * Generic storage class helps to manage global data. + Zend_Loader
  25  *
  26  * @category   Zend
  27  * @package    Zend_Registry
  28  * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
  29  * @copyright  Copyright (c) 2008 Bellière Ludovic
  30  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  31  * @license    http://www.gnu.org/licenses/gpl-3.0.html
  32  */
  33 class Zend_Registry extends ArrayObject
  34 {
  35     /**
  36      * Class name of the singleton registry object.
  37      * @var string
  38      */
  39     private static $_registryClassName = 'Zend_Registry';
  40
  41     /**
  42      * Registry object provides storage for shared objects.
  43      * @var Zend_Registry
  44      */
  45     private static $_registry = null;
  46
  47     /**
  48      * Retrieves the default registry instance.
  49      *
  50      * @return Zend_Registry
  51      */
  52     public static function getInstance()
  53     {
  54         if (self::$_registry === null) {
  55             self::init();
  56         }
  57
  58         return self::$_registry;
  59     }
  60
  61     /**
  62      * Set the default registry instance to a specified instance.
  63      *
  64      * @param Zend_Registry $registry An object instance of type Zend_Registry,
  65      *   or a subclass.
  66      * @return void
  67      * @throws Exception if registry is already initialized.
  68      */
  69     public static function setInstance(Zend_Registry $registry)
  70     {
  71         if (self::$_registry !== null) {
  72             throw new Exception('Registry is already initialized');
  73         }
  74
  75         self::setClassName(get_class($registry));
  76         self::$_registry = $registry;
  77     }
  78
  79     /**
  80      * Initialize the default registry instance.
  81      *
  82      * @return void
  83      */
  84     protected static function init()
  85     {
  86         self::setInstance(new self::$_registryClassName());
  87     }
  88
  89     /**
  90      * Set the class name to use for the default registry instance.
  91      * Does not affect the currently initialized instance, it only applies
  92      * for the next time you instantiate.
  93      *
  94      * @param string $registryClassName
  95      * @return void
  96      * @throws Exception if the registry is initialized or if the
  97      *   class name is not valid.
  98      */
  99     public static function setClassName($registryClassName = 'Zend_Registry')
 100     {
 101         if (self::$_registry !== null) {
 102             throw new Exception('Registry is already initialized');
 103         }
 104
 105         if (!is_string($registryClassName)) {
 106             throw new Exception("Argument is not a class name");
 107         }
 108
 109         self::loadClass($registryClassName);
 110
 111         self::$_registryClassName = $registryClassName;
 112     }
 113
 114     /**
 115      * Unset the default registry instance.
 116      * Primarily used in tearDown() in unit tests.
 117      * @returns void
 118      */
 119     public static function _unsetInstance()
 120     {
 121         self::$_registry = null;
 122     }
 123
 124     /**
 125      * getter method, basically same as offsetGet().
 126      *
 127      * This method can be called from an object of type Zend_Registry, or it
 128      * can be called statically.  In the latter case, it uses the default
 129      * static instance stored in the class.
 130      *
 131      * @param string $index - get the value associated with $index
 132      * @return mixed
 133      * @throws Exception if no entry is registerd for $index.
 134      */
 135     public static function get($index)
 136     {
 137         $instance = self::getInstance();
 138
 139         if (!$instance->offsetExists($index)) {
 140             throw new Exception("No entry is registered for key '$index'");
 141         }
 142
 143         return $instance->offsetGet($index);
 144     }
 145
 146     /**
 147      * setter method, basically same as offsetSet().
 148      *
 149      * This method can be called from an object of type Zend_Registry, or it
 150      * can be called statically.  In the latter case, it uses the default
 151      * static instance stored in the class.
 152      *
 153      * @param string $index The location in the ArrayObject in which to store
 154      *   the value.
 155      * @param mixed $value The object to store in the ArrayObject.
 156      * @return void
 157      */
 158     public static function set($index, $value)
 159     {
 160         $instance = self::getInstance();
 161         $instance->offsetSet($index, $value);
 162     }
 163
 164     /**
 165      * Returns TRUE if the $index is a named value in the registry,
 166      * or FALSE if $index was not found in the registry.
 167      *
 168      * @param  string $index
 169      * @return boolean
 170      */
 171     public static function isRegistered($index)
 172     {
 173         if (self::$_registry === null) {
 174             return false;
 175         }
 176         return self::$_registry->offsetExists($index);
 177     }
 178
 179     /**
 180      * @param string $index
 181      * @returns mixed
 182      *
 183      * Workaround for http://bugs.php.net/bug.php?id=40442 (ZF-960).
 184      */
 185     public function offsetExists($index)
 186     {
 187         return array_key_exists($index, $this);
 188     }
 189
 190     /**
 191      * Loads a class from a PHP file.  The filename must be formatted
 192      * as "$class.php".
 193      *
 194      * If $dirs is a string or an array, it will search the directories
 195      * in the order supplied, and attempt to load the first matching file.
 196      *
 197      * If $dirs is null, it will split the class name at underscores to
 198      * generate a path hierarchy (e.g., "Zend_Example_Class" will map
 199      * to "Zend/Example/Class.php").
 200      *
 201      * If the file was not found in the $dirs, or if no $dirs were specified,
 202      * it will attempt to load it from PHP's include_path.
 203      *
 204      * @param string $class      - The full class name of a Zend component.
 205      * @param string|array $dirs - OPTIONAL Either a path or an array of paths
 206      *                             to search.
 207      * @return void
 208      * @throws Exception
 209      */
 210     public static function loadClass($class, $dirs = null)
 211     {
 212         if (class_exists($class, false) || interface_exists($class, false)) {
 213             return;
 214         }
 215
 216         if ((null !== $dirs) && !is_string($dirs) && !is_array($dirs)) {
 217             throw new Exception('Directory argument must be a string or an array');
 218         }
 219
 220         // autodiscover the path from the class name
 221         $file = str_replace('_', DIRECTORY_SEPARATOR, $class) . '.php';
 222         if (!empty($dirs)) {
 223             // use the autodiscovered path
 224             $dirPath = dirname($file);
 225             if (is_string($dirs)) {
 226                 $dirs = explode(PATH_SEPARATOR, $dirs);
 227             }
 228             foreach ($dirs as $key => $dir) {
 229                 if ($dir == '.') {
 230                     $dirs[$key] = $dirPath;
 231                 } else {
 232                     $dir = rtrim($dir, '\\/');
 233                     $dirs[$key] = $dir . DIRECTORY_SEPARATOR . $dirPath;
 234                 }
 235             }
 236             $file = basename($file);
 237             self::loadFile($file, $dirs, true);
 238         } else {
 239             self::_securityCheck($file);
 240             include_once $file;
 241         }
 242
 243         if (!class_exists($class, false) && !interface_exists($class, false)) {
 244             throw new Exception("File \"$file\" was loaded but class \"$class\" was not found in the file");
 245         }
 246     }
 247
 248     /**
 249      * Loads a PHP file.  This is a wrapper for PHP's include() function.
 250      *
 251      * $filename must be the complete filename, including any
 252      * extension such as ".php".  Note that a security check is performed that
 253      * does not permit extended characters in the filename.  This method is
 254      * intended for loading Zend Framework files.
 255      *
 256      * If $dirs is a string or an array, it will search the directories
 257      * in the order supplied, and attempt to load the first matching file.
 258      *
 259      * If the file was not found in the $dirs, or if no $dirs were specified,
 260      * it will attempt to load it from PHP's include_path.
 261      *
 262      * If $once is TRUE, it will use include_once() instead of include().
 263      *
 264      * @param  string        $filename
 265      * @param  string|array  $dirs - OPTIONAL either a path or array of paths
 266      *                       to search.
 267      * @param  boolean       $once
 268      * @return boolean
 269      * @throws Zend_Exception
 270      */
 271     public static function loadFile($filename, $dirs = null, $once = false)
 272     {
 273         self::_securityCheck($filename);
 274
 275         /**
 276          * Search in provided directories, as well as include_path
 277          */
 278         $incPath = false;
 279         if (!empty($dirs) && (is_array($dirs) || is_string($dirs))) {
 280             if (is_array($dirs)) {
 281                 $dirs = implode(PATH_SEPARATOR, $dirs);
 282             }
 283             $incPath = get_include_path();
 284             set_include_path($dirs . PATH_SEPARATOR . $incPath);
 285         }
 286
 287         /**
 288          * Try finding for the plain filename in the include_path.
 289          */
 290         if ($once) {
 291             include_once $filename;
 292         } else {
 293             include $filename;
 294         }
 295
 296         /**
 297          * If searching in directories, reset include_path
 298          */
 299         if ($incPath) {
 300             set_include_path($incPath);
 301         }
 302
 303         return true;
 304     }
 305
 306     /**
 307      * Returns TRUE if the $filename is readable, or FALSE otherwise.
 308      * This function uses the PHP include_path, where PHP's is_readable()
 309      * does not.
 310      *
 311      * @param string   $filename
 312      * @return boolean
 313      */
 314     public static function isReadable($filename)
 315     {
 316         if (!$fh = @fopen($filename, 'r', true)) {
 317             return false;
 318         }
 319
 320         return true;
 321     }
 322
 323     /**
 324      * spl_autoload() suitable implementation for supporting class autoloading.
 325      *
 326      * Attach to spl_autoload() using the following:
 327      * <code>
 328      * spl_autoload_register(array('Zend_Loader', 'autoload'));
 329      * </code>
 330      *
 331      * @param string $class
 332      * @return string|false Class name on success; false on failure
 333      */
 334     public static function autoload($class)
 335     {
 336         try {
 337             self::loadClass($class);
 338             return $class;
 339         } catch (Exception $e) {
 340             return false;
 341         }
 342     }
 343
 344     /**
 345      * Register {@link autoload()} with spl_autoload()
 346      *
 347      * @param string $class (optional)
 348      * @param boolean $enabled (optional)
 349      * @return void
 350      * @throws Exception if spl_autoload() is not found
 351      * or if the specified class does not have an autoload() method.
 352      */
 353     public static function registerAutoload($class = 'Zend_Registry', $enabled = true)
 354     {
 355         if (!function_exists('spl_autoload_register')) {
 356             throw new Exception('spl_autoload does not exist in this PHP installation');
 357         }
 358
 359         self::loadClass($class);
 360         $methods = get_class_methods($class);
 361         if (!in_array('autoload', (array) $methods)) {
 362             throw new Exception("The class \"$class\" does not have an autoload() method");
 363         }
 364
 365         if ($enabled === true) {
 366             spl_autoload_register(array($class, 'autoload'));
 367         } else {
 368             spl_autoload_unregister(array($class, 'autoload'));
 369         }
 370     }
 371
 372     /**
 373      * Ensure that filename does not contain exploits
 374      *
 375      * @param  string $filename
 376      * @return void
 377      * @throws Zend_Exception
 378      */
 379     protected static function _securityCheck($filename)
 380     {
 381         /**
 382          * Security check
 383          */
 384         if (preg_match('/[^a-z0-9\\/\\\\_.-]/i', $filename)) {
 385             throw new Exception('Security check: Illegal character in filename');
 386         }
 387     }
 388
 389     /**
 390      * Attempt to include() the file.
 391      *
 392      * include() is not prefixed with the @ operator because if
 393      * the file is loaded and contains a parse error, execution
 394      * will halt silently and this is difficult to debug.
 395      *
 396      * Always set display_errors = Off on production servers!
 397      *
 398      * @param  string  $filespec
 399      * @param  boolean $once
 400      * @return boolean
 401      * @deprecated Since 1.5.0; use loadFile() instead
 402      */
 403     protected static function _includeFile($filespec, $once = false)
 404     {
 405         if ($once) {
 406             return include_once $filespec;
 407         } else {
 408             return include $filespec ;
 409         }
 410     }
 411
 412 }