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')` will load the DebugKit plugin and will not load any bootstrap nor route files
41: * `CakePlugin::load('DebugKit', array('bootstrap' => true, 'routes' => true))` will load the bootstrap.php and routes.php files
42: * `CakePlugin::load('DebugKit', array('bootstrap' => false, 'routes' => true))` will load routes.php file but not bootstrap.php
43: * `CakePlugin::load('DebugKit', array('bootstrap' => array('config1', 'config2')))` will load config1.php and config2.php files
44: * `CakePlugin::load('DebugKit', array('bootstrap' => 'aCallableMethod'))` will run the aCallableMethod function to initialize it
45: *
46: * Bootstrap initialization functions can be expressed as a PHP callback type, including closures. Callbacks will receive two
47: * parameters (plugin name, plugin configuration)
48: *
49: * It is also possible to load multiple plugins at once. Examples:
50: *
51: * `CakePlugin::load(array('DebugKit', 'ApiGenerator'))` will load the DebugKit and ApiGenerator plugins
52: * `CakePlugin::load(array('DebugKit', 'ApiGenerator'), array('bootstrap' => true))` will load bootstrap file for both plugins
53: *
54: * {{{
55: * CakePlugin::load(array(
56: * 'DebugKit' => array('routes' => true),
57: * 'ApiGenerator'
58: * ), array('bootstrap' => true))
59: * }}}
60: *
61: * Will only load the bootstrap for ApiGenerator and only the routes for DebugKit
62: *
63: * @param string|array $plugin name of the plugin to be loaded in CamelCase format or array or plugins to load
64: * @param array $config configuration options for the plugin
65: * @throws MissingPluginException if the folder for the plugin to be loaded is not found
66: * @return void
67: */
68: public static function load($plugin, $config = array()) {
69: if (is_array($plugin)) {
70: foreach ($plugin as $name => $conf) {
71: list($name, $conf) = (is_numeric($name)) ? array($conf, $config) : array($name, $conf);
72: self::load($name, $conf);
73: }
74: return;
75: }
76: $config += array('bootstrap' => false, 'routes' => false, 'ignoreMissing' => false);
77: if (empty($config['path'])) {
78: foreach (App::path('plugins') as $path) {
79: if (is_dir($path . $plugin)) {
80: self::$_plugins[$plugin] = $config + array('path' => $path . $plugin . DS);
81: break;
82: }
83:
84: //Backwards compatibility to make easier to migrate to 2.0
85: $underscored = Inflector::underscore($plugin);
86: if (is_dir($path . $underscored)) {
87: self::$_plugins[$plugin] = $config + array('path' => $path . $underscored . DS);
88: break;
89: }
90: }
91: } else {
92: self::$_plugins[$plugin] = $config;
93: }
94:
95: if (empty(self::$_plugins[$plugin]['path'])) {
96: throw new MissingPluginException(array('plugin' => $plugin));
97: }
98: if (!empty(self::$_plugins[$plugin]['bootstrap'])) {
99: self::bootstrap($plugin);
100: }
101: }
102:
103: /**
104: * Will load all the plugins located in the configured plugins folders
105: * If passed an options array, it will be used as a common default for all plugins to be loaded
106: * It is possible to set specific defaults for each plugins in the options array. Examples:
107: *
108: * {{{
109: * CakePlugin::loadAll(array(
110: * array('bootstrap' => true),
111: * 'DebugKit' => array('routes' => true, 'bootstrap' => false),
112: * ))
113: * }}}
114: *
115: * The above example will load the bootstrap file for all plugins, but for DebugKit it will only load
116: * the routes file and will not look for any bootstrap script.
117: *
118: * @param array $options Options list. See CakePlugin::load() for valid options.
119: * @return void
120: */
121: public static function loadAll($options = array()) {
122: $plugins = App::objects('plugins');
123: foreach ($plugins as $p) {
124: $opts = isset($options[$p]) ? (array)$options[$p] : array();
125: if (isset($options[0])) {
126: $opts += $options[0];
127: }
128: self::load($p, $opts);
129: }
130: }
131:
132: /**
133: * Returns the filesystem path for a plugin
134: *
135: * @param string $plugin name of the plugin in CamelCase format
136: * @return string path to the plugin folder
137: * @throws MissingPluginException if the folder for plugin was not found or plugin has not been loaded
138: */
139: public static function path($plugin) {
140: if (empty(self::$_plugins[$plugin])) {
141: throw new MissingPluginException(array('plugin' => $plugin));
142: }
143: return self::$_plugins[$plugin]['path'];
144: }
145:
146: /**
147: * Loads the bootstrapping files for a plugin, or calls the initialization setup in the configuration
148: *
149: * @param string $plugin name of the plugin
150: * @return mixed
151: * @see CakePlugin::load() for examples of bootstrap configuration
152: */
153: public static function bootstrap($plugin) {
154: $config = self::$_plugins[$plugin];
155: if ($config['bootstrap'] === false) {
156: return false;
157: }
158: if (is_callable($config['bootstrap'])) {
159: return call_user_func_array($config['bootstrap'], array($plugin, $config));
160: }
161:
162: $path = self::path($plugin);
163: if ($config['bootstrap'] === true) {
164: return self::_includeFile(
165: $path . 'Config' . DS . 'bootstrap.php',
166: $config['ignoreMissing']
167: );
168: }
169:
170: $bootstrap = (array)$config['bootstrap'];
171: foreach ($bootstrap as $file) {
172: self::_includeFile(
173: $path . 'Config' . DS . $file . '.php',
174: $config['ignoreMissing']
175: );
176: }
177:
178: return true;
179: }
180:
181: /**
182: * Loads the routes file for a plugin, or all plugins configured to load their respective routes file
183: *
184: * @param string $plugin name of the plugin, if null will operate on all plugins having enabled the
185: * loading of routes files
186: * @return bool
187: */
188: public static function routes($plugin = null) {
189: if ($plugin === null) {
190: foreach (self::loaded() as $p) {
191: self::routes($p);
192: }
193: return true;
194: }
195: $config = self::$_plugins[$plugin];
196: if ($config['routes'] === false) {
197: return false;
198: }
199: return (bool)self::_includeFile(
200: self::path($plugin) . 'Config' . DS . 'routes.php',
201: $config['ignoreMissing']
202: );
203: }
204:
205: /**
206: * Returns true if the plugin $plugin is already loaded
207: * If plugin is null, it will return a list of all loaded plugins
208: *
209: * @param string $plugin Plugin name to check.
210: * @return mixed boolean true if $plugin is already loaded.
211: * If $plugin is null, returns a list of plugins that have been loaded
212: */
213: public static function loaded($plugin = null) {
214: if ($plugin) {
215: return isset(self::$_plugins[$plugin]);
216: }
217: $return = array_keys(self::$_plugins);
218: sort($return);
219: return $return;
220: }
221:
222: /**
223: * Forgets a loaded plugin or all of them if first parameter is null
224: *
225: * @param string $plugin name of the plugin to forget
226: * @return void
227: */
228: public static function unload($plugin = null) {
229: if ($plugin === null) {
230: self::$_plugins = array();
231: } else {
232: unset(self::$_plugins[$plugin]);
233: }
234: }
235:
236: /**
237: * Include file, ignoring include error if needed if file is missing
238: *
239: * @param string $file File to include
240: * @param bool $ignoreMissing Whether to ignore include error for missing files
241: * @return mixed
242: */
243: protected static function _includeFile($file, $ignoreMissing = false) {
244: if ($ignoreMissing && !is_file($file)) {
245: return false;
246: }
247: return include $file;
248: }
249:
250: }
251: