- Patch #546336 by sun, dropcube: code clean-up and documentation improvements for the filter hooks.

5 files changed, 71 insertions, 73 deletions

diff --git a/modules/filter/filter.api.php b/modules/filter/filter.api.php
index 0e118d51e..f78824212 100644
--- a/modules/filter/filter.api.php
+++ b/modules/filter/filter.api.php
@@ -13,32 +13,31 @@
 
 /**
  * Define content filters.
- * 
- * Content in Drupal is passed through all enabled filters before it is
+ *
+ * Content in Drupal is passed through a group of filters before it is
  * output. This lets a module modify content to the site administrator's
  * liking.
  *
  * This hook allows modules to declare input filters they provide.
  *
- * A module can contain as many filters as it wants. The 'list' operation tells
- * the filter system which filters are available.
+ * A module can contain as many filters as it wants.
  *
  * Filtering is a two-step process. First, the content is 'prepared' by calling
- * the 'prepare callback' function for every filter. The purpose of the 'prepare callback'
- * is to escape HTML-like structures. For example, imagine a filter which allows the
- * user to paste entire chunks of programming code without requiring manual
- * escaping of special HTML characters like @< or @&. If the programming code
- * were left untouched, then other filters could think it was HTML and change
- * it. For most filters however, the prepare-step is not necessary, and they can
- * just return the input without changes.
+ * the 'prepare callback' function for every filter. The purpose of the 'prepare
+ * callback' is to escape HTML-like structures. For example, imagine a filter
+ * which allows the user to paste entire chunks of programming code without
+ * requiring manual escaping of special HTML characters like @< or @&. If the
+ * programming code were left untouched, then other filters could think it was
+ * HTML and change it. For most filters however, the prepare-step is not
+ * necessary, and they can just return the input without changes.
  *
- * Filters should not use the 'prepare callback' step for anything other than escaping,
- * because that would short-circuits the control the user has over the order
- * in which filters are applied.
+ * Filters should not use the 'prepare callback' step for anything other than
+ * escaping, because that would short-circuits the control the user has over the
+ * order in which filters are applied.
  *
- * The second step is the actual processing step. The result from the
- * prepare-step gets passed to all the filters again, this time with the
- * 'process callback' function. It's here that filters should perform actual changing of
+ * The second step is the actual processing step. The result from the prepare
+ * step gets passed to all the filters again, this time with the 'process
+ * callback' function. It's here that filters should perform actual changing of
  * the content: transforming URLs into hyperlinks, converting smileys into
  * images, etc.
  *
@@ -57,50 +56,52 @@
  * in the cache table and retrieved the next time the piece of content is
  * displayed. If a filter's output is dynamic it can override the cache
  * mechanism, but obviously this feature should be used with caution: having one
- * 'no cache' filter in a particular text format disables caching for the
- * entire format, not just for one filter.
+ * filter that doesn't support caching in a particular text format disables
+ * caching for the entire format, not just for one filter.
  *
  * Beware of the filter cache when developing your module: it is advised to set
- * your filter to 'no cache' while developing, but be sure to remove it again
- * if it's not needed. You can clear the cache by running the SQL query 'DELETE
- * FROM cache_filter';
+ * your filter to 'cache' => FALSE while developing, but be sure to remove it
+ * again if it's not needed. You can clear the cache by running the SQL query
+ * 'DELETE * FROM cache_filter';
  *
- * @return 
- *  An array of filter items. Each filter item has a numeric key corresponding to the
- *  filter delta in the module. The item is an associative array that may
- *  contain the following key-value pairs:
- *   - "name": Required. The name of the filter.
- *   - "description": Short description of what this filter does.
- *   - "prepare callback": The callback function to call in the 'prepare' step of 
- *     the filtering.
- *   - "process callback": Required. The callback function to call in the 'process' step of 
- *     the filtering.
- *   - "settings callback": The callback function that provides form controls for 
- *     the filter's settings. These settings are stored with variable_set() when
- *     the form is submitted. Remember to use the $format identifier in the variable
- *     and control names  to store settings per text format (e.g. "mymodule_setting_$format").
- *   - "tips callback": The callback function that provide tips for using filters.
- *     A module's tips should be informative and to the point. Short tips are
- *     preferably one-liners.
- *   - "cache": Specify if the filter result can be cached. TRUE by default.
+ * @return
+ *   An array of filter items. Each filter item has a unique name, prefixed
+ *   with the name of the module that provides it. The item is an associative
+ *   array that may contain the following key-value pairs:
+ *   - 'title': Required. The title of the filter.
+ *   - 'description': Short description of what this filter does.
+ *   - 'prepare callback': The callback function to call in the 'prepare' step
+ *     of the filtering.
+ *   - 'process callback': Required. The callback function to call in the
+ *     'process' step of the filtering.
+ *   - 'settings callback': The callback function that provides form controls
+ *     for the filter's settings. These settings are stored with variable_set()
+ *     when the form is submitted. Remember to use the $format identifier in the
+ *     variable and control names  to store settings per text format (e.g.
+ *     'mymodule_setting_$format').
+ *   - 'tips callback': The callback function that provide tips for using
+ *     filters. A module's tips should be informative and to the point. Short
+ *     tips are preferably one-liners.
+ *   - 'cache': Specify if the filter result can be cached. TRUE by default.
  *
  * For a detailed usage example, see filter_example.module. For an example of
  * using multiple filters in one module, see filter_filter_info().
  */
 function hook_filter_info() {
-  $filters[0] = array(
-    'name' => t('Limit allowed HTML tags'),
+  $filters['filter_html'] = array(
+    'title' => t('Limit allowed HTML tags'),
     'description' => t('Allows you to restrict the HTML tags the user can use. It will also remove harmful content such as JavaScript events, JavaScript URLs and CSS styles from those tags that are not removed.'),
     'process callback' => '_filter_html',
     'settings callback' => '_filter_html_settings',
-    'tips callback'  => '_filter_html_tips'
+    'tips callback' => '_filter_html_tips',
   );
-  $filters[1] = array(
-    'name' => t('Convert line breaks'),
+  $filters['filter_autop'] = array(
+    'title' => t('Convert line breaks'),
     'description' => t('Converts line breaks into HTML (i.e. &lt;br&gt; and &lt;p&gt;) tags.'),
     'process callback' => '_filter_autop',
-    'tips callback' => '_filter_autop_tips'
+    'tips callback' => '_filter_autop_tips',
   );
+  return $filters;
 }
 
 /**
@@ -111,7 +112,7 @@ function hook_filter_info() {
  *   implementations.
  */
 function hook_filter_info_alter(&$info) {
-  // Replace the PHP evaluator process callback with an improved 
+  // Replace the PHP evaluator process callback with an improved
   // PHP evaluator provided by a module.
   $info['php_code']['process callback'] = 'my_module_php_evaluator';
 }
diff --git a/modules/filter/filter.install b/modules/filter/filter.install
index 1b3c238bb..78ca255ae 100644
--- a/modules/filter/filter.install
+++ b/modules/filter/filter.install
@@ -153,10 +153,10 @@ function filter_update_7003() {
       '4' => 'filter_html_escape',
     ),
     'php' => array(
-      '0' => 'php_code'
-    )
+      '0' => 'php_code',
+    ),
   );
