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