PageRenderTime 61ms CodeModel.GetById 28ms RepoModel.GetById 0ms app.codeStats 1ms

/htdocs/lithium/0.9.9/libraries/lithium/core/Libraries.php

http://github.com/pmjones/php-framework-benchmarks
PHP | 898 lines | 612 code | 31 blank | 255 comment | 53 complexity | c9a34930b5940dd9790002e445de68df MD5 | raw file
Possible License(s): LGPL-3.0, Apache-2.0, BSD-3-Clause, ISC, AGPL-3.0, LGPL-2.1
  1. <?php
  2. /**
  3. * Lithium: the most rad php framework
  4. *
  5. * @copyright Copyright 2010, Union of RAD (http://union-of-rad.org)
  6. * @license http://opensource.org/licenses/bsd-license.php The BSD License
  7. */
  8. namespace lithium\core;
  9. use RuntimeException;
  10. use lithium\util\String;
  11. use lithium\core\ConfigException;
  12. use lithium\core\ClassNotFoundException;
  13. /**
  14. * Manages all aspects of class and file location, naming and mapping. Implements auto-loading for
  15. * the Lithium core, as well as all applications, plugins and vendor libraries registered.
  16. * Typically, libraries and plugins are registered in `app/config/bootstrap/libraries.php`.
  17. *
  18. * By convention, plugins and vendor libraries are typically located in `app/libraries` or
  19. * `/libraries` (the former may override the latter). By default, `Libraries` will use its own
  20. * autoloader for all plugins and vendor libraries, but can be configured to use others on a
  21. * per-library basis.
  22. *
  23. * `Libraries` also handles service location. Various _types_ of classes can be defined by name,
  24. * using _class patterns_, which define conventions for organizing classes, i.e. `'models'`, which
  25. * maps to `'{:library}\models\{:name}'`, which will find a model class in any registered app,
  26. * plugin or vendor library that follows that path (namespace) convention. You can find classes by
  27. * name (see the `locate()` method for more information on class-locating precedence), or find all
  28. * models in all registered libraries (apps / plugins / vendor libraries, etc). For more information
  29. * on modifying the default class organization, or defining your own class types, see the `paths()`
  30. * method.
  31. *
  32. * #### Auto-loading classes
  33. *
  34. * Lithium defines several rules, conventions and recommendations for naming and organizing classes.
  35. * The autoloader itself conforms to the [PHP Interoperability Group's draft
  36. * specification](http://groups.google.com/group/php-standards/web/psr-0-final-proposal). While the
  37. * autoloader will load any classes conforming to that specification, Lithium itself follows
  38. * additional constraints, which are also recommended for Lithium applications, libraries and
  39. * extensions, and are as follows:
  40. *
  41. * - Each library must exist in a top-level vendor namespace
  42. * - Each top-level vendor namespace must define a set of sub-packages, and should not directly
  43. * contain classes
  44. * - Namespace names must be lowercased and under_scored
  45. * - Class names must be CamelCased
  46. *
  47. * Any libraries registered by calling `Libraries::add()` which follow the autoloader's will have
  48. * their classes automatically loaded when referenced.
  49. *
  50. * @see lithium\core\Libraries::add()
  51. * @see lithium\core\Libraries::locate()
  52. * @see lithium\core\Libraries::paths()
  53. */
  54. class Libraries {
  55. /**
  56. * The list of class libraries registered with the class loader.
  57. *
  58. * @var array
  59. */
  60. protected static $_configurations = array();
  61. /**
  62. * Contains a cascading list of search path templates, indexed by base object type.
  63. *
  64. * Used by `Libraries::locate()` to perform service location. This allows new types of
  65. * objects (i.e. models, helpers, cache adapters and data sources) to be automatically
  66. * 'discovered' when you register a new vendor library or plugin (using `Libraries::add()`).
  67. *
  68. * Because paths are checked in the order in which they appear, path templates should be
  69. * specified from most-specific to least-specific. See the `locate()` method for usage examples.
  70. *
  71. * @see lithium\core\Libraries::locate()
  72. * @see lithium\core\Libraries::paths()
  73. * @var array
  74. */
  75. protected static $_paths = array(
  76. 'adapter' => array(
  77. '{:library}\extensions\adapter\{:namespace}\{:class}\{:name}',
  78. '{:library}\extensions\adapter\{:class}\{:name}',
  79. '{:library}\{:namespace}\{:class}\adapter\{:name}' => array('libraries' => 'lithium')
  80. ),
  81. 'command' => array(
  82. '{:library}\extensions\command\{:namespace}\{:class}\{:name}',
  83. '{:library}\extensions\command\{:class}\{:name}',
  84. '{:library}\extensions\command\{:name}',
  85. '{:library}\console\command\{:namespace}\{:class}\{:name}' => array(
  86. 'libraries' => 'lithium'
  87. ),
  88. '{:library}\console\command\{:class}\{:name}' => array('libraries' => 'lithium'),
  89. '{:library}\console\command\{:name}' => array('libraries' => 'lithium'),
  90. ),
  91. 'controllers' => array(
  92. '{:library}\controllers\{:name}Controller'
  93. ),
  94. 'data' => array(
  95. '{:library}\extensions\data\{:namespace}\{:class}\{:name}',
  96. '{:library}\extensions\data\{:class}\{:name}',
  97. '{:library}\data\{:namespace}\{:class}\adapter\{:name}' => array(
  98. 'libraries' => 'lithium'
  99. ),
  100. '{:library}\data\{:namespace}\{:class}\{:name}' => array('libraries' => 'lithium'),
  101. '{:library}\data\{:class}\adapter\{:name}' => array('libraries' => 'lithium')
  102. ),
  103. 'helper' => array(
  104. '{:library}\extensions\helper\{:name}',
  105. '{:library}\template\helper\{:name}' => array('libraries' => 'lithium')
  106. ),
  107. 'libraries' => array(
  108. '{:app}/libraries/{:name}',
  109. '{:root}/{:name}'
  110. ),
  111. 'models' => '{:library}\models\{:name}',
  112. 'strategy' => array(
  113. '{:library}\extensions\strategy\{:namespace}\{:class}\{:name}',
  114. '{:library}\extensions\strategy\{:name}',
  115. '{:library}\{:namespace}\{:class}\strategy\{:name}' => array('libraries' => 'lithium')
  116. ),
  117. 'socket' => array(
  118. '{:library}\extensions\net\socket\{:name}',
  119. '{:library}\extensions\socket\{:name}',
  120. '{:library}\net\socket\{:name}'
  121. ),
  122. 'test' => array(
  123. '{:library}\extensions\test\{:namespace}\{:class}\{:name}',
  124. '{:library}\extensions\test\{:class}\{:name}',
  125. '{:library}\test\{:namespace}\{:class}\{:name}' => array('libraries' => 'lithium'),
  126. '{:library}\test\{:class}\{:name}' => array('libraries' => 'lithium')
  127. ),
  128. 'tests' => array(
  129. '{:library}\tests\{:namespace}\{:class}\{:name}Test',
  130. '{:library}\tests\{:namespace}\{:name}Test'
  131. )
  132. );
  133. /**
  134. * Stores the name of the default library. When adding a library configuration to the
  135. * application, if the `'default'` option flag is set to `true`, the name of the library will
  136. * be assigned. To retrieve the default library's configuration, use `Libraries::get(true)`.
  137. *
  138. * @see lithium\core\Libraries::add()
  139. * @see lithium\core\Libraries::get()
  140. * @var string
  141. */
  142. protected static $_default;
  143. /**
  144. * Holds cached class paths generated and used by `lithium\core\Libraries::load()`.
  145. *
  146. * @var array
  147. * @see lithium\core\Libraries::load()
  148. */
  149. protected static $_cachedPaths = array();
  150. /**
  151. * Accessor method for the class path templates which `Libraries` uses to look up and load
  152. * classes. Using this method, you can define your own types of classes, or modify the default
  153. * organization of built-in class types.
  154. *
  155. * For example, in a queuing application, you can define a class type called `'job'`:
  156. * {{{
  157. * Libraries::paths(array('job' => '{:library}\extensions\job\{:name}'));
  158. * }}}
  159. *
  160. * Then, any classes you add to the `extensions/job` directory in your application will be
  161. * automatically detected when calling `Libraries::locate('job')`. Additionally, any matching
  162. * classes in the `extensions/job` directory of any plugin or vendor library you add to your
  163. * application will also be detected.
  164. *
  165. * Supposing you wanted to have the option of further organizing jobs by class type (some jobs
  166. * are related to updating caches, others to sending notifications, etc.), you can specify
  167. * mulitple paths per class type, with varying levels of specificity:
  168. * {{{
  169. * Libraries::paths(array('job' => array(
  170. * '{:library}\extensions\job\{:class}\{:name}',
  171. * '{:library}\extensions\job\{:name}'
  172. * )));
  173. * }}}
  174. *
  175. * This allows you to, for example, have two different classes called `Cleanup`. One may be
  176. * located in `app\extensions\job\Cleanup`, while the other is in
  177. * `app\extensions\job\cache\Cleanup`. Calling: {{{Libraries::locate('job');}}} will find
  178. * both classes, while {{{Libraries::locate('job.cache');}}} will only find the second. You can
  179. * also find individual jobs by name: {{{Libraries::locate('job', 'Cleanup');}}}
  180. *
  181. * See `Libraries::locate()` for more information on using built-in and user-defined paths to
  182. * look up classes.
  183. *
  184. * In addition to adding custom class types, `paths()` allows you to redefine the naming and
  185. * organization of existing types. For example, if you wished to reference your model classes
  186. * as `app\models\PostModel` instead of `app\models\Post`, you can do the following:
  187. * {{{Libraries::paths(array('models' => '{:library}\models\{:name}Model'));}}} Note, however,
  188. * that this is a destructive, not an additive operation, and will replace any existing paths
  189. * defined for that type. If you wish to add a search path for an existing type, you must do
  190. * the following:
  191. * {{{
  192. * $existing = Libraries::paths('controllers');
  193. * Libraries::paths(array('controller' => array_merge(
  194. * array('{:library}\extensions\controllers\{:name}Controller'), (array) $existing
  195. * )));
  196. * }}}
  197. *
  198. * @see lithium\core\Libraries::locate()
  199. * @see lithium\core\Libraries::$_paths
  200. * @param mixed $path If `$path` is a string, returns the path(s) associated with that path
  201. * type, or `null` if no paths are defined for that type.
  202. * @return mixed
  203. */
  204. public static function paths($path = null) {
  205. if (empty($path)) {
  206. return static::$_paths;
  207. }
  208. if (is_string($path)) {
  209. return isset(static::$_paths[$path]) ? static::$_paths[$path] : null;
  210. }
  211. static::$_paths = array_filter(array_merge(static::$_paths, (array) $path));
  212. }
  213. /**
  214. * Adds a class library from which files can be loaded.
  215. *
  216. * The `add()` method registers a named library configuration to your application, and is used
  217. * to allow the framework to auto-load classes on an as-needed basis.
  218. *
  219. * ### Adding libraries to your application
  220. *
  221. * In Lithium, libraries represent the broadest unit of class organization in an application,
  222. * and _everything_ is a library; this includes your application, and the Lithium framework
  223. * itself. Libraries can also be other frameworks, like Solar, Zend Framework or PEAR, or
  224. * Lithium plugins, which are simply libraries that follow the same organizational standards
  225. * as Lithium applications.
  226. *
  227. * By convention, libraries are placed in the `libraries` directory inside your application, or
  228. * the root `libraries` directory at the top level of the default distribution (i.e. the one
  229. * that contains the `lithium` directory), however, you can change this on a case-by-case basis
  230. * using the `'path'` key to specify an absolute path to the library's directory.
  231. *
  232. * @param string $name Library name, i.e. `'app'`, `'lithium'`, `'pear'` or `'solar'`.
  233. * @param array $config Specifies where the library is in the filesystem, and how classes
  234. * should be loaded from it. Allowed keys are:
  235. * - `'bootstrap'`: A file path (relative to `'path'`) to a bootstrap script that should
  236. * be run when the library is added.
  237. * - `'defer'`: If true, indicates that, when locating classes, this library should
  238. * defer to other libraries in order of preference.
  239. * - `'includePath'`: If `true`, appends the absolutely-resolved value of `'path'` to
  240. * the PHP include path.
  241. * - `'loader'`: An auto-loader method associated with the library, if any.
  242. * - `'path'`: The directory containing the library.
  243. * - `'prefix'`: The class prefix this library uses, i.e. `'lithium\'`, `'Zend_'` or
  244. * `'Solar_'`.
  245. * - `'suffix'`: Gets appended to the end of the file name. For example, most libraries
  246. * end classes in `'.php'`, but some use `'.class.php'`, or `'.inc.php'`.
  247. * - `'transform'`: Defines a custom way to transform a class name into its
  248. * corresponding file path. Accepts either an array of two strings which are
  249. * interpreted as the pattern and replacement for a regex, or an anonymous function,
  250. * which receives the class name as a parameter, and returns a file path as output.
  251. * @return array Returns the resulting set of options created for this library.
  252. */
  253. public static function add($name, array $config = array()) {
  254. $defaults = array(
  255. 'path' => null,
  256. 'prefix' => $name . "\\",
  257. 'suffix' => '.php',
  258. 'loader' => null,
  259. 'includePath' => false,
  260. 'transform' => null,
  261. 'bootstrap' => true,
  262. 'defer' => false,
  263. 'default' => false,
  264. );
  265. if ($name === 'lithium') {
  266. $defaults['defer'] = true;
  267. $defaults['bootstrap'] = false;
  268. $defaults['path'] = dirname(__DIR__);
  269. $defaults['loader'] = 'lithium\core\Libraries::load';
  270. }
  271. if (isset($config['default']) && $config['default']) {
  272. static::$_default = $name;
  273. $defaults['path'] = LITHIUM_APP_PATH;
  274. $defaults['bootstrap'] = false;
  275. }
  276. $config += $defaults;
  277. if (!$config['path']) {
  278. if (!$config['path'] = static::_locatePath('libraries', compact('name'))) {
  279. throw new ConfigException("Library '{$name}' not found.");
  280. }
  281. }
  282. $config['path'] = str_replace('\\', '/', $config['path']);
  283. static::_configure(static::$_configurations[$name] = $config);
  284. return $config;
  285. }
  286. /**
  287. * Configures the application environment based on a library's settings, including appending to
  288. * the include path, loading a bootstrap file, and registering a loader with SPL's autoloading
  289. * system.
  290. *
  291. * @param array $config The new library's configuration array.
  292. * @return void
  293. */
  294. protected static function _configure($config) {
  295. if ($config['includePath']) {
  296. $path = ($config['includePath'] === true) ? $config['path'] : $config['includePath'];
  297. set_include_path(get_include_path() . PATH_SEPARATOR . $path);
  298. }
  299. if ($config['bootstrap'] === true) {
  300. $path = "{$config['path']}/config/bootstrap.php";
  301. $config['bootstrap'] = file_exists($path) ? 'config/bootstrap.php' : false;
  302. }
  303. if ($config['bootstrap']) {
  304. require "{$config['path']}/{$config['bootstrap']}";
  305. }
  306. if (!empty($config['loader'])) {
  307. spl_autoload_register($config['loader']);
  308. }
  309. }
  310. /**
  311. * Returns configuration for given name.
  312. *
  313. * @param string $name Registered library to retrieve configuration for.
  314. * @return array Retrieved configuration.
  315. */
  316. public static function get($name = null) {
  317. $configs = static::$_configurations;
  318. if (!$name) {
  319. return $configs;
  320. }
  321. if (is_array($name)) {
  322. foreach ($name as $i => $key) {
  323. unset($name[$i]);
  324. $name[$key] = isset($configs[$key]) ? $configs[$key] : null;
  325. }
  326. return $name;
  327. }
  328. if ($name === true) {
  329. $name = static::$_default;
  330. }
  331. return isset($configs[$name]) ? $configs[$name] : null;
  332. }
  333. /**
  334. * Removes a registered library, and unregister's the library's autoloader, if it has one.
  335. *
  336. * @param mixed $name A string or array of library names indicating the libraries you wish to
  337. * remove, i.e. `'app'` or `'lithium'`. This can also be used to unload plugins by name.
  338. * @return void
  339. */
  340. public static function remove($name) {
  341. foreach ((array) $name as $library) {
  342. if (isset(static::$_configurations[$library])) {
  343. if (static::$_configurations[$library]['loader']) {
  344. spl_autoload_unregister(static::$_configurations[$library]['loader']);
  345. }
  346. unset(static::$_configurations[$library]);
  347. }
  348. }
  349. }
  350. /**
  351. * Finds the classes in a library/namespace/folder
  352. *
  353. * @param string $library
  354. * @param string $options
  355. * @return array
  356. */
  357. public static function find($library, array $options = array()) {
  358. $format = function($file, $config) {
  359. $trim = array(strlen($config['path']) + 1, strlen($config['suffix']));
  360. $rTrim = strpos($file, $config['suffix']) !== false ? -$trim[1] : 9999;
  361. $file = preg_split('/[\/\\\\]/', substr($file, $trim[0], $rTrim));
  362. return $config['prefix'] . join('\\', $file);
  363. };
  364. $defaults = compact('format') + array(
  365. 'path' => '',
  366. 'recursive' => false,
  367. 'filter' => '/^(\w+)?(\\\\[a-z0-9_]+)+\\\\[A-Z][a-zA-Z0-9]+$/',
  368. 'exclude' => '',
  369. 'namespaces' => false,
  370. );
  371. $options += $defaults;
  372. $libs = array();
  373. if ($options['namespaces'] && $options['filter'] == $defaults['filter']) {
  374. $options['format'] = function($class, $config) use ($format, $defaults) {
  375. if (is_dir($class)) {
  376. return $format($class, $config);
  377. }
  378. if (preg_match($defaults['filter'], $class = $format($class, $config))) {
  379. return $class;
  380. }
  381. };
  382. $options['filter'] = false;
  383. }
  384. if ($library === true) {
  385. foreach (static::$_configurations as $library => $config) {
  386. $libs = array_merge($libs, static::find($library, $options));
  387. }
  388. return $libs;
  389. }
  390. if (!isset(static::$_configurations[$library])) {
  391. return null;
  392. }
  393. $config = static::$_configurations[$library];
  394. $options['path'] = "{$config['path']}{$options['path']}/*";
  395. $libs = static::_search($config, $options);
  396. return array_values(array_filter($libs));
  397. }
  398. /**
  399. * Loads the class definition specified by `$class`. Also calls the `__init()` method on the
  400. * class, if defined. Looks through the list of libraries defined in `$_configurations`, which
  401. * are added through `lithium\core\Libraries::add()`.
  402. *
  403. * @see lithium\core\Libraries::add()
  404. * @see lithium\core\Libraries::path()
  405. * @param string $class The fully-namespaced (where applicable) name of the class to load.
  406. * @param boolean $require Specifies whether the class must be loaded or considered an
  407. * exception. Defaults to `false`.
  408. * @return void
  409. */
  410. public static function load($class, $require = false) {
  411. $path = isset(static::$_cachedPaths[$class]) ? static::$_cachedPaths[$class] : null;
  412. $path = $path ?: static::path($class);
  413. if ($path && include $path) {
  414. static::$_cachedPaths[$class] = $path;
  415. method_exists($class, '__init') ? $class::__init() : null;
  416. } elseif ($require) {
  417. throw new RuntimeException("Failed to load {$class} from {$path}");
  418. }
  419. }
  420. /**
  421. * Get the corresponding physical file path for a class or namespace name.
  422. *
  423. * @param string $class The class name to locate the physical file for. If `$options['dirs']` is
  424. * set to `true`, `$class` may also be a namespace name, in which case the corresponding
  425. * directory will be located.
  426. * @param array $options Options for converting `$class` to a phyiscal path:
  427. * - `'dirs'`: Defaults to `false`. If `true`, will attempt to case-sensitively look up
  428. * directories in addition to files (in which case `$class` is assumed to actually be a
  429. * namespace).
  430. * @return string Returns the absolute path to the file containing `$class`, or `null` if the
  431. * file cannot be found.
  432. */
  433. public static function path($class, array $options = array()) {
  434. $defaults = array('dirs' => false);
  435. $options += $defaults;
  436. $class = ltrim($class, '\\');
  437. if (isset(static::$_cachedPaths[$class]) && !$options['dirs']) {
  438. return static::$_cachedPaths[$class];
  439. }
  440. foreach (static::$_configurations as $name => $config) {
  441. $params = $options + $config;
  442. $suffix = $params['suffix'];
  443. if ($params['prefix'] && strpos($class, $params['prefix']) !== 0) {
  444. continue;
  445. }
  446. if ($transform = $params['transform']) {
  447. if ($file = static::_transformPath($transform, $class, $params)) {
  448. return $file;
  449. }
  450. continue;
  451. }
  452. $path = str_replace("\\", '/', substr($class, strlen($params['prefix'])));
  453. $fullPath = "{$params['path']}/{$path}";
  454. if (!$options['dirs']) {
  455. return static::$_cachedPaths[$class] = realpath($fullPath . $suffix);
  456. }
  457. $list = glob(dirname($fullPath) . '/*');
  458. $list = array_map(function($i) { return str_replace('\\', '/', $i); }, $list);
  459. if (in_array($fullPath . $suffix, $list)) {
  460. return static::$_cachedPaths[$class] = realpath($fullPath . $suffix);
  461. }
  462. return is_dir($fullPath) ? realpath($fullPath) : null;
  463. }
  464. }
  465. /**
  466. * Handles the conversion of a class name to a file name using a custom transformation typically
  467. * defined in the `'transform'` key of a configuration defined through `Libraries::add()`.
  468. *
  469. * The transformation can either be a closure which receives two parameters (the class name
  470. * as a string, and the library configuration as an array), or an array with two values (one
  471. * being the pattern to match, the other being the replacement).
  472. *
  473. * @see lithium\core\Libraries::add()
  474. * @see lithium\core\Libraries::path()
  475. * @param mixed $transform Either a closure or an array containing a regular expression match
  476. * and replacement. If the closure returns an empty value, or the regular
  477. * expression fails to match, will return `null`.
  478. * @param string $class The class name which is attempting to be mapped to a file.
  479. * @param array $options The configuration of the library as passed to `Libraries::add()`, along
  480. * with any options specified in the call to `Libraries::path()`.
  481. * @return string Returns transformed path of a class to a file, or `null` if the transformation
  482. * did not match.
  483. */
  484. protected static function _transformPath($transform, $class, array $options = array()) {
  485. if ((is_callable($transform)) && $file = $transform($class, $options)) {
  486. return $file;
  487. }
  488. if (is_array($transform)) {
  489. list($match, $replace) = $transform;
  490. return preg_replace($match, $replace, $class) ?: null;
  491. }
  492. }
  493. /**
  494. * Uses service location (i.e. `Libraries::locate()`) to look up a named class of a particular
  495. * type, and creates an instance of it, and passes an array of parameters to the constructor.
  496. *
  497. * If the given class can't be found, an exception is thrown.
  498. *
  499. * @param string $type The type of class as defined by `Libraries::$_paths`.
  500. * @param string $name The un-namespaced name of the class to instantiate.
  501. * @param array $options An array of constructor parameters to pass to the class.
  502. * @return object If the class is found, returns an instance of it, otherwise throws an
  503. * exception.
  504. * @throws lithium\core\ClassNotFoundException Throws an exception if the class can't be found.
  505. */
  506. public static function instance($type, $name, array $options = array()) {
  507. if (!$class = (string) static::locate($type, $name)) {
  508. throw new ClassNotFoundException("Class '{$name}' of type '{$type}' not found.");
  509. }
  510. return class_exists($class) ? new $class($options) : null;
  511. }
  512. /**
  513. * Performs service location for an object of a specific type. If `$name` is a string, finds the
  514. * first instance of a class with the given name in any registered library (i.e. apps, plugins
  515. * or vendor libraries registered via `Libraries::add()`), based on each library's order of
  516. * precedence. For example, this will find the first model called `File` in any plugin or class
  517. * library loaded into an application, including the application itself.
  518. *
  519. * {{{Libraries::locate('models', 'File');}}}
  520. *
  521. * Order of precedence is usually based on the order in which the library was registered (via
  522. * `Libraries::add()`), unless the library was registered with the `'defer'` option set to
  523. * `true`. All libraries with the `'defer'` option set will be searched in
  524. * registration-order **after** searching all libraries **without** `'defer'` set. This means
  525. * that in the above example, if an app and a plugin both have a model named `File`, then the
  526. * model from the app will be returned first, assuming the app was registered first (and
  527. * assuming the default settings).
  528. *
  529. * If `$name` is not specified, `locate()` returns an array with all classes of the specified
  530. * type which can be found. By default, `locate()` searches all registered libraries.
  531. *
  532. * {{{Libraries::locate('models');}}}
  533. *
  534. * For example, the above will return an array of all model classes in all registered plugins
  535. * and libraries (including the app itself).
  536. *
  537. * To learn more about adding and modifying the class paths used with `locate()`, see the
  538. * documentation for the `paths()` method.
  539. *
  540. * @see lithium\core\Libraries::paths()
  541. * @see lithium\core\Libraries::add()
  542. * @see lithium\core\Libraries::_locateDeferred()
  543. * @param string $type The type of class to search for. Typically follows the name of the
  544. * directory in which the class is stored, i.e. `'models'`, `'controllers'` or
  545. * `'adapter'`. Some classes types, such as adapters, will require a greater
  546. * degree of specificity when looking up the desired class. In this case, the dot
  547. * syntax is used, as in this example when looking up cache adapters:
  548. * `'adapter.storage.cache'`, or this example, when looking up authentication
  549. * adapters: `'adapter.security.auth'`.
  550. * @param string $name The base name (without namespace) of the class you wish to locate. If
  551. * unspecified, `locate()` will attempt to find all classes of the type specified
  552. * in `$type`. If you only wish to search for classes within a single plugin or
  553. * library, you may use the dot syntax to prefix the class name with the library
  554. * name, i.e. `'app.Post'`, which will only look for a `Post` model within the
  555. * app itself.
  556. * @param array $options The options to use when searching and returning class names.
  557. * - `'type'` _string_: Defaults to `'class'`. If set to `'file'`, returns file
  558. * names instead of class names.
  559. * - `'library'` _string_: When specified, only the given library/plugin name will
  560. * be searched.
  561. * @return mixed If `$name` is specified, returns the name of the first class found that matches
  562. * `$name` and `$type`, or returns `null` if no matching classes were found in any
  563. * registered library. If `$name` is not specified, returns an array of all classes
  564. * found which match `$type`.
  565. */
  566. public static function locate($type, $name = null, array $options = array()) {
  567. $defaults = array('type' => 'class');
  568. $options += $defaults;
  569. if (is_object($name) || strpos($name, '\\') !== false) {
  570. return $name;
  571. }
  572. $ident = $name ? ($type . '.' . $name) : ($type . '.*');
  573. if (isset(static::$_cachedPaths[$ident])) {
  574. return static::$_cachedPaths[$ident];
  575. }
  576. $params = static::_params($type, $name);
  577. extract($params);
  578. if (!isset(static::$_paths[$type])) {
  579. return null;
  580. }
  581. if (!$name) {
  582. $result = static::_locateAll(array('name' => '*') + $params, $options);
  583. return (static::$_cachedPaths[$ident] = $result);
  584. }
  585. $paths = (array) static::$_paths[$type];
  586. if (strpos($name, '.')) {
  587. list($params['library'], $params['name']) = explode('.', $name);
  588. $params['library'][0] = strtolower($params['library'][0]);
  589. $result = static::_locateDeferred(null, $paths, $params, $options + array(
  590. 'library' => $params['library']
  591. ));
  592. return static::$_cachedPaths[$ident] = $result;
  593. }
  594. foreach (array(false, true) as $defer) {
  595. if ($result = static::_locateDeferred($defer, $paths, $params, $options)) {
  596. return (static::$_cachedPaths[$ident] = $result);
  597. }
  598. }
  599. }
  600. /**
  601. * Returns or sets the the class path cache used for mapping class names to file paths, or
  602. * locating classes using `Libraries::locate()`.
  603. *
  604. * @param array $cache An array of keys and values to use when pre-populating the cache. Keys
  605. * are either class names (which match to file paths as values), or dot-separated
  606. * lookup paths used by `locate()` (which matches to either a single class or an
  607. * array of classes). If `false`, the cache is cleared.
  608. * @return array Returns an array of cached class lookups, formatted per the description for
  609. * `$cache`.
  610. */
  611. public static function cache($cache = null) {
  612. if ($cache === false) {
  613. static::$_cachedPaths = array();
  614. }
  615. if (is_array($cache)) {
  616. static::$_cachedPaths += $cache;
  617. }
  618. return static::$_cachedPaths;
  619. }
  620. /**
  621. * Performs service location lookups by library, based on the library's `'defer'` flag.
  622. * Libraries with `'defer'` set to `true` will be searched last when looking up services.
  623. *
  624. * @see lithium\core\Libraries::$_paths
  625. * @see lithium\core\Libraries::locate()
  626. * @param boolean $defer A boolean flag indicating which libraries to search, either the ones
  627. * with the `'defer'` flag set, or the ones without.
  628. * @param array $paths List of paths to be searched for the given service (class). These are
  629. * defined in `lithium\core\Libraries::$_paths`, and are organized by class type.
  630. * @param array $params The list of insert parameters to be injected into each path format
  631. * string when searching for classes.
  632. * @param array $options
  633. * @return string Returns a class path as a string if a given class is found, or null if no
  634. * class in any path matching any of the parameters is located.
  635. */
  636. protected static function _locateDeferred($defer, $paths, $params, array $options = array()) {
  637. if (isset($options['library'])) {
  638. $libraries = static::get((array) $options['library']);
  639. } else {
  640. $libraries = static::$_configurations;
  641. }
  642. foreach ($libraries as $library => $config) {
  643. if ($config['defer'] !== $defer && $defer !== null) {
  644. continue;
  645. }
  646. foreach (static::_searchPaths($paths, $library, $params) as $tpl) {
  647. $params['library'] = $library;
  648. $class = str_replace('\\*', '', String::insert($tpl, $params));
  649. if (file_exists($file = Libraries::path($class, $options))) {
  650. return ($options['type'] === 'file') ? $file : $class;
  651. }
  652. }
  653. }
  654. }
  655. /**
  656. * Returns the list of valid search path templates for the given service location lookup.
  657. *
  658. * @see lithium\core\Libraries::$_paths
  659. * @see lithium\core\Libraries::_search()
  660. * @param array $paths The list of all possible path templates from `Libraries::$_paths`.
  661. * @param string $library The name of the library being searched.
  662. * @param array $params The parameters used in the service location lookup.
  663. * @return array Returns an array of valid path template strings.
  664. */
  665. protected static function _searchPaths($paths, $library, $params) {
  666. $result = array();
  667. $params = array('library' => null, 'type' => null) + $params;
  668. foreach ($paths as $tpl => $opts) {
  669. if (is_int($tpl)) {
  670. $tpl = $opts;
  671. $opts = array();
  672. }
  673. if (isset($opts['libraries']) && !in_array($library, (array) $opts['libraries'])) {
  674. continue;
  675. }
  676. foreach ($params as $key => $value) {
  677. if (($value && $value !== '*') && strpos($tpl, "{:{$key}}") === false) {
  678. continue 2;
  679. }
  680. }
  681. $result[] = $tpl;
  682. }
  683. return $result;
  684. }
  685. /**
  686. * Locates all possible classes for given set of parameters.
  687. *
  688. * @param array $params
  689. * @param array $options
  690. * @return array
  691. */
  692. protected static function _locateAll(array $params, array $options = array()) {
  693. $defaults = array('libraries' => null, 'recursive' => true, 'namespaces' => false);
  694. $options += $defaults;
  695. $paths = (array) static::$_paths[$params['type']];
  696. $libraries = static::get($options['libraries'] ? (array) $options['libraries'] : null);
  697. $flags = array('escape' => '/');
  698. $classes = array();
  699. foreach ($libraries as $library => $config) {
  700. $params['library'] = $config['path'];
  701. foreach (static::_searchPaths($paths, $library, $params) as $tpl) {
  702. $options['path'] = str_replace('\\', '/', String::insert($tpl, $params, $flags));
  703. $classes = array_merge($classes, static::_search($config, $options));
  704. }
  705. }
  706. return array_unique($classes);
  707. }
  708. /**
  709. * Helper function for returning known paths given a certain type.
  710. *
  711. * @see lithium\core\Libraries::$_paths
  712. * @param string $type Path type (specified in `Libraries::$_paths`).
  713. * @param string $params Path parameters.
  714. * @return string Valid path name.
  715. */
  716. protected static function _locatePath($type, $params) {
  717. if (!isset(static::$_paths[$type])) {
  718. return;
  719. }
  720. $params += array('app' => LITHIUM_APP_PATH, 'root' => LITHIUM_LIBRARY_PATH);
  721. foreach (static::$_paths[$type] as $path) {
  722. if (is_dir($path = str_replace('\\', '/', String::insert($path, $params)))) {
  723. return $path;
  724. }
  725. }
  726. }
  727. /**
  728. * Search file system.
  729. *
  730. * @param string $config
  731. * @param string $options
  732. * @param string $name
  733. * @return array
  734. */
  735. protected static function _search($config, $options, $name = null) {
  736. $defaults = array(
  737. 'path' => null,
  738. 'suffix' => null,
  739. 'namespaces' => false,
  740. 'recursive' => false,
  741. 'preFilter' => '/[A-Z][A-Za-z0-9]+\./',
  742. 'filter' => false,
  743. 'exclude' => false,
  744. 'format' => function ($file, $config) {
  745. $trim = array(strlen($config['path']) + 1, strlen($config['suffix']));
  746. $file = substr($file, $trim[0], -$trim[1]);
  747. return $config['prefix'] . str_replace('/', '\\', $file);
  748. }
  749. );
  750. $options += $defaults;
  751. $path = $options['path'];
  752. $suffix = $options['namespaces'] ? '' : $config['suffix'];
  753. $suffix = ($options['suffix'] === null) ? $suffix : $options['suffix'];
  754. $dFlags = GLOB_ONLYDIR;
  755. $libs = (array) glob($path . $suffix, $options['namespaces'] ? $dFlags : 0);
  756. if ($options['recursive']) {
  757. list($current, $match) = explode('/*', $path, 2);
  758. $dirs = $queue = array_diff((array) glob($current . '/*', $dFlags), $libs);
  759. $match = str_replace('##', '.+', preg_quote(str_replace('*', '##', $match), '/'));
  760. $match = '/' . $match . preg_quote($suffix, '/') . '$/';
  761. while ($queue) {
  762. if (!is_dir($dir = array_pop($queue))) {
  763. continue;
  764. }
  765. $libs = array_merge($libs, (array) glob("{$dir}/*{$suffix}"));
  766. $queue = array_merge($queue, array_diff((array) glob("{$dir}/*", $dFlags), $libs));
  767. }
  768. $libs = preg_grep($match, $libs);
  769. }
  770. if ($suffix) {
  771. $libs = $options['preFilter'] ? preg_grep($options['preFilter'], $libs) : $libs;
  772. }
  773. return static::_filter($libs, $config, $options + compact('name'));
  774. }
  775. /**
  776. * Filters a list of library search results by the given set of options.
  777. *
  778. * @param array $libs List of found libraries.
  779. * @param array $config The configuration of the library currently being searched within.
  780. * @param array $options The options used to filter/format `$libs`.
  781. * @return array Returns a copy of `$libs`, filtered and transformed based on the configuration
  782. * provided in `$options`.
  783. */
  784. protected static function _filter($libs, array $config, array $options = array()) {
  785. if (is_callable($options['format'])) {
  786. foreach ($libs as $i => $file) {
  787. $libs[$i] = $options['format']($file, $config);
  788. }
  789. $libs = $options['name'] ? preg_grep("/{$options['name']}$/", $libs) : $libs;
  790. }
  791. if ($exclude = $options['exclude']) {
  792. if (is_string($exclude)) {
  793. $libs = preg_grep($exclude, $libs, PREG_GREP_INVERT);
  794. } elseif (is_callable($exclude)) {
  795. $libs = array_values(array_filter($libs, $exclude));
  796. }
  797. }
  798. if ($filter = $options['filter']) {
  799. if (is_string($filter)) {
  800. $libs = preg_grep($filter, $libs) ;
  801. } elseif (is_callable($filter)) {
  802. $libs = array_filter(array_map($filter, $libs));
  803. }
  804. }
  805. return $libs;
  806. }
  807. /**
  808. * Get params from type.
  809. *
  810. * @param string $type
  811. * @param string $name default: '*'
  812. * @return array type, namespace, class, name
  813. */
  814. protected static function _params($type, $name = "*") {
  815. $namespace = $class = '*';
  816. if (strpos($type, '.')) {
  817. $parts = explode('.', $type);
  818. $type = array_shift($parts);
  819. switch (count($parts)) {
  820. case 1:
  821. list($class) = $parts;
  822. break;
  823. case 2:
  824. list($namespace, $class) = $parts;
  825. break;
  826. default:
  827. $class = array_pop($parts);
  828. $namespace = join('\\', $parts);
  829. break;
  830. }
  831. }
  832. return compact('type', 'namespace', 'class', 'name');
  833. }
  834. }
  835. if (!defined('LITHIUM_LIBRARY_PATH')) {
  836. define('LITHIUM_LIBRARY_PATH', dirname(dirname(__DIR__)));
  837. }
  838. if (!defined('LITHIUM_APP_PATH')) {
  839. define('LITHIUM_APP_PATH', dirname(LITHIUM_LIBRARY_PATH) . '/app');
  840. }
  841. ?>