-  
+
   // Rename field 'delta' to 'name'.
   db_drop_unique_key($ret, 'filter', 'fmd');
   db_drop_index($ret, 'filter', 'list');
@@ -174,10 +174,10 @@ function filter_update_7003() {
       ),
       'indexes' => array(
         'list' => array('format', 'weight', 'module', 'name'),
-      )      
+      ),
     )
   );
-    
+
   // Loop through each filter and make changes to the core filter table.
   foreach ($renamed_deltas as $module => $deltas) {
     foreach ($deltas as $old_delta => $new_delta) {
diff --git a/modules/filter/filter.module b/modules/filter/filter.module
index 27b7a4edb..8331c7c85 100644
--- a/modules/filter/filter.module
+++ b/modules/filter/filter.module
@@ -730,26 +730,29 @@ function theme_filter_guidelines($format) {
  * Filters implemented by the filter.module.
  */
 
+/**
+ * Implement hook_filter_info().
+ */
 function filter_filter_info() {
   $filters['filter_html'] = array(
     'title' => t('Limit allowed HTML tags'),
     'description' => t('Allows you to restrict the HTML tags the user can use. It will also remove harmful content such as JavaScript events, JavaScript URLs and CSS styles from those tags that are not removed.'),
     'process callback' => '_filter_html',
     'settings callback' => '_filter_html_settings',
-    'tips callback'  => '_filter_html_tips'
+    'tips callback' => '_filter_html_tips',
   );
   $filters['filter_autop'] = array(
     'title' => t('Convert line breaks'),
     'description' => t('Converts line breaks into HTML (i.e. &lt;br&gt; and &lt;p&gt;) tags.'),
     'process callback' => '_filter_autop',
-    'tips callback' => '_filter_autop_tips'
+    'tips callback' => '_filter_autop_tips',
   );
   $filters['filter_url'] = array(
     'title' => t('Convert URLs into links'),
     'description' => t('Turns web and e-mail addresses into clickable links.'),
     'process callback' => '_filter_url',
     'settings callback' => '_filter_url_settings',
-    'tips callback' => '_filter_url_tips'
+    'tips callback' => '_filter_url_tips',
   );
   $filters['filter_htmlcorrector'] = array(
     'title' =>  t('Correct broken HTML'),
@@ -760,13 +763,13 @@ function filter_filter_info() {
     'title' => t('Escape all HTML'),
     'description' => t('Escapes all HTML tags, so they will be visible instead of being effective.'),
     'process callback' => '_filter_html_escape',
-    'tips callback' => '_filter_html_escape_tips'
+    'tips callback' => '_filter_html_escape_tips',
   );
   return $filters;
 }
 
 /**
- * Settings for the HTML filter.
+ * Settings callback for the HTML filter.
  */
 function _filter_html_settings($format) {
   $form['filter_html'] = array(
@@ -817,7 +820,7 @@ function _filter_html($text, $format) {
 }
 
 /**
- * Settings for URL filter.
+ * Settings callback for URL filter.
  */
 function _filter_url_settings($format) {
   $form['filter_urlfilter'] = array(
diff --git a/modules/filter/filter.test b/modules/filter/filter.test
index 24157e450..6a2c7ada2 100644
--- a/modules/filter/filter.test
+++ b/modules/filter/filter.test
@@ -422,7 +422,7 @@ class FilterUnitTest extends DrupalWebTestCase {
    *   or better a whitelist approach should be used for that too.
    */
   function testFilter() {
-    $format = "fake format";
+    $format = 'fake_format';
 
     // HTML filter is not able to secure some tags, these should never be
     // allowed.
diff --git a/modules/php/php.module b/modules/php/php.module
index 86e8d5d43..4dd23f5ea 100644
--- a/modules/php/php.module
+++ b/modules/php/php.module
@@ -6,7 +6,6 @@
  * Additional filter for PHP input.
  */
 
-
 /**
  * Implement hook_help().
  */
@@ -120,22 +119,17 @@ else {
 
 /**
  * Implement hook_filter_info().
- * 
- * Contains a basic PHP evaluator.
  *
- * Executes PHP code. Use with care.
+ * Provide PHP code filter. Use with care.
  */
 function php_filter_info() {
-  return array(
-    'php_code' => array(
-      'title' => t('PHP evaluator'),
-      'description' => t('Executes a piece of PHP code. The usage of this filter should be restricted to administrators only!'), 
-      'cache' => FALSE,
-      'process callback' => 'php_eval',
-      'tips callback' => '_php_filter_tips'
-    )
+  $filters['php_code'] = array(
+    'title' => t('PHP evaluator'),
+    'description' => t('Executes a piece of PHP code. The usage of this filter should be restricted to administrators only!'),
+    'process callback' => 'php_eval',
+    'tips callback' => '_php_filter_tips',
+    'cache' => FALSE,
   );
+  return $filters;
 }
 
-
-