plugins.inc 32 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917
  1. <?php
  2. /**
  3. * @file
  4. *
  5. * Contains routines to organize and load plugins. It allows a special
  6. * variation of the hook system so that plugins can be kept in separate
  7. * .inc files, and can be either loaded all at once or loaded only when
  8. * necessary.
  9. */
  10. /**
  11. * Get an array of information about modules that support an API.
  12. *
  13. * This will ask each module if they support the given API, and if they do
  14. * it will return an array of information about the modules that do.
  15. *
  16. * This function invokes hook_ctools_api. This invocation is statically
  17. * cached, so feel free to call it as often per page run as you like, it
  18. * will cost very little.
  19. *
  20. * This function can be used as an alternative to module_implements and can
  21. * thus be used to find a precise list of modules that not only support
  22. * a given hook (aka 'api') but also restrict to only modules that use
  23. * the given version. This will allow multiple modules moving at different
  24. * paces to still be able to work together and, in the event of a mismatch,
  25. * either fall back to older behaviors or simply cease loading, which is
  26. * still better than a crash.
  27. *
  28. * @param $owner
  29. * The name of the module that controls the API.
  30. * @param $api
  31. * The name of the api. The api name forms the file name:
  32. * $module.$api.inc
  33. * @param $minimum_version
  34. * The lowest version API that is compatible with this one. If a module
  35. * reports its API as older than this, its files will not be loaded. This
  36. * should never change during operation.
  37. * @param $current_version
  38. * The current version of the api. If a module reports its minimum API as
  39. * higher than this, its files will not be loaded. This should never change
  40. * during operation.
  41. *
  42. * @return
  43. * An array of API information, keyed by module. Each module's information will
  44. * contain:
  45. * - 'version': The version of the API required by the module. The module
  46. * should use the lowest number it can support so that the widest range
  47. * of supported versions can be used.
  48. * - 'path': If not provided, this will be the module's path. This is
  49. * where the module will store any subsidiary files. This differs from
  50. * plugin paths which are figured separately.
  51. *
  52. * APIs can request any other information to be placed here that they might
  53. * need. This should be in the documentation for that particular API.
  54. */
  55. function ctools_plugin_api_info($owner, $api, $minimum_version, $current_version) {
  56. $cache = &drupal_static(__FUNCTION__, array());
  57. if (!isset($cache[$owner][$api])) {
  58. $cache[$owner][$api] = array();
  59. $hook = ctools_plugin_api_get_hook($owner, $api);
  60. foreach (module_implements($hook) as $module) {
  61. $function = $module . '_' . $hook;
  62. $info = $function($owner, $api);
  63. $version = NULL;
  64. // This is added to make hook_views_api() compatible with this, since
  65. // views used a different version key.
  66. if (isset($info['version'])) {
  67. $version = $info['version'];
  68. }
  69. else if (isset($info['api'])) {
  70. $version = $info['api'];
  71. }
  72. if (!isset($version)) {
  73. continue;
  74. }
  75. // Only process if version is between minimum and current, inclusive.
  76. if (($version == $minimum_version) || ($version == $current_version)
  77. || (version_compare($version, $minimum_version, '>=')
  78. && version_compare($version, $current_version, '<='))) {
  79. if (!isset($info['path'])) {
  80. $info['path'] = drupal_get_path('module', $module);
  81. }
  82. $cache[$owner][$api][$module] = $info;
  83. }
  84. }
  85. // And allow themes to implement these as well.
  86. $themes = _ctools_list_themes();
  87. foreach ($themes as $name => $theme) {
  88. if (!empty($theme->info['api'][$owner][$api])) {
  89. $info = $theme->info['api'][$owner][$api];
  90. if (!isset($info['version'])) {
  91. continue;
  92. }
  93. // Only process if version is between minimum and current, inclusive.
  94. if (version_compare($info['version'], $minimum_version, '>=') && version_compare($info['version'], $current_version, '<=')) {
  95. if (!isset($info['path'])) {
  96. $info['path'] = '';
  97. }
  98. // Because themes can't easily specify full path, we add it here
  99. // even though we do not for modules:
  100. $info['path'] = drupal_get_path('theme', $name) . '/' . $info['path'];
  101. $cache[$owner][$api][$name] = $info;
  102. }
  103. }
  104. }
  105. // Allow other modules to hook in.
  106. drupal_alter($hook, $cache[$owner][$api], $owner, $api);
  107. }
  108. return $cache[$owner][$api];
  109. }
  110. /**
  111. * Load a group of API files.
  112. *
  113. * This will ask each module if they support the given API, and if they do
  114. * it will load the specified file name. The API and the file name
  115. * coincide by design.
  116. *
  117. * @param $owner
  118. * The name of the module that controls the API.
  119. * @param $api
  120. * The name of the api. The api name forms the file name:
  121. * $module.$api.inc, though this can be overridden by the module's response.
  122. * @param $minimum_version
  123. * The lowest version API that is compatible with this one. If a module
  124. * reports its API as older than this, its files will not be loaded. This
  125. * should never change during operation.
  126. * @param $current_version
  127. * The current version of the api. If a module reports its minimum API as
  128. * higher than this, its files will not be loaded. This should never change
  129. * during operation.
  130. *
  131. * @return
  132. * The API information, in case you need it.
  133. */
  134. function ctools_plugin_api_include($owner, $api, $minimum_version, $current_version) {
  135. static $already_done = array();
  136. $info = ctools_plugin_api_info($owner, $api, $minimum_version, $current_version);
  137. foreach ($info as $module => $plugin_info) {
  138. if (!isset($already_done[$owner][$api][$module])) {
  139. if (isset($plugin_info["$api file"])) {
  140. $file = $plugin_info["$api file"];
  141. }
  142. else if (isset($plugin_info['file'])) {
  143. $file = $plugin_info['file'];
  144. }
  145. else {
  146. $file = "$module.$api.inc";
  147. }
  148. if (file_exists(DRUPAL_ROOT . "/$plugin_info[path]/$file")) {
  149. require_once DRUPAL_ROOT . "/$plugin_info[path]/$file";
  150. }
  151. else if (file_exists(DRUPAL_ROOT . "/$file")) {
  152. require_once DRUPAL_ROOT . "/$file";
  153. }
  154. $already_done[$owner][$api][$module] = TRUE;
  155. }
  156. }
  157. return $info;
  158. }
  159. /**
  160. * Find out what hook to use to determine if modules support an API.
  161. *
  162. * By default, most APIs will use hook_ctools_plugin_api, but some modules
  163. * want sole ownership. This technique lets modules define what hook
  164. * to use.
  165. */
  166. function ctools_plugin_api_get_hook($owner, $api) {
  167. // Allow modules to use their own hook for this. The only easy way to do
  168. // this right now is with a magically named function.
  169. if (function_exists($function = $owner . '_' . $api . '_hook_name')) {
  170. $hook = $function();
  171. }
  172. else if (function_exists($function = $owner . '_ctools_plugin_api_hook_name')) {
  173. $hook = $function();
  174. }
  175. // Do this last so that if the $function above failed to return, we have a
  176. // sane default.
  177. if (empty($hook)) {
  178. $hook = 'ctools_plugin_api';
  179. }
  180. return $hook;
  181. }
  182. /**
  183. * Fetch a group of plugins by name.
  184. *
  185. * @param $module
  186. * The name of the module that utilizes this plugin system. It will be
  187. * used to call hook_ctools_plugin_$plugin() to get more data about the plugin.
  188. * @param $type
  189. * The type identifier of the plugin.
  190. * @param $id
  191. * If specified, return only information about plugin with this identifier.
  192. * The system will do its utmost to load only plugins with this id.
  193. *
  194. * @return
  195. * An array of information arrays about the plugins received. The contents
  196. * of the array are specific to the plugin.
  197. */
  198. function ctools_get_plugins($module, $type, $id = NULL) {
  199. // Store local caches of plugins and plugin info so we don't have to do full
  200. // lookups every time.
  201. static $drupal_static_fast;
  202. if (!isset($drupal_static_fast)) {
  203. $drupal_static_fast['plugins'] = &drupal_static('ctools_plugins', array());
  204. }
  205. $plugins = &$drupal_static_fast['plugins'];
  206. $info = ctools_plugin_get_plugin_type_info();
  207. // Bail out noisily if an invalid module/type combination is requested.
  208. if (!isset($info[$module][$type])) {
  209. watchdog('ctools', 'Invalid plugin module/type combination requested: module @module and type @type', array('@module' => $module, '@type' => $type), WATCHDOG_ERROR);
  210. return array();
  211. }
  212. // Make sure our plugins array is populated.
  213. if (!isset($plugins[$module][$type])) {
  214. $plugins[$module][$type] = array();
  215. }
  216. // Attempt to shortcut this whole piece of code if we already have
  217. // the requested plugin:
  218. if ($id && array_key_exists($id, $plugins[$module][$type])) {
  219. return $plugins[$module][$type][$id];
  220. }
  221. // Store the status of plugin loading. If a module plugin type pair is true,
  222. // then it is fully loaded and no searching or setup needs to be done.
  223. $setup = &drupal_static('ctools_plugin_setup', array());
  224. // We assume we don't need to build a cache.
  225. $build_cache = FALSE;
  226. // If the plugin info says this can be cached, check cache first.
  227. if ($info[$module][$type]['cache'] && empty($setup[$module][$type])) {
  228. $cache = cache_get("plugins:$module:$type", $info[$module][$type]['cache table']);
  229. if (!empty($cache->data)) {
  230. // Cache load succeeded so use the cached plugin list.
  231. $plugins[$module][$type] = $cache->data;
  232. // Set $setup to true so we know things where loaded.
  233. $setup[$module][$type] = TRUE;
  234. }
  235. else {
  236. // Cache load failed so store that we need to build and write the cache.
  237. $build_cache = TRUE;
  238. }
  239. }
  240. // Always load all hooks if we need them. Note we only need them now if the
  241. // plugin asks for them. We can assume that if we have plugins we've already
  242. // called the global hook.
  243. if (!empty($info[$module][$type]['use hooks']) && empty($plugins[$module][$type])) {
  244. $plugins[$module][$type] = ctools_plugin_load_hooks($info[$module][$type]);
  245. }
  246. // Then see if we should load all files. We only do this if we
  247. // want a list of all plugins or there was a cache miss.
  248. if (empty($setup[$module][$type]) && ($build_cache || !$id)) {
  249. $setup[$module][$type] = TRUE;
  250. $plugins[$module][$type] = array_merge($plugins[$module][$type], ctools_plugin_load_includes($info[$module][$type]));
  251. // If the plugin can have child plugins, and we're loading all plugins,
  252. // go through the list of plugins we have and find child plugins.
  253. if (!$id && !empty($info[$module][$type]['child plugins'])) {
  254. // If a plugin supports children, go through each plugin and ask.
  255. $temp = array();
  256. foreach ($plugins[$module][$type] as $name => $plugin) {
  257. // The strpos ensures that we don't try to find children for plugins
  258. // that are already children.
  259. if (!empty($plugin['get children']) && function_exists($plugin['get children']) && strpos($name, ':') === FALSE) {
  260. $temp = array_merge($plugin['get children']($plugin, $name), $temp);
  261. }
  262. else {
  263. $temp[$name] = $plugin;
  264. }
  265. }
  266. $plugins[$module][$type] = $temp;
  267. }
  268. }
  269. // If we were told earlier that this is cacheable and the cache was
  270. // empty, give something back.
  271. if ($build_cache) {
  272. cache_set("plugins:$module:$type", $plugins[$module][$type], $info[$module][$type]['cache table']);
  273. }
  274. // If no id was requested, we are finished here:
  275. if (!$id) {
  276. // Use array_filter because looking for unknown plugins could cause NULL
  277. // entries to appear in the list later.
  278. return array_filter($plugins[$module][$type]);
  279. }
  280. // Check to see if we need to look for the file
  281. if (!array_key_exists($id, $plugins[$module][$type])) {
  282. // If we can have child plugins, check to see if the plugin name is in the
  283. // format of parent:child and break it up if it is.
  284. if (!empty($info[$module][$type]['child plugins']) && strpos($id, ':') !== FALSE) {
  285. list($parent, $child) = explode(':', $id, 2);
  286. }
  287. else {
  288. $parent = $id;
  289. }
  290. if (!array_key_exists($parent, $plugins[$module][$type])) {
  291. $result = ctools_plugin_load_includes($info[$module][$type], $parent);
  292. // Set to either what was returned or NULL.
  293. $plugins[$module][$type][$parent] = isset($result[$parent]) ? $result[$parent] : NULL;
  294. }
  295. // If we are looking for a child, and have the parent, ask the parent for the child.
  296. if (!empty($child) && !empty($plugins[$module][$type][$parent]) && function_exists($plugins[$module][$type][$parent]['get child'])) {
  297. $plugins[$module][$type][$id] = $plugins[$module][$type][$parent]['get child']($plugins[$module][$type][$parent], $parent, $child);
  298. }
  299. }
  300. // At this point we should either have the plugin, or a NULL.
  301. return $plugins[$module][$type][$id];
  302. }
  303. /**
  304. * Return the full list of plugin type info for all plugin types registered in
  305. * the current system.
  306. *
  307. * This function manages its own cache getting/setting, and should always be
  308. * used as the way to initially populate the list of plugin types. Make sure you
  309. * call this function to properly populate the ctools_plugin_type_info static
  310. * variable.
  311. *
  312. * @return array
  313. * A multilevel array of plugin type info, the outer array keyed on module
  314. * name and each inner array keyed on plugin type name.
  315. */
  316. function ctools_plugin_get_plugin_type_info($flush = FALSE) {
  317. static $drupal_static_fast;
  318. if (!isset($drupal_static_fast)) {
  319. $drupal_static_fast['info_loaded'] = &drupal_static('ctools_plugin_type_info_loaded', FALSE);
  320. $drupal_static_fast['all_type_info'] = &drupal_static('ctools_plugin_type_info', array());
  321. }
  322. $info_loaded = &$drupal_static_fast['info_loaded'];
  323. $all_type_info = &$drupal_static_fast['all_type_info'];
  324. // Only trigger info loading once.
  325. if ($info_loaded && !$flush) {
  326. return $all_type_info;
  327. }
  328. $info_loaded = TRUE;
  329. $cache = cache_get('ctools_plugin_type_info');
  330. if (!empty($cache->data) && !$flush) {
  331. // Plugin type info cache is warm, use it.
  332. $all_type_info = $cache->data;
  333. }
  334. else {
  335. // Cache expired, refill it.
  336. foreach (module_implements('ctools_plugin_type') as $module) {
  337. $module_infos = array();
  338. $function = $module . '_ctools_plugin_type';
  339. $module_infos = $function();
  340. foreach ($module_infos as $plugin_type_name => $plugin_type_info) {
  341. // Apply defaults. Array addition will not overwrite pre-existing keys.
  342. $plugin_type_info += array(
  343. 'module' => $module,
  344. 'type' => $plugin_type_name,
  345. 'cache' => FALSE,
  346. 'cache table' => 'cache',
  347. 'classes' => array(),
  348. 'use hooks' => FALSE,
  349. 'defaults' => array(),
  350. 'process' => '',
  351. 'alterable' => TRUE,
  352. 'extension' => 'inc',
  353. 'info file' => FALSE,
  354. 'hook' => $module . '_' . $plugin_type_name,
  355. 'load themes' => FALSE,
  356. );
  357. $all_type_info[$module][$plugin_type_name] = $plugin_type_info;
  358. }
  359. }
  360. cache_set('ctools_plugin_type_info', $all_type_info);
  361. }
  362. return $all_type_info;
  363. }
  364. /**
  365. * Reset all static caches that affect the result of ctools_get_plugins().
  366. */
  367. function ctools_get_plugins_reset() {
  368. drupal_static_reset('ctools_plugins');
  369. drupal_static_reset('ctools_plugin_setup');
  370. drupal_static_reset('ctools_plugin_load_includes');
  371. drupal_static_reset('ctools_plugin_api_info');
  372. }
  373. /**
  374. * Load plugins from a directory.
  375. *
  376. * @param $info
  377. * The plugin info as returned by ctools_plugin_get_info()
  378. * @param $file
  379. * The file to load if we're looking for just one particular plugin.
  380. *
  381. * @return
  382. * An array of information created for this plugin.
  383. */
  384. function ctools_plugin_load_includes($info, $filename = NULL) {
  385. // Keep a static array so we don't hit file_scan_directory more than necessary.
  386. $all_files = &drupal_static(__FUNCTION__, array());
  387. // store static of plugin arrays for reference because they can't be reincluded.
  388. static $plugin_arrays = array();
  389. if (!isset($all_files[$info['module']][$info['type']])) {
  390. $cache = cache_get("ctools_plugin_files:$info[module]:$info[type]");
  391. if ($cache) {
  392. $all_files[$info['module']][$info['type']] = $cache->data;
  393. }
  394. // Do not attempt any file scan even if the cached entry was empty.
  395. // A NULL entry here would mean the plugin just does not exists, and we
  396. // cannot afford to run file scan on production sites normal run.
  397. elseif (!isset($all_files[$info['module']][$info['type']])) {
  398. $all_files[$info['module']][$info['type']] = array();
  399. // Load all our plugins.
  400. $directories = ctools_plugin_get_directories($info);
  401. $extension = (empty($info['info file']) || ($info['extension'] != 'inc')) ? $info['extension'] : 'info';
  402. foreach ($directories as $module => $path) {
  403. $all_files[$info['module']][$info['type']][$module] = file_scan_directory($path, '/\.' . $extension . '$/', array('key' => 'name'));
  404. }
  405. cache_set("ctools_plugin_files:$info[module]:$info[type]", $all_files[$info['module']][$info['type']]);
  406. }
  407. }
  408. $file_list = $all_files[$info['module']][$info['type']];
  409. $plugins = array();
  410. // Iterate through all the plugin .inc files, load them and process the hook
  411. // that should now be available.
  412. foreach (array_filter($file_list) as $module => $files) {
  413. if ($filename) {
  414. $files = isset($files[$filename]) ? array($filename => $files[$filename]) : array();
  415. }
  416. foreach ($files as $file) {
  417. if (!empty($info['info file'])) {
  418. // Parse a .info file
  419. $result = ctools_plugin_process_info($info, $module, $file);
  420. }
  421. else {
  422. // Parse a hook.
  423. $plugin = NULL; // ensure that we don't have something leftover from earlier.
  424. if (isset($plugin_arrays[$file->uri])) {
  425. $identifier = $plugin_arrays[$file->uri];
  426. }
  427. else {
  428. require_once DRUPAL_ROOT . '/' . $file->uri;
  429. // .inc files have a special format for the hook identifier.
  430. // For example, 'foo.inc' in the module 'mogul' using the plugin
  431. // whose hook is named 'borg_type' should have a function named (deep breath)
  432. // mogul_foo_borg_type()
  433. // If, however, the .inc file set the quasi-global $plugin array, we
  434. // can use that and not even call a function. Set the $identifier
  435. // appropriately and ctools_plugin_process() will handle it.
  436. if (isset($plugin)) {
  437. $plugin_arrays[$file->uri] = $plugin;
  438. $identifier = $plugin;
  439. }
  440. else {
  441. $identifier = $module . '_' . $file->name;
  442. }
  443. }
  444. $result = ctools_plugin_process($info, $module, $identifier, dirname($file->uri), basename($file->uri), $file->name);
  445. }
  446. if (is_array($result)) {
  447. $plugins = array_merge($plugins, $result);
  448. }
  449. }
  450. }
  451. return $plugins;
  452. }
  453. /**
  454. * Get a list of directories to search for plugins of the given type.
  455. *
  456. * This utilizes hook_ctools_plugin_directory() to determine a complete list of
  457. * directories. Only modules that implement this hook and return a string
  458. * value will have their directories included.
  459. *
  460. * @param $info
  461. * The $info array for the plugin as returned by ctools_plugin_get_info().
  462. *
  463. * @return array $directories
  464. * An array of directories to search.
  465. */
  466. function ctools_plugin_get_directories($info) {
  467. $directories = array();
  468. foreach (module_implements('ctools_plugin_directory') as $module) {
  469. $function = $module . '_ctools_plugin_directory';
  470. $result = $function($info['module'], $info['type']);
  471. if ($result && is_string($result)) {
  472. $directories[$module] = drupal_get_path('module', $module) . '/' . $result;
  473. }
  474. }
  475. if (!empty($info['load themes'])) {
  476. $themes = _ctools_list_themes();
  477. foreach ($themes as $name => $theme) {
  478. if (!empty($theme->info['plugins'][$info['module']][$info['type']])) {
  479. $directories[$name] = drupal_get_path('theme', $name) . '/' . $theme->info['plugins'][$info['module']][$info['type']];
  480. }
  481. }
  482. }
  483. return $directories;
  484. }
  485. /**
  486. * Helper function to build a ctools-friendly list of themes capable of
  487. * providing plugins.
  488. *
  489. * @return array $themes
  490. * A list of themes that can act as plugin providers, sorted parent-first with
  491. * the active theme placed last.
  492. */
  493. function _ctools_list_themes() {
  494. static $themes;
  495. if (is_null($themes)) {
  496. $current = variable_get('theme_default', FALSE);
  497. $themes = $active = array();
  498. $all_themes = list_themes();
  499. foreach ($all_themes as $name => $theme) {
  500. // Only search from active themes
  501. if (empty($theme->status) && $theme->name != $current) {
  502. continue;
  503. }
  504. $active[$name] = $theme;
  505. // Prior to drupal 6.14, $theme->base_themes does not exist. Build it.
  506. if (!isset($theme->base_themes) && !empty($theme->base_theme)) {
  507. $active[$name]->base_themes = ctools_find_base_themes($all_themes, $name);
  508. }
  509. }
  510. // Construct a parent-first list of all themes
  511. foreach ($active as $name => $theme) {
  512. $base_themes = isset($theme->base_themes) ? $theme->base_themes : array();
  513. $themes = array_merge($themes, $base_themes, array($name => $theme->info['name']));
  514. }
  515. // Put the actual theme info objects into the array
  516. foreach (array_keys($themes) as $name) {
  517. if (isset($all_themes[$name])) {
  518. $themes[$name] = $all_themes[$name];
  519. }
  520. }
  521. // Make sure the current default theme always gets the last word
  522. if ($current_key = array_search($current, array_keys($themes))) {
  523. $themes += array_splice($themes, $current_key, 1);
  524. }
  525. }
  526. return $themes;
  527. }
  528. /**
  529. * Find all the base themes for the specified theme.
  530. *
  531. * Themes can inherit templates and function implementations from earlier themes.
  532. *
  533. * NOTE: this is a verbatim copy of system_find_base_themes(), which was not
  534. * implemented until 6.14. It is included here only as a fallback for outdated
  535. * versions of drupal core.
  536. *
  537. * @param $themes
  538. * An array of available themes.
  539. * @param $key
  540. * The name of the theme whose base we are looking for.
  541. * @param $used_keys
  542. * A recursion parameter preventing endless loops.
  543. * @return
  544. * Returns an array of all of the theme's ancestors; the first element's value
  545. * will be NULL if an error occurred.
  546. */
  547. function ctools_find_base_themes($themes, $key, $used_keys = array()) {
  548. $base_key = $themes[$key]->info['base theme'];
  549. // Does the base theme exist?
  550. if (!isset($themes[$base_key])) {
  551. return array($base_key => NULL);
  552. }
  553. $current_base_theme = array($base_key => $themes[$base_key]->info['name']);
  554. // Is the base theme itself a child of another theme?
  555. if (isset($themes[$base_key]->info['base theme'])) {
  556. // Do we already know the base themes of this theme?
  557. if (isset($themes[$base_key]->base_themes)) {
  558. return $themes[$base_key]->base_themes + $current_base_theme;
  559. }
  560. // Prevent loops.
  561. if (!empty($used_keys[$base_key])) {
  562. return array($base_key => NULL);
  563. }
  564. $used_keys[$base_key] = TRUE;
  565. return ctools_find_base_themes($themes, $base_key, $used_keys) + $current_base_theme;
  566. }
  567. // If we get here, then this is our parent theme.
  568. return $current_base_theme;
  569. }
  570. /**
  571. * Load plugin info for the provided hook; this is handled separately from
  572. * plugins from files.
  573. *
  574. * @param $info
  575. * The info array about the plugin as created by ctools_plugin_get_info()
  576. *
  577. * @return
  578. * An array of info supplied by any hook implementations.
  579. */
  580. function ctools_plugin_load_hooks($info) {
  581. $hooks = array();
  582. foreach (module_implements($info['hook']) as $module) {
  583. $result = ctools_plugin_process($info, $module, $module, drupal_get_path('module', $module));
  584. if (is_array($result)) {
  585. $hooks = array_merge($hooks, $result);
  586. }
  587. }
  588. return $hooks;
  589. }
  590. /**
  591. * Process a single hook implementation of a ctools plugin.
  592. *
  593. * @param $info
  594. * The $info array about the plugin as returned by ctools_plugin_get_info()
  595. * @param $module
  596. * The module that implements the plugin being processed.
  597. * @param $identifier
  598. * The plugin identifier, which is used to create the name of the hook
  599. * function being called.
  600. * @param $path
  601. * The path where files utilized by this plugin will be found.
  602. * @param $file
  603. * The file that was loaded for this plugin, if it exists.
  604. * @param $base
  605. * The base plugin name to use. If a file was loaded for the plugin, this
  606. * is the plugin to assume must be present. This is used to automatically
  607. * translate the array to make the syntax more friendly to plugin
  608. * implementors.
  609. */
  610. function ctools_plugin_process($info, $module, $identifier, $path, $file = NULL, $base = NULL) {
  611. if (is_array($identifier)) {
  612. $result = $identifier;
  613. }
  614. else {
  615. $function = $identifier . '_' . $info['hook'];
  616. if (!function_exists($function)) {
  617. return NULL;
  618. }
  619. $result = $function($info);
  620. if (!isset($result) || !is_array($result)) {
  621. return NULL;
  622. }
  623. }
  624. // Automatically convert to the proper format that lets plugin implementations
  625. // not nest arrays as deeply as they used to, but still support the older
  626. // format where they do:
  627. if ($base && (!isset($result[$base]) || !is_array($result[$base]))) {
  628. $result = array($base => $result);
  629. }
  630. return _ctools_process_data($result, $info, $module, $path, $file);
  631. }
  632. /**
  633. * Fill in default values and run hooks for data loaded for one or
  634. * more plugins.
  635. */
  636. function _ctools_process_data($result, $plugin_type_info, $module, $path, $file) {
  637. // Fill in global defaults.
  638. foreach ($result as $name => $plugin) {
  639. $result[$name] += array(
  640. 'module' => $module,
  641. 'name' => $name,
  642. 'path' => $path,
  643. 'file' => $file,
  644. 'plugin module' => $plugin_type_info['module'],
  645. 'plugin type' => $plugin_type_info['type'],
  646. );
  647. // Fill in plugin-specific defaults, if they exist.
  648. if (!empty($plugin_type_info['defaults'])) {
  649. if (is_array($plugin_type_info['defaults'])) {
  650. $result[$name] += $plugin_type_info['defaults'];
  651. }
  652. }
  653. // Allow the plugin to be altered before processing.
  654. if (!empty($plugin_type_info['alterable']) && $plugin_type_info['alterable']) {
  655. drupal_alter('ctools_plugin_pre', $result[$name], $plugin_type_info);
  656. }
  657. // Allow the plugin owner to do additional processing.
  658. if (!empty($plugin_type_info['process']) && $function = ctools_plugin_get_function($plugin_type_info, 'process')) {
  659. $function($result[$name], $plugin_type_info);
  660. }
  661. // Allow the plugin to be altered after processing.
  662. if (!empty($plugin_type_info['alterable']) && $plugin_type_info['alterable']) {
  663. drupal_alter('ctools_plugin_post', $result[$name], $plugin_type_info);
  664. }
  665. }
  666. return $result;
  667. }
  668. /**
  669. * Process an info file for plugin information, rather than a hook.
  670. */
  671. function ctools_plugin_process_info($info, $module, $file) {
  672. $result = drupal_parse_info_file($file->uri);
  673. if ($result) {
  674. $result = array($file->name => $result);
  675. return _ctools_process_data($result, $info, $module, dirname($file->uri), basename($file->uri));
  676. }
  677. }
  678. /**
  679. * Ask a module for info about a particular plugin type.
  680. */
  681. function ctools_plugin_get_info($module, $type) {
  682. $all_info = ctools_plugin_get_plugin_type_info();
  683. return isset($all_info[$module][$type]) ? $all_info[$module][$type] : array();
  684. }
  685. /**
  686. * Get a function from a plugin, if it exists. If the plugin is not already
  687. * loaded, try ctools_plugin_load_function() instead.
  688. *
  689. * @param $plugin_definition
  690. * The loaded plugin type.
  691. * @param $function_name
  692. * The identifier of the function. For example, 'settings form'.
  693. *
  694. * @return
  695. * The actual name of the function to call, or NULL if the function
  696. * does not exist.
  697. */
  698. function ctools_plugin_get_function($plugin_definition, $function_name) {
  699. // If cached the .inc file may not have been loaded. require_once is quite safe
  700. // and fast so it's okay to keep calling it.
  701. if (isset($plugin_definition['file'])) {
  702. // Plugins that are loaded from info files have the info file as
  703. // $plugin['file']. Don't try to run those.
  704. $info = ctools_plugin_get_info($plugin_definition['plugin module'], $plugin_definition['plugin type']);
  705. if (empty($info['info file'])) {
  706. require_once DRUPAL_ROOT . '/' . $plugin_definition['path'] . '/' . $plugin_definition['file'];
  707. }
  708. }
  709. if (!isset($plugin_definition[$function_name])) {
  710. return;
  711. }
  712. if (is_array($plugin_definition[$function_name]) && isset($plugin_definition[$function_name]['function'])) {
  713. $function = $plugin_definition[$function_name]['function'];
  714. if (isset($plugin_definition[$function_name]['file'])) {
  715. $file = $plugin_definition[$function_name]['file'];
  716. if (isset($plugin_definition[$function_name]['path'])) {
  717. $file = $plugin_definition[$function_name]['path'] . '/' . $file;
  718. }
  719. require_once DRUPAL_ROOT . '/' . $file;
  720. }
  721. }
  722. else {
  723. $function = $plugin_definition[$function_name];
  724. }
  725. if (function_exists($function)) {
  726. return $function;
  727. }
  728. }
  729. /**
  730. * Load a plugin and get a function name from it, returning success only
  731. * if the function exists.
  732. *
  733. * @param $module
  734. * The module that owns the plugin type.
  735. * @param $type
  736. * The type of plugin.
  737. * @param $id
  738. * The id of the specific plugin to load.
  739. * @param $function_name
  740. * The identifier of the function. For example, 'settings form'.
  741. *
  742. * @return
  743. * The actual name of the function to call, or NULL if the function
  744. * does not exist.
  745. */
  746. function ctools_plugin_load_function($module, $type, $id, $function_name) {
  747. $plugin = ctools_get_plugins($module, $type, $id);
  748. return ctools_plugin_get_function($plugin, $function_name);
  749. }
  750. /**
  751. * Get a class from a plugin, if it exists. If the plugin is not already
  752. * loaded, try ctools_plugin_load_class() instead.
  753. *
  754. * @param $plugin_definition
  755. * The loaded plugin type.
  756. * @param $class_name
  757. * The identifier of the class. For example, 'handler'.
  758. *
  759. * @return
  760. * The actual name of the class to call, or NULL if the class does not exist.
  761. */
  762. function ctools_plugin_get_class($plugin_definition, $class_name) {
  763. // If cached the .inc file may not have been loaded. require_once is quite safe
  764. // and fast so it's okay to keep calling it.
  765. if (isset($plugin_definition['file'])) {
  766. // Plugins that are loaded from info files have the info file as
  767. // $plugin['file']. Don't try to run those.
  768. $info = ctools_plugin_get_info($plugin_definition['plugin module'], $plugin_definition['plugin type']);
  769. if (empty($info['info file'])) {
  770. require_once DRUPAL_ROOT . '/' . $plugin_definition['path'] . '/' . $plugin_definition['file'];
  771. }
  772. }
  773. $return = FALSE;
  774. if (!isset($plugin_definition[$class_name])) {
  775. return;
  776. }
  777. else if (is_string($plugin_definition[$class_name])) {
  778. // Plugin uses the string form shorthand.
  779. $return = $plugin_definition[$class_name];
  780. }
  781. else if (isset($plugin_definition[$class_name]['class'])) {
  782. // Plugin uses the verbose array form.
  783. $return = $plugin_definition[$class_name]['class'];
  784. }
  785. // @todo consider adding an else {watchdog(...)} here
  786. return ($return && class_exists($return)) ? $return : NULL;
  787. }
  788. /**
  789. * Load a plugin and get a class name from it, returning success only if the
  790. * class exists.
  791. *
  792. * @param $module
  793. * The module that owns the plugin type.
  794. * @param $type
  795. * The type of plugin.
  796. * @param $id
  797. * The id of the specific plugin to load.
  798. * @param $class_name
  799. * The identifier of the class. For example, 'handler'.
  800. *
  801. * @return
  802. * The actual name of the class to call, or NULL if the class does not exist.
  803. */
  804. function ctools_plugin_load_class($module, $type, $id, $class_name) {
  805. $plugin = ctools_get_plugins($module, $type, $id);
  806. return ctools_plugin_get_class($plugin, $class_name);
  807. }
  808. /**
  809. * Sort callback for sorting plugins naturally.
  810. *
  811. * Sort first by weight, then by title.
  812. */
  813. function ctools_plugin_sort($a, $b) {
  814. if (is_object($a)) {
  815. $a = (array) $a;
  816. }
  817. if (is_object($b)) {
  818. $b = (array) $b;
  819. }
  820. if (empty($a['weight'])) {
  821. $a['weight'] = 0;
  822. }
  823. if (empty($b['weight'])) {
  824. $b['weight'] = 0;
  825. }
  826. if ($a['weight'] == $b['weight']) {
  827. return strnatcmp(strtolower($a['title']), strtolower($b['title']));
  828. }
  829. return ($a['weight'] < $b['weight']) ? -1 : 1;
  830. }