library/Zend/Loader/Autoloader/Resource.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 Autoloader
  18  * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
  19  * @version    $Id: Resource.php 17417 2009-08-06 18:06:04Z matthew $
  20  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  21  */
  22
  23 /** Zend_Loader_Autoloader_Interface */
  24 require_once 'Zend/Loader/Autoloader/Interface.php';
  25
  26 /**
  27  * Resource loader
  28  *
  29  * @uses       Zend_Loader_Autoloader_Interface
  30  * @package    Zend_Loader
  31  * @subpackage Autoloader
  32  * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
  33  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  34  */
  35 class Zend_Loader_Autoloader_Resource implements Zend_Loader_Autoloader_Interface
  36 {
  37     /**
  38      * @var string Base path to resource classes
  39      */
  40     protected $_basePath;
  41
  42     /**
  43      * @var array Components handled within this resource
  44      */
  45     protected $_components = array();
  46
  47     /**
  48      * @var string Default resource/component to use when using object registry
  49      */
  50     protected $_defaultResourceType;
  51
  52     /**
  53      * @var string Namespace of classes within this resource
  54      */
  55     protected $_namespace;
  56
  57     /**
  58      * @var array Available resource types handled by this resource autoloader
  59      */
  60     protected $_resourceTypes = array();
  61
  62     /**
  63      * Constructor
  64      *
  65      * @param  array|Zend_Config $options Configuration options for resource autoloader
  66      * @return void
  67      */
  68     public function __construct($options)
  69     {
  70         if ($options instanceof Zend_Config) {
  71             $options = $options->toArray();
  72         }
  73         if (!is_array($options)) {
  74             require_once 'Zend/Loader/Exception.php';
  75             throw new Zend_Loader_Exception('Options must be passed to resource loader constructor');
  76         }
  77
  78         $this->setOptions($options);
  79
  80         $namespace = $this->getNamespace();
  81         if ((null === $namespace)
  82             || (null === $this->getBasePath())
  83         ) {
  84             require_once 'Zend/Loader/Exception.php';
  85             throw new Zend_Loader_Exception('Resource loader requires both a namespace and a base path for initialization');
  86         }
  87
  88         if (!empty($namespace)) {
  89             $namespace .= '_';
  90         }
  91         Zend_Loader_Autoloader::getInstance()->unshiftAutoloader($this, $namespace);
  92     }
  93
  94     /**
  95      * Overloading: methods
  96      *
  97      * Allow retrieving concrete resource object instances using 'get<Resourcename>()'
  98      * syntax. Example:
  99      * <code>
 100      * $loader = new Zend_Loader_Autoloader_Resource(array(
 101      *     'namespace' => 'Stuff_',
 102      *     'basePath'  => '/path/to/some/stuff',
 103      * ))
 104      * $loader->addResourceType('Model', 'models', 'Model');
 105      *
 106      * $foo = $loader->getModel('Foo'); // get instance of Stuff_Model_Foo class
 107      * </code>
 108      *
 109      * @param  string $method
 110      * @param  array $args
 111      * @return mixed
 112      * @throws Zend_Loader_Exception if method not beginning with 'get' or not matching a valid resource type is called
 113      */
 114     public function __call($method, $args)
 115     {
 116         if ('get' == substr($method, 0, 3)) {
 117             $type  = strtolower(substr($method, 3));
 118             if (!$this->hasResourceType($type)) {
 119                 require_once 'Zend/Loader/Exception.php';
 120                 throw new Zend_Loader_Exception("Invalid resource type $type; cannot load resource");
 121             }
 122             if (empty($args)) {
 123                 require_once 'Zend/Loader/Exception.php';
 124                 throw new Zend_Loader_Exception("Cannot load resources; no resource specified");
 125             }
 126             $resource = array_shift($args);
 127             return $this->load($resource, $type);
 128         }
 129
 130         require_once 'Zend/Loader/Exception.php';
 131         throw new Zend_Loader_Exception("Method '$method' is not supported");
 132     }
 133
 134     /**
 135      * Attempt to autoload a class
 136      *
 137      * @param  string $class
 138      * @return mixed False if not matched, otherwise result if include operation
 139      */
 140     public function autoload($class)
 141     {
 142         $segments          = explode('_', $class);
 143         $namespaceTopLevel = $this->getNamespace();
 144         $namespace         = '';
 145
 146         if (!empty($namespaceTopLevel)) {
 147             $namespace = array_shift($segments);
 148             if ($namespace != $namespaceTopLevel) {
 149                 // wrong prefix? we're done
 150                 return false;
 151             }
 152         }
 153
 154         if (count($segments) < 2) {
 155             // assumes all resources have a component and class name, minimum
 156             return false;
 157         }
 158
 159         $final     = array_pop($segments);
 160         $component = $namespace;
 161         $lastMatch = false;
 162         do {
 163             $segment    = array_shift($segments);
 164             $component .= empty($component) ? $segment : '_' . $segment;
 165             if (isset($this->_components[$component])) {
 166                 $lastMatch = $component;
 167             }
 168         } while (count($segments));
 169
 170         if (!$lastMatch) {
 171             return false;
 172         }
 173
 174         $final = substr($class, strlen($lastMatch));
 175         $path = $this->_components[$lastMatch];
 176         return include $path . '/' . str_replace('_', '/', $final) . '.php';
 177     }
 178
 179     /**
 180      * Set class state from options
 181      *
 182      * @param  array $options
 183      * @return Zend_Loader_Autoloader_Resource
 184      */
 185     public function setOptions(array $options)
 186     {
 187         $methods = get_class_methods($this);
 188         foreach ($options as $key => $value) {
 189             $method = 'set' . ucfirst($key);
 190             if (in_array($method, $methods)) {
 191                 $this->$method($value);
 192             }
 193         }
 194         return $this;
 195     }
 196
 197     /**
 198      * Set namespace that this autoloader handles
 199      *
 200      * @param  string $namespace
 201      * @return Zend_Loader_Autoloader_Resource
 202      */
 203     public function setNamespace($namespace)
 204     {
 205         $this->_namespace = rtrim((string) $namespace, '_');
 206         return $this;
 207     }
 208
 209     /**
 210      * Get namespace this autoloader handles
 211      *
 212      * @return string
 213      */
 214     public function getNamespace()
 215     {
 216         return $this->_namespace;
 217     }
 218
 219     /**
 220      * Set base path for this set of resources
 221      *
 222      * @param  string $path
 223      * @return Zend_Loader_Autoloader_Resource
 224      */
 225     public function setBasePath($path)
 226     {
 227         $this->_basePath = (string) $path;
 228         return $this;
 229     }
 230
 231     /**
 232      * Get base path to this set of resources
 233      *
 234      * @return string
 235      */
 236     public function getBasePath()
 237     {
 238         return $this->_basePath;
 239     }
 240
 241     /**
 242      * Add resource type
 243      *
 244      * @param  string $type identifier for the resource type being loaded
 245      * @param  string $path path relative to resource base path containing the resource types
 246      * @param  null|string $namespace sub-component namespace to append to base namespace that qualifies this resource type
 247      * @return Zend_Loader_Autoloader_Resource
 248      */
 249     public function addResourceType($type, $path, $namespace = null)
 250     {
 251         $type = strtolower($type);
 252         if (!isset($this->_resourceTypes[$type])) {
 253             if (null === $namespace) {
 254                 require_once 'Zend/Loader/Exception.php';
 255                 throw new Zend_Loader_Exception('Initial definition of a resource type must include a namespace');
 256             }
 257             $namespaceTopLevel = $this->getNamespace();
 258             $namespace = ucfirst(trim($namespace, '_'));
 259             $this->_resourceTypes[$type] = array(
 260                 'namespace' => empty($namespaceTopLevel) ? $namespace : $namespaceTopLevel . '_' . $namespace,
 261             );
 262         }
 263         if (!is_string($path)) {
 264             require_once 'Zend/Loader/Exception.php';
 265             throw new Zend_Loader_Exception('Invalid path specification provided; must be string');
 266         }
 267         $this->_resourceTypes[$type]['path'] = $this->getBasePath() . '/' . $path;
 268
 269         $component = $this->_resourceTypes[$type]['namespace'];
 270         $this->_components[$component] = $this->_resourceTypes[$type]['path'];
 271         return $this;
 272     }
 273
 274     /**
 275      * Add multiple resources at once
 276      *
 277      * $types should be an associative array of resource type => specification
 278      * pairs. Each specification should be an associative array containing
 279      * minimally the 'path' key (specifying the path relative to the resource
 280      * base path) and optionally the 'namespace' key (indicating the subcomponent
 281      * namespace to append to the resource namespace).
 282      *
 283      * As an example:
 284      * <code>
 285      * $loader->addResourceTypes(array(
 286      *     'model' => array(
 287      *         'path'      => 'models',
 288      *         'namespace' => 'Model',
 289      *     ),
 290      *     'form' => array(
 291      *         'path'      => 'forms',
 292      *         'namespace' => 'Form',
 293      *     ),
 294      * ));
 295      * </code>
 296      *
 297      * @param  array $types
 298      * @return Zend_Loader_Autoloader_Resource
 299      */
 300     public function addResourceTypes(array $types)
 301     {
 302         foreach ($types as $type => $spec) {
 303             if (!is_array($spec)) {
 304                 require_once 'Zend/Loader/Exception.php';
 305                 throw new Zend_Loader_Exception('addResourceTypes() expects an array of arrays');
 306             }
 307             if (!isset($spec['path'])) {
 308                 require_once 'Zend/Loader/Exception.php';
 309                 throw new Zend_Loader_Exception('addResourceTypes() expects each array to include a paths element');
 310             }
 311             $paths  = $spec['path'];
 312             $namespace = null;
 313             if (isset($spec['namespace'])) {
 314                 $namespace = $spec['namespace'];
 315             }
 316             $this->addResourceType($type, $paths, $namespace);
 317         }
 318         return $this;
 319     }
 320
 321     /**
 322      * Overwrite existing and set multiple resource types at once
 323      *
 324      * @see    Zend_Loader_Autoloader_Resource::addResourceTypes()
 325      * @param  array $types
 326      * @return Zend_Loader_Autoloader_Resource
 327      */
 328     public function setResourceTypes(array $types)
 329     {
 330         $this->clearResourceTypes();
 331         return $this->addResourceTypes($types);
 332     }
 333
 334     /**
 335      * Retrieve resource type mappings
 336      *
 337      * @return array
 338      */
 339     public function getResourceTypes()
 340     {
 341         return $this->_resourceTypes;
 342     }
 343
 344     /**
 345      * Is the requested resource type defined?
 346      *
 347      * @param  string $type
 348      * @return bool
 349      */
 350     public function hasResourceType($type)
 351     {
 352         return isset($this->_resourceTypes[$type]);
 353     }
 354
 355     /**
 356      * Remove the requested resource type
 357      *
 358      * @param  string $type
 359      * @return Zend_Loader_Autoloader_Resource
 360      */
 361     public function removeResourceType($type)
 362     {
 363         if ($this->hasResourceType($type)) {
 364             $namespace = $this->_resourceTypes[$type]['namespace'];
 365             unset($this->_components[$namespace]);
 366             unset($this->_resourceTypes[$type]);
 367         }
 368         return $this;
 369     }
 370
 371     /**
 372      * Clear all resource types
 373      *
 374      * @return Zend_Loader_Autoloader_Resource
 375      */
 376     public function clearResourceTypes()
 377     {
 378         $this->_resourceTypes = array();
 379         $this->_components    = array();
 380         return $this;
 381     }
 382
 383     /**
 384      * Set default resource type to use when calling load()
 385      *
 386      * @param  string $type
 387      * @return Zend_Loader_Autoloader_Resource
 388      */
 389     public function setDefaultResourceType($type)
 390     {
 391         if ($this->hasResourceType($type)) {
 392             $this->_defaultResourceType = $type;
 393         }
 394         return $this;
 395     }
 396
 397     /**
 398      * Get default resource type to use when calling load()
 399      *
 400      * @return string|null
 401      */
 402     public function getDefaultResourceType()
 403     {
 404         return $this->_defaultResourceType;
 405     }
 406
 407     /**
 408      * Object registry and factory
 409      *
 410      * Loads the requested resource of type $type (or uses the default resource
 411      * type if none provided). If the resource has been loaded previously,
 412      * returns the previous instance; otherwise, instantiates it.
 413      *
 414      * @param  string $resource
 415      * @param  string $type
 416      * @return object
 417      * @throws Zend_Loader_Exception if resource type not specified or invalid
 418      */
 419     public function load($resource, $type = null)
 420     {
 421         if (null === $type) {
 422             $type = $this->getDefaultResourceType();
 423             if (empty($type)) {
 424                 require_once 'Zend/Loader/Exception.php';
 425                 throw new Zend_Loader_Exception('No resource type specified');
 426             }
 427         }
 428         if (!$this->hasResourceType($type)) {
 429             require_once 'Zend/Loader/Exception.php';
 430             throw new Zend_Loader_Exception('Invalid resource type specified');
 431         }
 432         $namespace = $this->_resourceTypes[$type]['namespace'];
 433         $class     = $namespace . '_' . ucfirst($resource);
 434         if (!isset($this->_resources[$class])) {
 435             $this->_resources[$class] = new $class;
 436         }
 437         return $this->_resources[$class];
 438     }
 439 }