Projet

Général

Profil

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

root / drupal7 / sites / all / modules / ctools / includes / plugins.inc @ 3aa14731

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 == $minimum_version) || ($version == $current_version)
83
        || (version_compare($version, $minimum_version, '>=')
84
        && version_compare($version, $current_version, '<='))) {
85
        if (!isset($info['path'])) {
86
          $info['path'] = drupal_get_path('module', $module);
87
        }
88
        $cache[$owner][$api][$module] = $info;
89
      }
90
    }
91

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

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

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

    
118
  return $cache[$owner][$api];
119
}
120

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

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

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

    
171
  return $info;
172
}
173

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

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

    
197
  return $hook;
198
}
199

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

    
225
  $info = ctools_plugin_get_plugin_type_info();
226

    
227
  // Bail out noisily if an invalid module/type combination is requested.
228
  if (!isset($info[$module][$type])) {
229
    watchdog('ctools', 'Invalid plugin module/type combination requested: module @module and type @type', array('@module' => $module, '@type' => $type), WATCHDOG_ERROR);
230
    return array();
231
  }
232

    
233
  // Make sure our plugins array is populated.
234
  if (!isset($plugins[$module][$type])) {
235
    $plugins[$module][$type] = array();
236
  }
237

    
238
  // Attempt to shortcut this whole piece of code if we already have
239
  // the requested plugin:
240
  if ($id && array_key_exists($id, $plugins[$module][$type])) {
241
    return $plugins[$module][$type][$id];
242
  }
243

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

    
248
  // We assume we don't need to build a cache.
249
  $build_cache = FALSE;
250

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

    
255
    if (!empty($cache->data)) {
256
      // Cache load succeeded so use the cached plugin list.
257
      $plugins[$module][$type]   = $cache->data;
258
      // Set $setup to true so we know things where loaded.
259
      $setup[$module][$type]     = TRUE;
260
    }
261
    else {
262
      // Cache load failed so store that we need to build and write the cache.
263
      $build_cache = TRUE;
264
    }
265
  }
266

    
267
  // Always load all hooks if we need them. Note we only need them now if the
268
  // plugin asks for them. We can assume that if we have plugins we've already
269
  // called the global hook.
270
  if (!empty($info[$module][$type]['use hooks']) && empty($plugins[$module][$type])) {
271
    $plugins[$module][$type] = ctools_plugin_load_hooks($info[$module][$type]);
272
  }
273

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

    
298

    
299
  // If we were told earlier that this is cacheable and the cache was
300
  // empty, give something back.
301
  if ($build_cache) {
302
    cache_set("plugins:$module:$type", $plugins[$module][$type], $info[$module][$type]['cache table']);
303
  }
304

    
305
  // If no id was requested, we are finished here:
306
  if (!$id) {
307
    // Use array_filter because looking for unknown plugins could cause NULL
308
    // entries to appear in the list later.
309
    return array_filter($plugins[$module][$type]);
310
  }
311

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

    
323
    if (!array_key_exists($parent, $plugins[$module][$type])) {
324
      $result = ctools_plugin_load_includes($info[$module][$type], $parent);
325
      // Set to either what was returned or NULL.
326
      $plugins[$module][$type][$parent] = isset($result[$parent]) ? $result[$parent] : NULL;
327
    }
328

    
329
    // If we are looking for a child, and have the parent, ask the parent for the child.
330
    if (!empty($child) && !empty($plugins[$module][$type][$parent]) && function_exists($plugins[$module][$type][$parent]['get child'])) {
331
      $plugins[$module][$type][$id] = $plugins[$module][$type][$parent]['get child']($plugins[$module][$type][$parent], $parent, $child);
332
    }
333
  }
334

    
335
  // At this point we should either have the plugin, or a NULL.
336
  return $plugins[$module][$type][$id];
337
}
338

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

    
361
  // Only trigger info loading once.
362
  if ($info_loaded && !$flush) {
363
    return $all_type_info;
364
  }
365
  $info_loaded = TRUE;
366

    
367
  $cache = cache_get('ctools_plugin_type_info');
368
  if (!empty($cache->data) && !$flush) {
369
    // Plugin type info cache is warm, use it.
370
    $all_type_info = $cache->data;
371
  }
372
  else {
373
    // Cache expired, refill it.
374
    foreach (module_implements('ctools_plugin_type') as $module) {
375
      $module_infos = array();
376
      $function = $module . '_ctools_plugin_type';
377
      $module_infos = $function();
378

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

    
402
  return $all_type_info;
403
}
404

    
405
/**
406
 * Reset all static caches that affect the result of ctools_get_plugins().
407
 */
408
function ctools_get_plugins_reset() {
409
  drupal_static_reset('ctools_plugins');
410
  drupal_static_reset('ctools_plugin_setup');
411
  drupal_static_reset('ctools_plugin_load_includes');
412
  drupal_static_reset('ctools_plugin_api_info');
413
}
414

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

    
430
  // store static of plugin arrays for reference because they can't be reincluded.
431
  static $plugin_arrays = array();
432

    
433
  if (!isset($all_files[$info['module']][$info['type']])) {
434
    $cache = cache_get("ctools_plugin_files:$info[module]:$info[type]");
435
    if ($cache) {
436
      $all_files[$info['module']][$info['type']] = $cache->data;
437
    }
438
    // Do not attempt any file scan even if the cached entry was empty.
439
    // A NULL entry here would mean the plugin just does not exists, and we
440
    // cannot afford to run file scan on production sites normal run.
441
    elseif (!isset($all_files[$info['module']][$info['type']])) {
442
      $all_files[$info['module']][$info['type']] = array();
443
      // Load all our plugins.
444
      $directories = ctools_plugin_get_directories($info);
445
      $extension = (empty($info['info file']) || ($info['extension'] != 'inc')) ? $info['extension'] : 'info';
446

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

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

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

    
472
        if (isset($plugin_arrays[$file->uri])) {
473
          $identifier = $plugin_arrays[$file->uri];
474
        }
475
        else {
476

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

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

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

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

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

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

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

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

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

    
586

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

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

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

    
632

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

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

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

    
696
  return _ctools_process_data($result, $info, $module, $path, $file);
697
}
698

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

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

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

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

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

    
740

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

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

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

    
785
  if (!isset($plugin_definition[$function_name])) {
786
    return;
787
  }
788

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

    
803
  if (function_exists($function)) {
804
    return $function;
805
  }
806
}
807

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

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

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

    
868
  return ($return && class_exists($return)) ? $return : NULL;
869
}
870

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

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

    
905
  if (empty($a['weight'])) {
906
    $a['weight'] = 0;
907
  }
908

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

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