diff --git a/includes/plugins.inc b/includes/plugins.inc index d524f74..8b0da84 100644 --- a/includes/plugins.inc +++ b/includes/plugins.inc @@ -419,19 +419,20 @@ function ctools_get_plugins_reset() { /** * Load plugins from a directory. * - * @param $info + * @param array $info * The plugin info as returned by ctools_plugin_get_info() - * @param $file + * @param string $filename * The file to load if we're looking for just one particular plugin. * - * @return - * An array of information created for this plugin. + * @return array + * A (possibly empty) array of information created for this plugin. */ function ctools_plugin_load_includes($info, $filename = NULL) { // Keep a static array so we don't hit file_scan_directory more than necessary. $all_files = &drupal_static(__FUNCTION__, array()); - // store static of plugin arrays for reference because they can't be reincluded. + // Store static of plugin arrays for reference because they can't be + // reincluded, so there is no point in using drupal_static(). static $plugin_arrays = array(); if (!isset($all_files[$info['module']][$info['type']])) { @@ -477,7 +478,6 @@ function ctools_plugin_load_includes($info, $filename = NULL) { $identifier = $plugin_arrays[$file->uri]; } else { - include_once DRUPAL_ROOT . '/' . $file->uri; // .inc files have a special format for the hook identifier. // For example, 'foo.inc' in the module 'mogul' using the plugin @@ -496,7 +496,8 @@ function ctools_plugin_load_includes($info, $filename = NULL) { } } - $result = ctools_plugin_process($info, $module, $identifier, dirname($file->uri), basename($file->uri), $file->name); + $result = ctools_plugin_process($info, $module, $identifier, + dirname($file->uri), basename($file->uri), $file->name); } if (is_array($result)) { $plugins = array_merge($plugins, $result); @@ -542,14 +543,14 @@ function ctools_plugin_get_directories($info) { } /** - * Helper function to build a ctools-friendly list of themes capable of - * providing plugins. + * Helper to build a ctools-friendly list of themes capable of providing plugins. * * @return array $themes * A list of themes that can act as plugin providers, sorted parent-first with * the active theme placed last. */ function _ctools_list_themes() { + // @TODO: Use drupal_static() here? static $themes; if (is_null($themes)) { $current = variable_get('theme_default', FALSE); @@ -603,9 +604,10 @@ function _ctools_list_themes() { * The name of the theme whose base we are looking for. * @param $used_keys * A recursion parameter preventing endless loops. - * @return + * + * @return array * Returns an array of all of the theme's ancestors; the first element's value - * will be NULL if an error occurred. + * will be NULL if an error occurred. (Note: this is NOT $arr[0]). */ function ctools_find_base_themes($themes, $key, $used_keys = array()) { $base_key = $themes[$key]->info['base theme']; @@ -658,22 +660,28 @@ function ctools_plugin_load_hooks($info) { /** * Process a single hook implementation of a ctools plugin. * - * @param $info + * @param array $info * The $info array about the plugin as returned by ctools_plugin_get_info() - * @param $module + * @param string $module * The module that implements the plugin being processed. - * @param $identifier - * The plugin identifier, which is used to create the name of the hook - * function being called. - * @param $path + * @param string|array $identifier + * Used to create the base setting of return value. If: + * - $identifier is a string, a hook name is created from this and the 'hook' + * key of the $info array, and the return value of that hook function is + * used. The hook is called like this: $identifier_$hook($info); + * - $identifier is an array, this array is used directly. + * @param string $path * The path where files utilized by this plugin will be found. - * @param $file + * @param string $file * The file that was loaded for this plugin, if it exists. - * @param $base + * @param string $base * The base plugin name to use. If a file was loaded for the plugin, this * is the plugin to assume must be present. This is used to automatically * translate the array to make the syntax more friendly to plugin * implementors. + * + * @return NULL|array + * NULL on failure, otherwise an array containing the results keyed by name. */ function ctools_plugin_process($info, $module, $identifier, $path, $file = NULL, $base = NULL) { if (is_array($identifier)) { @@ -741,9 +749,19 @@ function _ctools_process_data($result, $plugin_type_info, $module, $path, $file) return $result; } - /** * Process an info file for plugin information, rather than a hook. + * + * @param array $info + * The $info array about the plugin as returned by ctools_plugin_get_info() + * @param string $module + * The module that implements the plugin being processed. + * @param object $file + * An object containing 'uri' and 'name' properties. 'uri' is the name of the + * 'info' file to process. 'name' is the plugin key-name. + * + * @return NULL|array + * NULL on failure, otherwise an array containing the results keyed by name. */ function ctools_plugin_process_info($info, $module, $file) { $result = drupal_parse_info_file($file->uri); @@ -770,7 +788,7 @@ function ctools_plugin_get_info($module, $type) { * @param $function_name * The identifier of the function. For example, 'settings form'. * - * @return + * @return string * The actual name of the function to call, or NULL if the function * does not exist. */ @@ -787,7 +805,7 @@ function ctools_plugin_get_function($plugin_definition, $function_name) { } if (!isset($plugin_definition[$function_name])) { - return; + return NULL; } if (is_array($plugin_definition[$function_name]) && isset($plugin_definition[$function_name]['function'])) { @@ -822,7 +840,7 @@ function ctools_plugin_get_function($plugin_definition, $function_name) { * @param $function_name * The identifier of the function. For example, 'settings form'. * - * @return + * @return string * The actual name of the function to call, or NULL if the function * does not exist. */ @@ -840,7 +858,7 @@ function ctools_plugin_load_function($module, $type, $id, $function_name) { * @param $class_name * The identifier of the class. For example, 'handler'. * - * @return + * @return string * The actual name of the class to call, or NULL if the class does not exist. */ function ctools_plugin_get_class($plugin_definition, $class_name) { @@ -885,7 +903,7 @@ function ctools_plugin_get_class($plugin_definition, $class_name) { * @param $class_name * The identifier of the class. For example, 'handler'. * - * @return + * @return string * The actual name of the class to call, or NULL if the class does not exist. */ function ctools_plugin_load_class($module, $type, $id, $class_name) { diff --git a/plugins/cache/export_ui.inc b/plugins/cache/export_ui.inc index c5960af..469edac 100644 --- a/plugins/cache/export_ui.inc +++ b/plugins/cache/export_ui.inc @@ -14,8 +14,8 @@ $plugin = array( // Some operations use a 'finalize' but that really just means set // for us, since we're not using temporary storage for subsystems. 'cache finalize' => 'ctools_cache_export_ui_cache_set', - // @todo The API specifications say that a 'cache clear' callback is - // required, but one is not provided? + // @todo The API specifications say that a 'cache clear' callback is required, + // but there is none provided? // @see cache.inc // 'cache clear' => ??? ); diff --git a/tests/ctools.plugins.test b/tests/ctools.plugins.test index 0b7fe26..78d0adb 100644 --- a/tests/ctools.plugins.test +++ b/tests/ctools.plugins.test @@ -27,12 +27,16 @@ class CtoolsPluginsGetInfoTestCase extends DrupalWebTestCase { } /** + * Assert helper to check that a specific plugin function exists. * - * - * @param string $module - * @param string $type - * @param mixed $id - * @param string $function + * @param $module + * The module that owns the plugin. + * @param $type + * The type of plugin. + * @param $id + * The id of the specific plugin to load. + * @param $function + * The identifier of the function. For example, 'settings form'. */ protected function assertPluginFunction($module, $type, $id, $function = 'function') { $func = ctools_plugin_load_function($module, $type, $id, $function); @@ -46,12 +50,16 @@ class CtoolsPluginsGetInfoTestCase extends DrupalWebTestCase { } /** + * Assert helper to check that a specific plugin function does NOT exist. * - * - * @param string $module - * @param string $type - * @param mixed $id - * @param string $function + * @param $module + * The module that owns the plugin. + * @param $type + * The type of plugin. + * @param $id + * The id of the specific plugin to load. + * @param $function + * The identifier of the function. For example, 'settings form'. */ protected function assertPluginMissingFunction($module, $type, $id, $function = 'function') { $func = ctools_plugin_load_function($module, $type, $id, $function); @@ -63,6 +71,18 @@ class CtoolsPluginsGetInfoTestCase extends DrupalWebTestCase { ))); } + /** + * Assert helper to check that a plugin can be loaded using a named class. + * + * @param $module + * The module that owns the plugin. + * @param $type + * The type of plugin. + * @param $id + * The id of the specific plugin to load. + * @param string $class + * The name of the PHP class to load. + */ protected function assertPluginClass($module, $type, $id, $class = 'handler') { $class_name = ctools_plugin_load_class($module, $type, $id, $class); $this->assertTrue(class_exists($class_name), t('Plugin @plugin of plugin type @module:@type successfully retrieved @retrieved for @class.', array( @@ -75,12 +95,16 @@ class CtoolsPluginsGetInfoTestCase extends DrupalWebTestCase { } /** + * Assert helper to check that a plugin DOES NOT contain the named class. * - * - * @param string $module - * @param string $type - * @param mixed $id - * @param string $function + * @param $module + * The module that owns the plugin. + * @param $type + * The type of plugin. + * @param $id + * The id of the specific plugin to load. + * @param string $class + * The name of the PHP class to load. */ protected function assertPluginMissingClass($module, $type, $id, $class = 'handler') { $class_name = ctools_plugin_load_class($module, $type, $id, $class); diff --git a/tests/object_cache_unit.test b/tests/object_cache_unit.test index 55da293..97b672f 100644 --- a/tests/object_cache_unit.test +++ b/tests/object_cache_unit.test @@ -3,7 +3,7 @@ /** * Test ctools_cache_find_plugin and the structure of the default cache plugins. */ -class CtoolsUnitObjectCachePlugins extends DrupalUnitTestCase { +class CtoolsUnitObjectCachePlugins extends DrupalWebTestCase { /** * {@inheritDoc} diff --git a/tests/uuid_with_uuid.test b/tests/uuid_with_uuid.test index 13ff0ac..e6e65c5 100644 --- a/tests/uuid_with_uuid.test +++ b/tests/uuid_with_uuid.test @@ -13,8 +13,8 @@ class CtoolsUUIDWithUUID extends DrupalWebTestCase { 'name' => 'UUID handing, with UUID module', 'description' => 'Check that the CTools UUID functions behave correctly when the UUID module is installed.', 'group' => 'ctools', - 'dependencies' => array('ctools'), - // 'dependencies' => array('ctools', 'uuid'), + // 'dependencies' => array('ctools'), + 'dependencies' => array('ctools', 'uuid'), ); } diff --git a/tests/uuid_without_uuid.test b/tests/uuid_without_uuid.test index e90a19b..6d62ebf 100644 --- a/tests/uuid_without_uuid.test +++ b/tests/uuid_without_uuid.test @@ -93,7 +93,7 @@ class CtoolsUUIDWithoutUUID extends DrupalWebTestCase { '8f4ca4fd-154e-5063-b6db-aa91af137037' => TRUE, // version 5 ); - foreach($checks as $uuid => $exp) { + foreach ($checks as $uuid => $exp) { $this->assertEqual(ctools_uuid_is_valid($uuid), $exp, 'Is Valid: UUIDs match expectations: ' . $uuid); } }