library/Zend/Loader/PluginLoader.php

   1 <?php
   2 /**
   3  * Zend Framework
   4  *
   5  * LICENSE
   6  *
   7  * This source file is subject to the new BSD license that is bundled
   8  * with this package in the file LICENSE.txt.
   9  * It is also available through the world-wide-web at this URL:
  10  * http://framework.zend.com/license/new-bsd
  11  * If you did not receive a copy of the license and are unable to
  12  * obtain it through the world-wide-web, please send an email
  13  * to license@zend.com so we can send you a copy immediately.
  14  *
  15  * @category   Zend
  16  * @package    Zend_Loader
  17  * @subpackage PluginLoader
  18  * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
  19  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  20  * @version    $Id: PluginLoader.php 16971 2009-07-22 18:05:45Z mikaelkael $
  21  */
  22
  23 /** Zend_Loader_PluginLoader_Interface */
  24 require_once 'Zend/Loader/PluginLoader/Interface.php';
  25
  26 /** Zend_Loader */
  27 require_once 'Zend/Loader.php';
  28
  29 /**
  30  * Generic plugin class loader
  31  *
  32  * @category   Zend
  33  * @package    Zend_Loader
  34  * @subpackage PluginLoader
  35  * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
  36  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  37  */
  38 class Zend_Loader_PluginLoader implements Zend_Loader_PluginLoader_Interface
  39 {
  40     /**
  41      * Class map cache file
  42      * @var string
  43      */
  44     protected static $_includeFileCache;
  45
  46     /**
  47      * Instance loaded plugin paths
  48      *
  49      * @var array
  50      */
  51     protected $_loadedPluginPaths = array();
  52
  53     /**
  54      * Instance loaded plugins
  55      *
  56      * @var array
  57      */
  58     protected $_loadedPlugins = array();
  59
  60     /**
  61      * Instance registry property
  62      *
  63      * @var array
  64      */
  65     protected $_prefixToPaths = array();
  66
  67     /**
  68      * Statically loaded plugin path mappings
  69      *
  70      * @var array
  71      */
  72     protected static $_staticLoadedPluginPaths = array();
  73
  74     /**
  75      * Statically loaded plugins
  76      *
  77      * @var array
  78      */
  79     protected static $_staticLoadedPlugins = array();
  80
  81     /**
  82      * Static registry property
  83      *
  84      * @var array
  85      */
  86     protected static $_staticPrefixToPaths = array();
  87
  88     /**
  89      * Whether to use a statically named registry for loading plugins
  90      *
  91      * @var string|null
  92      */
  93     protected $_useStaticRegistry = null;
  94
  95     /**
  96      * Constructor
  97      *
  98      * @param array $prefixToPaths
  99      * @param string $staticRegistryName OPTIONAL
 100      */
 101     public function __construct(Array $prefixToPaths = array(), $staticRegistryName = null)
 102     {
 103         if (is_string($staticRegistryName) && !empty($staticRegistryName)) {
 104             $this->_useStaticRegistry = $staticRegistryName;
 105             if(!isset(self::$_staticPrefixToPaths[$staticRegistryName])) {
 106                 self::$_staticPrefixToPaths[$staticRegistryName] = array();
 107             }
 108             if(!isset(self::$_staticLoadedPlugins[$staticRegistryName])) {
 109                 self::$_staticLoadedPlugins[$staticRegistryName] = array();
 110             }
 111         }
 112
 113         foreach ($prefixToPaths as $prefix => $path) {
 114             $this->addPrefixPath($prefix, $path);
 115         }
 116     }
 117
 118     /**
 119      * Format prefix for internal use
 120      *
 121      * @param  string $prefix
 122      * @return string
 123      */
 124     protected function _formatPrefix($prefix)
 125     {
 126         if($prefix == "") {
 127                 return $prefix;
 128         }
 129         return rtrim($prefix, '_') . '_';
 130     }
 131
 132     /**
 133      * Add prefixed paths to the registry of paths
 134      *
 135      * @param string $prefix
 136      * @param string $path
 137      * @return Zend_Loader_PluginLoader
 138      */
 139     public function addPrefixPath($prefix, $path)
 140     {
 141         if (!is_string($prefix) || !is_string($path)) {
 142             require_once 'Zend/Loader/PluginLoader/Exception.php';
 143             throw new Zend_Loader_PluginLoader_Exception('Zend_Loader_PluginLoader::addPrefixPath() method only takes strings for prefix and path.');
 144         }
 145
 146         $prefix = $this->_formatPrefix($prefix);
 147         $path   = rtrim($path, '/\\') . '/';
 148
 149         if ($this->_useStaticRegistry) {
 150             self::$_staticPrefixToPaths[$this->_useStaticRegistry][$prefix][] = $path;
 151         } else {
 152             $this->_prefixToPaths[$prefix][] = $path;
 153         }
 154         return $this;
 155     }
 156
 157     /**
 158      * Get path stack
 159      *
 160      * @param  string $prefix
 161      * @return false|array False if prefix does not exist, array otherwise
 162      */
 163     public function getPaths($prefix = null)
 164     {
 165         if ((null !== $prefix) && is_string($prefix)) {
 166             $prefix = $this->_formatPrefix($prefix);
 167             if ($this->_useStaticRegistry) {
 168                 if (isset(self::$_staticPrefixToPaths[$this->_useStaticRegistry][$prefix])) {
 169                     return self::$_staticPrefixToPaths[$this->_useStaticRegistry][$prefix];
 170                 }
 171
 172                 return false;
 173             }
 174
 175             if (isset($this->_prefixToPaths[$prefix])) {
 176                 return $this->_prefixToPaths[$prefix];
 177             }
 178
 179             return false;
 180         }
 181
 182         if ($this->_useStaticRegistry) {
 183             return self::$_staticPrefixToPaths[$this->_useStaticRegistry];
 184         }
 185
 186         return $this->_prefixToPaths;
 187     }
 188
 189     /**
 190      * Clear path stack
 191      *
 192      * @param  string $prefix
 193      * @return bool False only if $prefix does not exist
 194      */
 195     public function clearPaths($prefix = null)
 196     {
 197         if ((null !== $prefix) && is_string($prefix)) {
 198             $prefix = $this->_formatPrefix($prefix);
 199             if ($this->_useStaticRegistry) {
 200                 if (isset(self::$_staticPrefixToPaths[$this->_useStaticRegistry][$prefix])) {
 201                     unset(self::$_staticPrefixToPaths[$this->_useStaticRegistry][$prefix]);
 202                     return true;
 203                 }
 204
 205                 return false;
 206             }
 207
 208             if (isset($this->_prefixToPaths[$prefix])) {
 209                 unset($this->_prefixToPaths[$prefix]);
 210                 return true;
 211             }
 212
 213             return false;
 214         }
 215
 216         if ($this->_useStaticRegistry) {
 217             self::$_staticPrefixToPaths[$this->_useStaticRegistry] = array();
 218         } else {
 219             $this->_prefixToPaths = array();
 220         }
 221
 222         return true;
 223     }
 224
 225     /**
 226      * Remove a prefix (or prefixed-path) from the registry
 227      *
 228      * @param string $prefix
 229      * @param string $path OPTIONAL
 230      * @return Zend_Loader_PluginLoader
 231      */
 232     public function removePrefixPath($prefix, $path = null)
 233     {
 234         $prefix = $this->_formatPrefix($prefix);
 235         if ($this->_useStaticRegistry) {
 236             $registry =& self::$_staticPrefixToPaths[$this->_useStaticRegistry];
 237         } else {
 238             $registry =& $this->_prefixToPaths;
 239         }
 240
 241         if (!isset($registry[$prefix])) {
 242             require_once 'Zend/Loader/PluginLoader/Exception.php';
 243             throw new Zend_Loader_PluginLoader_Exception('Prefix ' . $prefix . ' was not found in the PluginLoader.');
 244         }
 245
 246         if ($path != null) {
 247             $pos = array_search($path, $registry[$prefix]);
 248             if ($pos === null) {
 249                 require_once 'Zend/Loader/PluginLoader/Exception.php';
 250                 throw new Zend_Loader_PluginLoader_Exception('Prefix ' . $prefix . ' / Path ' . $path . ' was not found in the PluginLoader.');
 251             }
 252             unset($registry[$prefix][$pos]);
 253         } else {
 254             unset($registry[$prefix]);
 255         }
 256
 257         return $this;
 258     }
 259
 260     /**
 261      * Normalize plugin name
 262      *
 263      * @param  string $name
 264      * @return string
 265      */
 266     protected function _formatName($name)
 267     {
 268         return ucfirst((string) $name);
 269     }
 270
 271     /**
 272      * Whether or not a Plugin by a specific name is loaded
 273      *
 274      * @param string $name
 275      * @return Zend_Loader_PluginLoader
 276      */
 277     public function isLoaded($name)
 278     {
 279         $name = $this->_formatName($name);
 280         if ($this->_useStaticRegistry) {
 281             return isset(self::$_staticLoadedPlugins[$this->_useStaticRegistry][$name]);
 282         }
 283
 284         return isset($this->_loadedPlugins[$name]);
 285     }
 286
 287     /**
 288      * Return full class name for a named plugin
 289      *
 290      * @param string $name
 291      * @return string|false False if class not found, class name otherwise
 292      */
 293     public function getClassName($name)
 294     {
 295         $name = $this->_formatName($name);
 296         if ($this->_useStaticRegistry
 297             && isset(self::$_staticLoadedPlugins[$this->_useStaticRegistry][$name])
 298         ) {
 299             return self::$_staticLoadedPlugins[$this->_useStaticRegistry][$name];
 300         } elseif (isset($this->_loadedPlugins[$name])) {
 301             return $this->_loadedPlugins[$name];
 302         }
 303
 304         return false;
 305     }
 306
 307     /**
 308      * Get path to plugin class
 309      *
 310      * @param  mixed $name
 311      * @return string|false False if not found
 312      */
 313     public function getClassPath($name)
 314     {
 315         $name = $this->_formatName($name);
 316         if ($this->_useStaticRegistry
 317             && !empty(self::$_staticLoadedPluginPaths[$this->_useStaticRegistry][$name])
 318         ) {
 319             return self::$_staticLoadedPluginPaths[$this->_useStaticRegistry][$name];
 320         } elseif (!empty($this->_loadedPluginPaths[$name])) {
 321             return $this->_loadedPluginPaths[$name];
 322         }
 323
 324         if ($this->isLoaded($name)) {
 325             $class = $this->getClassName($name);
 326             $r     = new ReflectionClass($class);
 327             $path  = $r->getFileName();
 328             if ($this->_useStaticRegistry) {
 329                 self::$_staticLoadedPluginPaths[$this->_useStaticRegistry][$name] = $path;
 330             } else {
 331                 $this->_loadedPluginPaths[$name] = $path;
 332             }
 333             return $path;
 334         }
 335
 336         return false;
 337     }
 338
 339     /**
 340      * Load a plugin via the name provided
 341      *
 342      * @param  string $name
 343      * @param  bool $throwExceptions Whether or not to throw exceptions if the
 344      * class is not resolved
 345      * @return string|false Class name of loaded class; false if $throwExceptions
 346      * if false and no class found
 347      * @throws Zend_Loader_Exception if class not found
 348      */
 349     public function load($name, $throwExceptions = true)
 350     {
 351         $name = $this->_formatName($name);
 352         if ($this->isLoaded($name)) {
 353             return $this->getClassName($name);
 354         }
 355
 356         if ($this->_useStaticRegistry) {
 357             $registry = self::$_staticPrefixToPaths[$this->_useStaticRegistry];
 358         } else {
 359             $registry = $this->_prefixToPaths;
 360         }
 361
 362         $registry  = array_reverse($registry, true);
 363         $found     = false;
 364         $classFile = str_replace('_', DIRECTORY_SEPARATOR, $name) . '.php';
 365         $incFile   = self::getIncludeFileCache();
 366         foreach ($registry as $prefix => $paths) {
 367             $className = $prefix . $name;
 368
 369             if (class_exists($className, false)) {
 370                 $found = true;
 371                 break;
 372             }
 373
 374             $paths     = array_reverse($paths, true);
 375
 376             foreach ($paths as $path) {
 377                 $loadFile = $path . $classFile;
 378                 if (Zend_Loader::isReadable($loadFile)) {
 379                     include_once $loadFile;
 380                     if (class_exists($className, false)) {
 381                         if (null !== $incFile) {
 382                             self::_appendIncFile($loadFile);
 383                         }
 384                         $found = true;
 385                         break 2;
 386                     }
 387                 }
 388             }
 389         }
 390
 391         if (!$found) {
 392             if (!$throwExceptions) {
 393                 return false;
 394             }
 395
 396             $message = "Plugin by name '$name' was not found in the registry; used paths:";
 397             foreach ($registry as $prefix => $paths) {
 398                 $message .= "\n$prefix: " . implode(PATH_SEPARATOR, $paths);
 399             }
 400             require_once 'Zend/Loader/PluginLoader/Exception.php';
 401             throw new Zend_Loader_PluginLoader_Exception($message);
 402        }
 403
 404         if ($this->_useStaticRegistry) {
 405             self::$_staticLoadedPlugins[$this->_useStaticRegistry][$name]     = $className;
 406             self::$_staticLoadedPluginPaths[$this->_useStaticRegistry][$name] = (isset($loadFile) ? $loadFile : '');
 407         } else {
 408             $this->_loadedPlugins[$name]     = $className;
 409             $this->_loadedPluginPaths[$name] = (isset($loadFile) ? $loadFile : '');
 410         }
 411         return $className;
 412     }
 413
 414     /**
 415      * Set path to class file cache
 416      *
 417      * Specify a path to a file that will add include_once statements for each
 418      * plugin class loaded. This is an opt-in feature for performance purposes.
 419      *
 420      * @param  string $file
 421      * @return void
 422      * @throws Zend_Loader_PluginLoader_Exception if file is not writeable or path does not exist
 423      */
 424     public static function setIncludeFileCache($file)
 425     {
 426         if (null === $file) {
 427             self::$_includeFileCache = null;
 428             return;
 429         }
 430
 431         if (!file_exists($file) && !file_exists(dirname($file))) {
 432             require_once 'Zend/Loader/PluginLoader/Exception.php';
 433             throw new Zend_Loader_PluginLoader_Exception('Specified file does not exist and/or directory does not exist (' . $file . ')');
 434         }
 435         if (file_exists($file) && !is_writable($file)) {
 436             require_once 'Zend/Loader/PluginLoader/Exception.php';
 437             throw new Zend_Loader_PluginLoader_Exception('Specified file is not writeable (' . $file . ')');
 438         }
 439         if (!file_exists($file) && file_exists(dirname($file)) && !is_writable(dirname($file))) {
 440             require_once 'Zend/Loader/PluginLoader/Exception.php';
 441             throw new Zend_Loader_PluginLoader_Exception('Specified file is not writeable (' . $file . ')');
 442         }
 443
 444         self::$_includeFileCache = $file;
 445     }
 446
 447     /**
 448      * Retrieve class file cache path
 449      *
 450      * @return string|null
 451      */
 452     public static function getIncludeFileCache()
 453     {
 454         return self::$_includeFileCache;
 455     }
 456
 457     /**
 458      * Append an include_once statement to the class file cache
 459      *
 460      * @param  string $incFile
 461      * @return void
 462      */
 463     protected static function _appendIncFile($incFile)
 464     {
 465         if (!file_exists(self::$_includeFileCache)) {
 466             $file = '<?php';
 467         } else {
 468             $file = file_get_contents(self::$_includeFileCache);
 469         }
 470         if (!strstr($file, $incFile)) {
 471             $file .= "\ninclude_once '$incFile';";
 472             file_put_contents(self::$_includeFileCache, $file);
 473         }
 474     }
 475 }