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