1: <?php
2: /**
3: * CakePlugin class
4: *
5: * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
6: * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
7: *
8: * Licensed under The MIT License
9: * For full copyright and license information, please see the LICENSE.txt
10: * Redistributions of files must retain the above copyright notice.
11: *
12: * @copyright Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
13: * @link http://cakephp.org CakePHP(tm) Project
14: * @package Cake.Core
15: * @since CakePHP(tm) v 2.0.0
16: * @license http://www.opensource.org/licenses/mit-license.php MIT License
17: */
18:
19: /**
20: * CakePlugin is responsible for loading and unloading plugins. It also can
21: * retrieve plugin paths and load their bootstrap and routes files.
22: *
23: * @package Cake.Core
24: * @link http://book.cakephp.org/2.0/en/plugins.html
25: */
26: class CakePlugin {
27:
28: /**
29: * Holds a list of all loaded plugins and their configuration
30: *
31: * @var array
32: */
33: protected static $_plugins = array();
34:
35: /**
36: * Loads a plugin and optionally loads bootstrapping, routing files or loads an initialization function
37: *
38: * Examples:
39: *
40: * `CakePlugin::load('DebugKit')`
41: *
42: * Will load the DebugKit plugin and will not load any bootstrap nor route files
43: *
44: * `CakePlugin::load('DebugKit', array('bootstrap' => true, 'routes' => true))`
45: *
46: * will load the bootstrap.php and routes.php files
47: *
48: * `CakePlugin::load('DebugKit', array('bootstrap' => false, 'routes' => true))`
49: *
50: * will load routes.php file but not bootstrap.php
51: *
52: * `CakePlugin::load('DebugKit', array('bootstrap' => array('config1', 'config2')))`
53: *
54: * will load config1.php and config2.php files
55: *
56: * `CakePlugin::load('DebugKit', array('bootstrap' => 'aCallableMethod'))`
57: *
58: * will run the aCallableMethod function to initialize it
59: *
60: * Bootstrap initialization functions can be expressed as a PHP callback type,
61: * including closures. Callbacks will receive two parameters
62: * (plugin name, plugin configuration)
63: *
64: * It is also possible to load multiple plugins at once. Examples:
65: *
66: * `CakePlugin::load(array('DebugKit', 'ApiGenerator'))`
67: *
68: * will load the DebugKit and ApiGenerator plugins
69: *
70: * `CakePlugin::load(array('DebugKit', 'ApiGenerator'), array('bootstrap' => true))`
71: *
72: * will load bootstrap file for both plugins
73: *
74: * ```
75: * CakePlugin::load(array(
76: * 'DebugKit' => array('routes' => true),
77: * 'ApiGenerator'
78: * ), array('bootstrap' => true))
79: * ```
80: *
81: * Will only load the bootstrap for ApiGenerator and only the routes for DebugKit.
82: * By using the `path` option you can specify an absolute path to the plugin. Make
83: * sure that the path is slash terminated or your plugin will not be located properly.
84: *
85: * @param string|array $plugin name of the plugin to be loaded in CamelCase format or array or plugins to load
86: * @param array $config configuration options for the plugin
87: * @throws MissingPluginException if the folder for the plugin to be loaded is not found
88: * @return void
89: */
90: public static function load($plugin, $config = array()) {
91: if (is_array($plugin)) {
92: foreach ($plugin as $name => $conf) {
93: list($name, $conf) = (is_numeric($name)) ? array($conf, $config) : array($name, $conf);
94: self::load($name, $conf);
95: }
96: return;
97: }
98: $config += array('bootstrap' => false, 'routes' => false, 'ignoreMissing' => false);
99: if (empty($config['path'])) {
100: foreach (App::path('plugins') as $path) {
101: if (is_dir($path . $plugin)) {
102: self::$_plugins[$plugin] = $config + array('path' => $path . $plugin . DS);
103: break;
104: }
105:
106: //Backwards compatibility to make easier to migrate to 2.0
107: $underscored = Inflector::underscore($plugin);
108: if (is_dir($path . $underscored)) {
109: self::$_plugins[$plugin] = $config + array('path' => $path . $underscored . DS);
110: break;
111: }
112: }
113: } else {
114: self::$_plugins[$plugin] = $config;
115: }
116:
117: if (empty(self::$_plugins[$plugin]['path'])) {
118: throw new MissingPluginException(array('plugin' => $plugin));
119: }
120: if (!empty(self::$_plugins[$plugin]['bootstrap'])) {
121: self::bootstrap($plugin);
122: }
123: }
124:
125: /**
126: * Will load all the plugins located in the configured plugins folders
127: * If passed an options array, it will be used as a common default for all plugins to be loaded
128: * It is possible to set specific defaults for each plugins in the options array. Examples:
129: *
130: * ```
131: * CakePlugin::loadAll(array(
132: * array('bootstrap' => true),
133: * 'DebugKit' => array('routes' => true, 'bootstrap' => false),
134: * ))
135: * ```
136: *
137: * The above example will load the bootstrap file for all plugins, but for DebugKit it will only load
138: * the routes file and will not look for any bootstrap script. If you are loading
139: * many plugins that inconsistently support routes/bootstrap files, instead of detailing
140: * each plugin you can use the `ignoreMissing` option:
141: *
142: * ```
143: * CakePlugin::loadAll(array(
144: * 'ignoreMissing' => true,
145: * 'bootstrap' => true,
146: * 'routes' => true,
147: * ));
148: * ```
149: *
150: * The ignoreMissing option will do additional file_exists() calls but is simpler
151: * to use.
152: *
153: * @param array $options Options list. See CakePlugin::load() for valid options.
154: * @return void
155: */
156: public static function loadAll($options = array()) {
157: $plugins = App::objects('plugins');
158: foreach ($plugins as $p) {
159: $opts = isset($options[$p]) ? (array)$options[$p] : array();
160: if (isset($options[0])) {
161: $opts += $options[0];
162: }
163: self::load($p, $opts);
164: }
165: }
166:
167: /**
168: * Returns the filesystem path for a plugin
169: *
170: * @param string $plugin name of the plugin in CamelCase format
171: * @return string path to the plugin folder
172: * @throws MissingPluginException if the folder for plugin was not found or plugin has not been loaded
173: */
174: public static function path($plugin) {
175: if (empty(self::$_plugins[$plugin])) {
176: throw new MissingPluginException(array('plugin' => $plugin));
177: }
178: return self::$_plugins[$plugin]['path'];
179: }
180:
181: /**
182: * Loads the bootstrapping files for a plugin, or calls the initialization setup in the configuration
183: *
184: * @param string $plugin name of the plugin
185: * @return mixed
186: * @see CakePlugin::load() for examples of bootstrap configuration
187: */
188: public static function bootstrap($plugin) {
189: $config = self::$_plugins[$plugin];
190: if ($config['bootstrap'] === false) {
191: return false;
192: }
193: if (is_callable($config['bootstrap'])) {
194: return call_user_func_array($config['bootstrap'], array($plugin, $config));
195: }
196:
197: $path = self::path($plugin);
198: if ($config['bootstrap'] === true) {
199: return self::_includeFile(
200: $path . 'Config' . DS . 'bootstrap.php',
201: $config['ignoreMissing']
202: );
203: }
204:
205: $bootstrap = (array)$config['bootstrap'];
206: foreach ($bootstrap as $file) {
207: self::_includeFile(
208: $path . 'Config' . DS . $file . '.php',
209: $config['ignoreMissing']
210: );
211: }
212:
213: return true;
214: }
215:
216: /**
217: * Loads the routes file for a plugin, or all plugins configured to load their respective routes file
218: *
219: * @param string $plugin name of the plugin, if null will operate on all plugins having enabled the
220: * loading of routes files
221: * @return bool
222: */
223: public static function routes($plugin = null) {
224: if ($plugin === null) {
225: foreach (self::loaded() as $p) {
226: self::routes($p);
227: }
228: return true;
229: }
230: $config = self::$_plugins[$plugin];
231: if ($config['routes'] === false) {
232: return false;
233: }
234: return (bool)self::_includeFile(
235: self::path($plugin) . 'Config' . DS . 'routes.php',
236: $config['ignoreMissing']
237: );
238: }
239:
240: /**
241: * Returns true if the plugin $plugin is already loaded
242: * If plugin is null, it will return a list of all loaded plugins
243: *
244: * @param string $plugin Plugin name to check.
245: * @return mixed boolean true if $plugin is already loaded.
246: * If $plugin is null, returns a list of plugins that have been loaded
247: */
248: public static function loaded($plugin = null) {
249: if ($plugin) {
250: return isset(self::$_plugins[$plugin]);
251: }
252: $return = array_keys(self::$_plugins);
253: sort($return);
254: return $return;
255: }
256:
257: /**
258: * Forgets a loaded plugin or all of them if first parameter is null
259: *
260: * @param string $plugin name of the plugin to forget
261: * @return void
262: */
263: public static function unload($plugin = null) {
264: if ($plugin === null) {
265: self::$_plugins = array();
266: } else {
267: unset(self::$_plugins[$plugin]);
268: }
269: }
270:
271: /**
272: * Include file, ignoring include error if needed if file is missing
273: *
274: * @param string $file File to include
275: * @param bool $ignoreMissing Whether to ignore include error for missing files
276: * @return mixed
277: */
278: protected static function _includeFile($file, $ignoreMissing = false) {
279: if ($ignoreMissing && !is_file($file)) {
280: return false;
281: }
282: return include $file;
283: }
284:
285: }
286: