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