Projet

Général

Profil

Paste
Télécharger (31,9 ko) Statistiques
| Branche: | Révision:

root / htmltest / sites / all / modules / ctools / includes / plugins.inc @ 3753f249

1
<?php
2

    
3
/**
4
 * @file
5
 *
6
 * Contains routines to organize and load plugins. It allows a special
7
 * variation of the hook system so that plugins can be kept in separate
8
 * .inc files, and can be either loaded all at once or loaded only when
9
 * necessary.
10
 */
11

    
12
/**
13
 * Get an array of information about modules that support an API.
14
 *
15
 * This will ask each module if they support the given API, and if they do
16
 * it will return an array of information about the modules that do.
17
 *
18
 * This function invokes hook_ctools_api. This invocation is statically
19
 * cached, so feel free to call it as often per page run as you like, it
20
 * will cost very little.
21
 *
22
 * This function can be used as an alternative to module_implements and can
23
 * thus be used to find a precise list of modules that not only support
24
 * a given hook (aka 'api') but also restrict to only modules that use
25
 * the given version. This will allow multiple modules moving at different
26
 * paces to still be able to work together and, in the event of a mismatch,
27
 * either fall back to older behaviors or simply cease loading, which is
28
 * still better than a crash.
29
 *
30
 * @param $owner
31
 *   The name of the module that controls the API.
32
 * @param $api
33
 *   The name of the api. The api name forms the file name:
34
 *   $module.$api.inc
35
 * @param $minimum_version
36
 *   The lowest version API that is compatible with this one. If a module
37
 *   reports its API as older than this, its files will not be loaded. This
38
 *   should never change during operation.
39
 * @param $current_version
40
 *   The current version of the api. If a module reports its minimum API as
41
 *   higher than this, its files will not be loaded. This should never change
42
 *   during operation.
43
 *
44
 * @return
45
 *   An array of API information, keyed by module. Each module's information will
46
 *   contain:
47
 *   - 'version': The version of the API required by the module. The module
48
 *     should use the lowest number it can support so that the widest range
49
 *     of supported versions can be used.
50
 *   - 'path': If not provided, this will be the module's path. This is
51
 *     where the module will store any subsidiary files. This differs from
52
 *     plugin paths which are figured separately.
53
 *
54
 *   APIs can request any other information to be placed here that they might
55
 *   need. This should be in the documentation for that particular API.
56
 */
57
function ctools_plugin_api_info($owner, $api, $minimum_version, $current_version) {
58
  $cache = &drupal_static(__FUNCTION__, array());
59
  if (!isset($cache[$owner][$api])) {
60
    $cache[$owner][$api] = array();
61

    
62
    $hook = ctools_plugin_api_get_hook($owner, $api);
63

    
64
    foreach (module_implements($hook) as $module) {
65
      $function = $module . '_' . $hook;
66
      $info = $function($owner, $api);
67
      $version = NULL;
68
      // This is added to make hook_views_api() compatible with this, since
69
      // views used a different version key.
70
      if (isset($info['version'])) {
71
        $version = $info['version'];
72
      }
73
      else if (isset($info['api'])) {
74
        $version = $info['api'];
75
      }
76

    
77
      if (!isset($version)) {
78
        continue;
79
      }
80

    
81
      // Only process if version is between minimum and current, inclusive.
82
      if (version_compare($version, $minimum_version, '>=') && version_compare($version, $current_version, '<=')) {
83
        if (!isset($info['path'])) {
84
          $info['path'] = drupal_get_path('module', $module);
85
        }
86
        $cache[$owner][$api][$module] = $info;
87
      }
88
    }
89

    
90
    // And allow themes to implement these as well.
91
    $themes = _ctools_list_themes();
92
    foreach ($themes as $name => $theme) {
93
      if (!empty($theme->info['api'][$owner][$api])) {
94
        $info = $theme->info['api'][$owner][$api];
95
        if (!isset($info['version'])) {
96
          continue;
97
        }
98

    
99
        // Only process if version is between minimum and current, inclusive.
100
      if (version_compare($info['version'], $minimum_version, '>=') && version_compare($info['version'], $current_version, '<=')) {
101
          if (!isset($info['path'])) {
102
            $info['path'] = '';
103
          }
104
          // Because themes can't easily specify full path, we add it here
105
          // even though we do not for modules:
106
          $info['path'] = drupal_get_path('theme', $name) . '/' . $info['path'];
107
          $cache[$owner][$api][$name] = $info;
108
        }
109
      }
110
    }
111

    
112
    // Allow other modules to hook in.
113
    drupal_alter($hook, $cache[$owner][$api]);
114
  }
115

    
116
  return $cache[$owner][$api];
117
}
118

    
119
/**
120
 * Load a group of API files.
121
 *
122
 * This will ask each module if they support the given API, and if they do
123
 * it will load the specified file name. The API and the file name
124
 * coincide by design.
125
 *
126
 * @param $owner
127
 *   The name of the module that controls the API.
128
 * @param $api
129
 *   The name of the api. The api name forms the file name:
130
 *   $module.$api.inc, though this can be overridden by the module's response.
131
 * @param $minimum_version
132
 *   The lowest version API that is compatible with this one. If a module
133
 *   reports its API as older than this, its files will not be loaded. This
134
 *   should never change during operation.
135
 * @param $current_version
136
 *   The current version of the api. If a module reports its minimum API as
137
 *   higher than this, its files will not be loaded. This should never change
138
 *   during operation.
139
 *
140
 * @return
141
 *   The API information, in case you need it.
142
 */
143
function ctools_plugin_api_include($owner, $api, $minimum_version, $current_version) {
144
  static $already_done = array();
145

    
146
  $info = ctools_plugin_api_info($owner, $api, $minimum_version, $current_version);
147
  foreach ($info as $module => $plugin_info) {
148
    if (!isset($already_done[$owner][$api][$module])) {
149
      if (isset($plugin_info["$api file"])) {
150
        $file = $plugin_info["$api file"];
151
      }
152
      else if (isset($plugin_info['file'])) {
153
        $file = $plugin_info['file'];
154
      }
155
      else {
156
        $file = "$module.$api.inc";
157
      }
158

    
159
      if (file_exists(DRUPAL_ROOT . "/$plugin_info[path]/$file")) {
160
        require_once DRUPAL_ROOT . "/$plugin_info[path]/$file";
161
      }
162
      else if (file_exists(DRUPAL_ROOT . "/$file")) {
163
        require_once DRUPAL_ROOT . "/$file";
164
      }
165
      $already_done[$owner][$api][$module] = TRUE;
166
    }
167
  }
168

    
169
  return $info;
170
}
171

    
172
/**
173
 * Find out what hook to use to determine if modules support an API.
174
 *
175
 * By default, most APIs will use hook_ctools_plugin_api, but some modules
176
 * want sole ownership. This technique lets modules define what hook
177
 * to use.
178
 */
179
function ctools_plugin_api_get_hook($owner, $api) {
180
  // Allow modules to use their own hook for this. The only easy way to do
181
  // this right now is with a magically named function.
182
  if (function_exists($function = $owner . '_' . $api . '_hook_name')) {
183
    $hook = $function();
184
  }
185
  else if (function_exists($function = $owner . '_ctools_plugin_api_hook_name')) {
186
    $hook = $function();
187
  }
188

    
189
  // Do this last so that if the $function above failed to return, we have a
190
  // sane default.
191
  if (empty($hook)) {
192
    $hook = 'ctools_plugin_api';
193
  }
194

    
195
  return $hook;
196
}
197

    
198
/**
199
 * Fetch a group of plugins by name.
200
 *
201
 * @param $module
202
 *   The name of the module that utilizes this plugin system. It will be
203
 *   used to call hook_ctools_plugin_$plugin() to get more data about the plugin.
204
 * @param $type
205
 *   The type identifier of the plugin.
206
 * @param $id
207
 *   If specified, return only information about plugin with this identifier.
208
 *   The system will do its utmost to load only plugins with this id.
209
 *
210
 * @return
211
 *   An array of information arrays about the plugins received. The contents
212
 *   of the array are specific to the plugin.
213
 */
214
function ctools_get_plugins($module, $type, $id = NULL) {
215
  // Store local caches of plugins and plugin info so we don't have to do full
216
  // lookups everytime.
217
  $plugins = &drupal_static('ctools_plugins', array());
218
  $info = ctools_plugin_get_plugin_type_info();
219

    
220
  // Bail out noisily if an invalid module/type combination is requested.
221
  if (!isset($info[$module][$type])) {
222
    watchdog('ctools', 'Invalid plugin module/type combination requested: module @module and type @type', array('@module' => $module, '@type' => $type), WATCHDOG_ERROR);
223
    return array();
224
  }
225

    
226
  // Make sure our plugins array is populated.
227
  if (!isset($plugins[$module][$type])) {
228
    $plugins[$module][$type] = array();
229
  }
230

    
231
  // Attempt to shortcut this whole piece of code if we already have
232
  // the requested plugin:
233
  if ($id && array_key_exists($id, $plugins[$module][$type])) {
234
    return $plugins[$module][$type][$id];
235
  }
236

    
237
  // Store the status of plugin loading. If a module plugin type pair is true,
238
  // then it is fully loaded and no searching or setup needs to be done.
239
  $setup = &drupal_static('ctools_plugin_setup', array());
240

    
241
  // We assume we don't need to build a cache.
242
  $build_cache = FALSE;
243

    
244
  // If the plugin info says this can be cached, check cache first.
245
  if ($info[$module][$type]['cache'] && empty($setup[$module][$type])) {
246
    $cache = cache_get("plugins:$module:$type", $info[$module][$type]['cache table']);
247

    
248
    if (!empty($cache->data)) {
249
      // Cache load succeeded so use the cached plugin list.
250
      $plugins[$module][$type]   = $cache->data;
251
      // Set $setup to true so we know things where loaded.
252
      $setup[$module][$type]     = TRUE;
253
    }
254
    else {
255
      // Cache load failed so store that we need to build and write the cache.
256
      $build_cache = TRUE;
257
    }
258
  }
259

    
260
  // Always load all hooks if we need them. Note we only need them now if the
261
  // plugin asks for them. We can assume that if we have plugins we've already
262
  // called the global hook.
263
  if (!empty($info[$module][$type]['use hooks']) && empty($plugins[$module][$type])) {
264
    $plugins[$module][$type] = ctools_plugin_load_hooks($info[$module][$type]);
265
  }
266

    
267
  // Then see if we should load all files. We only do this if we
268
  // want a list of all plugins or there was a cache miss.
269
  if (empty($setup[$module][$type]) && ($build_cache || !$id)) {
270
    $setup[$module][$type] = TRUE;
271
    $plugins[$module][$type] = array_merge($plugins[$module][$type], ctools_plugin_load_includes($info[$module][$type]));
272
    // If the plugin can have child plugins, and we're loading all plugins,
273
    // go through the list of plugins we have and find child plugins.
274
    if (!$id && !empty($info[$module][$type]['child plugins'])) {
275
      // If a plugin supports children, go through each plugin and ask.
276
      $temp = array();
277
      foreach ($plugins[$module][$type] as $name => $plugin) {
278
        // The strpos ensures that we don't try to find children for plugins
279
        // that are already children.
280
        if (!empty($plugin['get children']) && function_exists($plugin['get children']) && strpos($name, ':') === FALSE) {
281
          $temp = array_merge($plugin['get children']($plugin, $name), $temp);
282
        }
283
        else {
284
          $temp[$name] = $plugin;
285
        }
286
      }
287
      $plugins[$module][$type] = $temp;
288
    }
289
  }
290

    
291

    
292
  // If we were told earlier that this is cacheable and the cache was
293
  // empty, give something back.
294
  if ($build_cache) {
295
    cache_set("plugins:$module:$type", $plugins[$module][$type], $info[$module][$type]['cache table']);
296
  }
297

    
298
  // If no id was requested, we are finished here:
299
  if (!$id) {
300
    // Use array_filter because looking for unknown plugins could cause NULL
301
    // entries to appear in the list later.
302
    return array_filter($plugins[$module][$type]);
303
  }
304

    
305
  // Check to see if we need to look for the file
306
  if (!array_key_exists($id, $plugins[$module][$type])) {
307
    // If we can have child plugins, check to see if the plugin name is in the
308
    // format of parent:child and break it up if it is.
309
    if (!empty($info[$module][$type]['child plugins']) && strpos($id, ':') !== FALSE) {
310
      list($parent, $child) = explode(':', $id, 2);
311
    }
312
    else {
313
      $parent = $id;
314
    }
315

    
316
    if (!array_key_exists($parent, $plugins[$module][$type])) {
317
      $result = ctools_plugin_load_includes($info[$module][$type], $parent);
318
      // Set to either what was returned or NULL.
319
      $plugins[$module][$type][$parent] = isset($result[$parent]) ? $result[$parent] : NULL;
320
    }
321

    
322
    // If we are looking for a child, and have the parent, ask the parent for the child.
323
    if (!empty($child) && !empty($plugins[$module][$type][$parent]) && function_exists($plugins[$module][$type][$parent]['get child'])) {
324
      $plugins[$module][$type][$id] = $plugins[$module][$type][$parent]['get child']($plugins[$module][$type][$parent], $parent, $child);
325
    }
326
  }
327

    
328
  // At this point we should either have the plugin, or a NULL.
329
  return $plugins[$module][$type][$id];
330
}
331

    
332
/**
333
 * Return the full list of plugin type info for all plugin types registered in
334
 * the current system.
335
 *
336
 * This function manages its own cache getting/setting, and should always be
337
 * used as the way to initially populate the list of plugin types. Make sure you
338
 * call this function to properly populate the ctools_plugin_type_info static
339
 * variable.
340
 *
341
 * @return array
342
 *   A multilevel array of plugin type info, the outer array keyed on module
343
 *   name and each inner array keyed on plugin type name.
344
 */
345
function ctools_plugin_get_plugin_type_info($flush = FALSE) {
346
  static $drupal_static_fast;
347
  if (!isset($drupal_static_fast)) {
348
    $drupal_static_fast['info_loaded'] = &drupal_static('ctools_plugin_type_info_loaded', FALSE);
349
    $drupal_static_fast['all_type_info'] = &drupal_static('ctools_plugin_type_info', array());
350
  }
351
  $info_loaded = &$drupal_static_fast['info_loaded'];
352
  $all_type_info = &$drupal_static_fast['all_type_info'];
353

    
354
  // Only trigger info loading once.
355
  if ($info_loaded && !$flush) {
356
    return $all_type_info;
357
  }
358
  $info_loaded = TRUE;
359

    
360
  $cache = cache_get('ctools_plugin_type_info');
361
  if (!empty($cache->data) && !$flush) {
362
    // Plugin type info cache is warm, use it.
363
    $all_type_info = $cache->data;
364
  }
365
  else {
366
    // Cache expired, refill it.
367
    foreach (module_implements('ctools_plugin_type') as $module) {
368
      $module_infos = array();
369
      $function = $module . '_ctools_plugin_type';
370
      $module_infos = $function();
371

    
372
      foreach ($module_infos as $plugin_type_name => $plugin_type_info) {
373
        // Apply defaults. Array addition will not overwrite pre-existing keys.
374
        $plugin_type_info += array(
375
          'module' => $module,
376
          'type' => $plugin_type_name,
377
          'cache' => FALSE,
378
          'cache table' => 'cache',
379
          'classes' => array(),
380
          'use hooks' => FALSE,
381
          'defaults' => array(),
382
          'process' => '',
383
          'alterable' => TRUE,
384
          'extension' => 'inc',
385
          'info file' => FALSE,
386
          'hook' => $module . '_' . $plugin_type_name,
387
          'load themes' => FALSE,
388
        );
389
        $all_type_info[$module][$plugin_type_name] = $plugin_type_info;
390
      }
391
    }
392
    cache_set('ctools_plugin_type_info', $all_type_info);
393
  }
394

    
395
  return $all_type_info;
396
}
397

    
398
/**
399
 * Reset all static caches that affect the result of ctools_get_plugins().
400
 */
401
function ctools_get_plugins_reset() {
402
  drupal_static_reset('ctools_plugins');
403
  drupal_static_reset('ctools_plugin_setup');
404
  drupal_static_reset('ctools_plugin_load_includes');
405
  drupal_static_reset('ctools_plugin_api_info');
406
}
407

    
408
/**
409
 * Load plugins from a directory.
410
 *
411
 * @param $info
412
 *   The plugin info as returned by ctools_plugin_get_info()
413
 * @param $file
414
 *   The file to load if we're looking for just one particular plugin.
415
 *
416
 * @return
417
 *   An array of information created for this plugin.
418
 */
419
function ctools_plugin_load_includes($info, $filename = NULL) {
420
  // Keep a static array so we don't hit file_scan_directory more than necessary.
421
  $all_files = &drupal_static(__FUNCTION__, array());
422

    
423
  // store static of plugin arrays for reference because they can't be reincluded.
424
  static $plugin_arrays = array();
425

    
426
  // If we're being asked for all plugins of a type, skip any caching
427
  // we may have done because this is an admin task and it's ok to
428
  // spend the extra time.
429
  if (!isset($filename)) {
430
    $all_files[$info['module']][$info['type']] = NULL;
431
  }
432

    
433
  if (!isset($all_files[$info['module']][$info['type']])) {
434
    // If a filename was set, we will try to load our list of files from
435
    // cache. This is considered normal operation and we try to reduce
436
    // the time spent finding files.
437
    if (isset($filename)) {
438
      $cache = cache_get("ctools_plugin_files:$info[module]:$info[type]");
439
      if ($cache) {
440
        $all_files[$info['module']][$info['type']] = $cache->data;
441
      }
442
    }
443

    
444
    if (!isset($all_files[$info['module']][$info['type']])) {
445
      $all_files[$info['module']][$info['type']] = array();
446
      // Load all our plugins.
447
      $directories = ctools_plugin_get_directories($info);
448
      $extension = (empty($info['info file']) || ($info['extension'] != 'inc')) ? $info['extension'] : 'info';
449

    
450
      foreach ($directories as $module => $path) {
451
        $all_files[$info['module']][$info['type']][$module] = file_scan_directory($path, '/\.' . $extension . '$/', array('key' => 'name'));
452
      }
453

    
454
      cache_set("ctools_plugin_files:$info[module]:$info[type]", $all_files[$info['module']][$info['type']]);
455
    }
456
  }
457
  $file_list = $all_files[$info['module']][$info['type']];
458
  $plugins = array();
459

    
460
  // Iterate through all the plugin .inc files, load them and process the hook
461
  // that should now be available.
462
  foreach (array_filter($file_list) as $module => $files) {
463
    if ($filename) {
464
      $files = isset($files[$filename]) ? array($filename => $files[$filename]) : array();
465
    }
466
    foreach ($files as $file) {
467
      if (!empty($info['info file'])) {
468
        // Parse a .info file
469
        $result = ctools_plugin_process_info($info, $module, $file);
470
      }
471
      else {
472
        // Parse a hook.
473
        $plugin = NULL; // ensure that we don't have something leftover from earlier.
474

    
475
        if (isset($plugin_arrays[$file->uri])) {
476
          $identifier = $plugin_arrays[$file->uri];
477
        }
478
        else {
479

    
480
          require_once DRUPAL_ROOT . '/' . $file->uri;
481
          // .inc files have a special format for the hook identifier.
482
          // For example, 'foo.inc' in the module 'mogul' using the plugin
483
          // whose hook is named 'borg_type' should have a function named (deep breath)
484
          // mogul_foo_borg_type()
485

    
486
          // If, however, the .inc file set the quasi-global $plugin array, we
487
          // can use that and not even call a function. Set the $identifier
488
          // appropriately and ctools_plugin_process() will handle it.
489
          if (isset($plugin)) {
490
            $plugin_arrays[$file->uri] = $plugin;
491
            $identifier = $plugin;
492
          }
493
          else {
494
            $identifier = $module . '_' . $file->name;
495
          }
496
        }
497

    
498
        $result = ctools_plugin_process($info, $module, $identifier, dirname($file->uri), basename($file->uri), $file->name);
499
      }
500
      if (is_array($result)) {
501
        $plugins = array_merge($plugins, $result);
502
      }
503
    }
504
  }
505
  return $plugins;
506
}
507

    
508
/**
509
 * Get a list of directories to search for plugins of the given type.
510
 *
511
 * This utilizes hook_ctools_plugin_directory() to determine a complete list of
512
 * directories. Only modules that implement this hook and return a string
513
 * value will have their directories included.
514
 *
515
 * @param $info
516
 *   The $info array for the plugin as returned by ctools_plugin_get_info().
517
 *
518
 * @return array $directories
519
 *   An array of directories to search.
520
 */
521
function ctools_plugin_get_directories($info) {
522
  $directories = array();
523

    
524
  foreach (module_implements('ctools_plugin_directory') as $module) {
525
    $function = $module . '_ctools_plugin_directory';
526
    $result = $function($info['module'], $info['type']);
527
    if ($result && is_string($result)) {
528
      $directories[$module] = drupal_get_path('module', $module) . '/' . $result;
529
    }
530
  }
531

    
532
  if (!empty($info['load themes'])) {
533
    $themes = _ctools_list_themes();
534
    foreach ($themes as $name => $theme) {
535
      if (!empty($theme->info['plugins'][$info['module']][$info['type']])) {
536
        $directories[$name] = drupal_get_path('theme', $name) . '/' . $theme->info['plugins'][$info['module']][$info['type']];
537
      }
538
    }
539
  }
540
  return $directories;
541
}
542

    
543
/**
544
 * Helper function to build a ctools-friendly list of themes capable of
545
 * providing plugins.
546
 *
547
 * @return array $themes
548
 *   A list of themes that can act as plugin providers, sorted parent-first with
549
 *   the active theme placed last.
550
 */
551
function _ctools_list_themes() {
552
  static $themes;
553
  if (is_null($themes)) {
554
    $current = variable_get('theme_default', FALSE);
555
    $themes = $active = array();
556
    $all_themes = list_themes();
557
    foreach ($all_themes as $name => $theme) {
558
      // Only search from active themes
559
      if (empty($theme->status) && $theme->name != $current) {
560
        continue;
561
      }
562
      $active[$name] = $theme;
563
      // Prior to drupal 6.14, $theme->base_themes does not exist. Build it.
564
      if (!isset($theme->base_themes) && !empty($theme->base_theme)) {
565
        $active[$name]->base_themes = ctools_find_base_themes($all_themes, $name);
566
      }
567
    }
568

    
569
    // Construct a parent-first list of all themes
570
    foreach ($active as $name => $theme) {
571
      $base_themes = isset($theme->base_themes) ? $theme->base_themes : array();
572
      $themes = array_merge($themes, $base_themes, array($name => $theme->info['name']));
573
    }
574
    // Put the actual theme info objects into the array
575
    foreach (array_keys($themes) as $name) {
576
      if (isset($all_themes[$name])) {
577
        $themes[$name] = $all_themes[$name];
578
      }
579
    }
580

    
581
    // Make sure the current default theme always gets the last word
582
    if ($current_key = array_search($current, array_keys($themes))) {
583
      $themes += array_splice($themes, $current_key, 1);
584
    }
585
  }
586
  return $themes;
587
}
588

    
589

    
590
/**
591
 * Find all the base themes for the specified theme.
592
 *
593
 * Themes can inherit templates and function implementations from earlier themes.
594
 *
595
 * NOTE: this is a verbatim copy of system_find_base_themes(), which was not
596
 * implemented until 6.14. It is included here only as a fallback for outdated
597
 * versions of drupal core.
598
 *
599
 * @param $themes
600
 *   An array of available themes.
601
 * @param $key
602
 *   The name of the theme whose base we are looking for.
603
 * @param $used_keys
604
 *   A recursion parameter preventing endless loops.
605
 * @return
606
 *   Returns an array of all of the theme's ancestors; the first element's value
607
 *   will be NULL if an error occurred.
608
 */
609
function ctools_find_base_themes($themes, $key, $used_keys = array()) {
610
  $base_key = $themes[$key]->info['base theme'];
611
  // Does the base theme exist?
612
  if (!isset($themes[$base_key])) {
613
    return array($base_key => NULL);
614
  }
615

    
616
  $current_base_theme = array($base_key => $themes[$base_key]->info['name']);
617

    
618
  // Is the base theme itself a child of another theme?
619
  if (isset($themes[$base_key]->info['base theme'])) {
620
    // Do we already know the base themes of this theme?
621
    if (isset($themes[$base_key]->base_themes)) {
622
      return $themes[$base_key]->base_themes + $current_base_theme;
623
    }
624
    // Prevent loops.
625
    if (!empty($used_keys[$base_key])) {
626
      return array($base_key => NULL);
627
    }
628
    $used_keys[$base_key] = TRUE;
629
    return ctools_find_base_themes($themes, $base_key, $used_keys) + $current_base_theme;
630
  }
631
  // If we get here, then this is our parent theme.
632
  return $current_base_theme;
633
}
634

    
635

    
636
/**
637
 * Load plugin info for the provided hook; this is handled separately from
638
 * plugins from files.
639
 *
640
 * @param $info
641
 *   The info array about the plugin as created by ctools_plugin_get_info()
642
 *
643
 * @return
644
 *   An array of info supplied by any hook implementations.
645
 */
646
function ctools_plugin_load_hooks($info) {
647
  $hooks = array();
648
  foreach (module_implements($info['hook']) as $module) {
649
    $result = ctools_plugin_process($info, $module, $module, drupal_get_path('module', $module));
650
    if (is_array($result)) {
651
      $hooks = array_merge($hooks, $result);
652
    }
653
  }
654
  return $hooks;
655
}
656

    
657
/**
658
 * Process a single hook implementation of a ctools plugin.
659
 *
660
 * @param $info
661
 *   The $info array about the plugin as returned by ctools_plugin_get_info()
662
 * @param $module
663
 *   The module that implements the plugin being processed.
664
 * @param $identifier
665
 *   The plugin identifier, which is used to create the name of the hook
666
 *   function being called.
667
 * @param $path
668
 *   The path where files utilized by this plugin will be found.
669
 * @param $file
670
 *   The file that was loaded for this plugin, if it exists.
671
 * @param $base
672
 *   The base plugin name to use. If a file was loaded for the plugin, this
673
 *   is the plugin to assume must be present. This is used to automatically
674
 *   translate the array to make the syntax more friendly to plugin
675
 *   implementors.
676
 */
677
function ctools_plugin_process($info, $module, $identifier, $path, $file = NULL, $base = NULL) {
678
  if (is_array($identifier)) {
679
    $result = $identifier;
680
  }
681
  else {
682
    $function = $identifier . '_' . $info['hook'];
683
    if (!function_exists($function)) {
684
      return NULL;
685
    }
686
    $result = $function();
687
    if (!isset($result) || !is_array($result)) {
688
      return NULL;
689
    }
690
  }
691

    
692
  // Automatically convert to the proper format that lets plugin implementations
693
  // not nest arrays as deeply as they used to, but still support the older
694
  // format where they do:
695
  if ($base && (!isset($result[$base]) || !is_array($result[$base]))) {
696
    $result = array($base => $result);
697
  }
698

    
699
  return _ctools_process_data($result, $info, $module, $path, $file);
700
}
701

    
702
/**
703
 * Fill in default values and run hooks for data loaded for one or
704
 * more plugins.
705
 */
706
function _ctools_process_data($result, $plugin_type_info, $module, $path, $file) {
707
  // Fill in global defaults.
708
  foreach ($result as $name => $plugin) {
709
    $result[$name] += array(
710
      'module' => $module,
711
      'name' => $name,
712
      'path' => $path,
713
      'file' => $file,
714
      'plugin module' => $plugin_type_info['module'],
715
      'plugin type' => $plugin_type_info['type'],
716
    );
717

    
718
    // Fill in plugin-specific defaults, if they exist.
719
    if (!empty($plugin_type_info['defaults'])) {
720
      if (is_array($plugin_type_info['defaults'])) {
721
        $result[$name] += $plugin_type_info['defaults'];
722
      }
723
    }
724

    
725
    // Allow the plugin to be altered before processing.
726
    if (!empty($plugin_type_info['alterable']) && $plugin_type_info['alterable']) {
727
      drupal_alter('ctools_plugin_pre', $result[$name], $plugin_type_info);
728
    }
729

    
730
    // Allow the plugin owner to do additional processing.
731
    if (!empty($plugin_type_info['process']) && $function = ctools_plugin_get_function($plugin_type_info, 'process')) {
732
      $function($result[$name], $plugin_type_info);
733
    }
734

    
735
    // Allow the plugin to be altered after processing.
736
    if (!empty($plugin_type_info['alterable']) && $plugin_type_info['alterable']) {
737
      drupal_alter('ctools_plugin_post', $result[$name], $plugin_type_info);
738
    }
739
  }
740
  return $result;
741
}
742

    
743

    
744
/**
745
 * Process an info file for plugin information, rather than a hook.
746
 */
747
function ctools_plugin_process_info($info, $module, $file) {
748
  $result = drupal_parse_info_file($file->uri);
749
  if ($result) {
750
    $result = array($file->name => $result);
751
    return _ctools_process_data($result, $info, $module, dirname($file->uri), basename($file->uri));
752
  }
753
}
754

    
755
/**
756
 * Ask a module for info about a particular plugin type.
757
 */
758
function ctools_plugin_get_info($module, $type) {
759
  $all_info = ctools_plugin_get_plugin_type_info();
760
  return isset($all_info[$module][$type]) ? $all_info[$module][$type] : array();
761
}
762

    
763
/**
764
 * Get a function from a plugin, if it exists. If the plugin is not already
765
 * loaded, try ctools_plugin_load_function() instead.
766
 *
767
 * @param $plugin_definition
768
 *   The loaded plugin type.
769
 * @param $function_name
770
 *   The identifier of the function. For example, 'settings form'.
771
 *
772
 * @return
773
 *   The actual name of the function to call, or NULL if the function
774
 *   does not exist.
775
 */
776
function ctools_plugin_get_function($plugin_definition, $function_name) {
777
  // If cached the .inc file may not have been loaded. require_once is quite safe
778
  // and fast so it's okay to keep calling it.
779
  if (isset($plugin_definition['file'])) {
780
    // Plugins that are loaded from info files have the info file as
781
    // $plugin['file'].  Don't try to run those.
782
    $info = ctools_plugin_get_info($plugin_definition['plugin module'], $plugin_definition['plugin type']);
783
    if (empty($info['info file'])) {
784
      require_once DRUPAL_ROOT . '/' . $plugin_definition['path'] . '/' . $plugin_definition['file'];
785
    }
786
  }
787

    
788
  if (!isset($plugin_definition[$function_name])) {
789
    return;
790
  }
791

    
792
  if (is_array($plugin_definition[$function_name]) && isset($plugin_definition[$function_name]['function'])) {
793
    $function = $plugin_definition[$function_name]['function'];
794
    if (isset($plugin_definition[$function_name]['file'])) {
795
      $file = $plugin_definition[$function_name]['file'];
796
      if (isset($plugin_definition[$function_name]['path'])) {
797
        $file = $plugin_definition[$function_name]['path'] . '/' . $file;
798
      }
799
      require_once DRUPAL_ROOT . '/' . $file;
800
    }
801
  }
802
  else {
803
    $function = $plugin_definition[$function_name];
804
  }
805

    
806
  if (function_exists($function)) {
807
    return $function;
808
  }
809
}
810

    
811
/**
812
 * Load a plugin and get a function name from it, returning success only
813
 * if the function exists.
814
 *
815
 * @param $module
816
 *   The module that owns the plugin type.
817
 * @param $type
818
 *   The type of plugin.
819
 * @param $id
820
 *   The id of the specific plugin to load.
821
 * @param $function_name
822
 *   The identifier of the function. For example, 'settings form'.
823
 *
824
 * @return
825
 *   The actual name of the function to call, or NULL if the function
826
 *   does not exist.
827
 */
828
function ctools_plugin_load_function($module, $type, $id, $function_name) {
829
  $plugin = ctools_get_plugins($module, $type, $id);
830
  return ctools_plugin_get_function($plugin, $function_name);
831
}
832

    
833
/**
834
 * Get a class from a plugin, if it exists. If the plugin is not already
835
 * loaded, try ctools_plugin_load_class() instead.
836
 *
837
 * @param $plugin_definition
838
 *   The loaded plugin type.
839
 * @param $class_name
840
 *   The identifier of the class. For example, 'handler'.
841
 *
842
 * @return
843
 *   The actual name of the class to call, or NULL if the class does not exist.
844
 */
845
function ctools_plugin_get_class($plugin_definition, $class_name) {
846
  // If cached the .inc file may not have been loaded. require_once is quite safe
847
  // and fast so it's okay to keep calling it.
848
  if (isset($plugin_definition['file'])) {
849
    // Plugins that are loaded from info files have the info file as
850
    // $plugin['file'].  Don't try to run those.
851
    $info = ctools_plugin_get_info($plugin_definition['plugin module'], $plugin_definition['plugin type']);
852
    if (empty($info['info file'])) {
853
      require_once DRUPAL_ROOT . '/' . $plugin_definition['path'] . '/' . $plugin_definition['file'];
854
    }
855
  }
856

    
857
  $return = FALSE;
858
  if (!isset($plugin_definition[$class_name])) {
859
    return;
860
  }
861
  else if (is_string($plugin_definition[$class_name])) {
862
    // Plugin uses the string form shorthand.
863
    $return = $plugin_definition[$class_name];
864
  }
865
  else if (isset($plugin_definition[$class_name]['class'])) {
866
    // Plugin uses the verbose array form.
867
    $return = $plugin_definition[$class_name]['class'];
868
  }
869
  // @todo consider adding an else {watchdog(...)} here
870

    
871
  return ($return && class_exists($return)) ? $return : NULL;
872
}
873

    
874
/**
875
 * Load a plugin and get a class name from it, returning success only if the
876
 * class exists.
877
 *
878
 * @param $module
879
 *   The module that owns the plugin type.
880
 * @param $type
881
 *   The type of plugin.
882
 * @param $id
883
 *   The id of the specific plugin to load.
884
 * @param $class_name
885
 *   The identifier of the class. For example, 'handler'.
886
 *
887
 * @return
888
 *   The actual name of the class to call, or NULL if the class does not exist.
889
 */
890
function ctools_plugin_load_class($module, $type, $id, $class_name) {
891
  $plugin = ctools_get_plugins($module, $type, $id);
892
  return ctools_plugin_get_class($plugin, $class_name);
893
}
894

    
895
/**
896
 * Sort callback for sorting plugins naturally.
897
 *
898
 * Sort first by weight, then by title.
899
 */
900
function ctools_plugin_sort($a, $b) {
901
  if (is_object($a)) {
902
    $a = (array) $a;
903
  }
904
  if (is_object($b)) {
905
    $b = (array) $b;
906
  }
907

    
908
  if (empty($a['weight'])) {
909
    $a['weight'] = 0;
910
  }
911

    
912
  if (empty($b['weight'])) {
913
    $b['weight'] = 0;
914
  }
915

    
916
  if ($a['weight'] == $b['weight']) {
917
    return strnatcmp(strtolower($a['title']), strtolower($b['title']));
918
  }
919
  return ($a['weight'] < $b['weight']) ? -1 : 1;
920
}