- Patch ##525540 by jvandyk, sun, jhodgdon, fago | webchick, TheRec, Dave Reid, brianV, sun.core, cweagans, Dries: gave trigger.module and includes/actions.inc an API overhaul. Simplified definitions of actions and triggers and removed dependency on the combination of hooks and operations. Triggers now directly map to module hooks.

1 files changed, 75 insertions, 105 deletions

diff --git a/includes/actions.inc b/includes/actions.inc
index 5650bc64f..65089b6ac 100644
--- a/includes/actions.inc
+++ b/includes/actions.inc
@@ -7,35 +7,31 @@
  */
 
 /**
- * Perform a given list of actions by executing their callback functions.
+ * Performs a given list of actions by executing their callback functions.
  *
- * Given the IDs of actions to perform, find out what the callbacks
- * for the actions are by querying the database. Then call each callback
- * using the function call $function($object, $context, $a1, $a2)
- * where $function is the name of a function written in compliance with
- * the action specification; that is, foo($object, $context).
+ * Given the IDs of actions to perform, this function finds out what the
+ * callback functions for the actions are by querying the database. Then
+ * it calls each callback using the function call $function($object, $context,
+ * $a1, $a2), passing the input arguments of this function (see below) to the
+ * action function.
  *
  * @param $action_ids
- *   The ID of the action to perform. Can be a single action ID or an array
- *   of IDs. IDs of instances will be numeric; IDs of singletons will be
- *   function names.
+ *   The IDs of the actions to perform. Can be a single action ID or an array
+ *   of IDs. IDs of configurable actions must be given as numeric action IDs;
+ *   IDs of non-configurable actions may be given as action function names.
  * @param $object
- *   Parameter that will be passed along to the callback. Typically the
- *   object that the action will act on; a node, user or comment object.
+ *   The object that the action will act on: a node, user, or comment object.
  * @param $context
- *   Parameter that will be passed along to the callback. $context is a
- *   keyed array containing extra information about what is currently
- *   happening at the time of the call. Typically $context['hook'] and
- *   $context['op'] will tell which hook-op combination resulted in this
- *   call to actions_do().
+ *   Associative array containing extra information about what triggered
+ *   the action call, with $context['hook'] giving the name of the hook
+ *   that resulted in this call to actions_do().
  * @param $a1
- *   Parameter that will be passed along to the callback.
+ *   Passed along to the callback.
  * @param $a2
- *   Parameter that will be passed along to the callback.
- *
+ *   Passed along to the callback.
  * @return
- *   An associative array containing the result of the function that
- *   performs the action, keyed on action ID.
+ *   An associative array containing the results of the functions that
+ *   perform the actions, keyed on action ID.
  */
 function actions_do($action_ids, $object = NULL, $context = NULL, $a1 = NULL, $a2 = NULL) {
   // $stack tracks the number of recursive calls.
@@ -109,49 +105,20 @@ function actions_do($action_ids, $object = NULL, $context = NULL, $a1 = NULL, $a
 }
 
 /**
- * Discover all action functions by invoking hook_action_info().
- *
- * @code
- * mymodule_action_info() {
- *   return array(
- *     'mymodule_functiondescription_action' => array(
- *       'type' => 'node',
- *       'description' => t('Save node'),
- *       'configurable' => FALSE,
- *       'hooks' => array(
- *         'node' => array('delete', 'insert', 'update', 'view'),
- *         'comment' => array('delete', 'insert', 'update', 'view'),
- *       )
- *     )
- *   );
- * }
- * @endcode
+ * Discovers all available actions by invoking hook_action_info().
  *
- * The description is used in presenting possible actions to the user for
- * configuration. The type is used to present these actions in a logical
- * grouping and to denote context. Some types are 'node', 'user', 'comment',
- * and 'system'. If an action is configurable it will provide form,
- * validation and submission functions. The hooks the action supports
- * are declared in the 'hooks' array.
+ * This function contrasts with actions_get_all_actions(); see the
+ * documentation of actions_get_all_actions() for an explanation.
  *
  * @param $reset
  *   Reset the action info static cache.
- *
  * @return
- *   An associative array keyed on function name. The value of each key is
- *   an array containing information about the action, such as type of
- *   action and description of the action, e.g.:
- *   @code
- *   $actions['node_publish_action'] = array(
- *     'type' => 'node',
- *     'description' => t('Publish post'),
- *     'configurable' => FALSE,
- *     'hooks' => array(
- *       'node' => array('presave', 'insert', 'update', 'view'),
- *       'comment' => array('delete', 'insert', 'update', 'view'),
- *     ),
- *   );
- *   @endcode
+ *   An associative array keyed on action function name, with the same format
+ *   as the return value of hook_action_info(), containing all
+ *   modules' hook_action_info() return values as modified by any
+ *   hook_action_info_alter() implementations.
+ *
+ * @see hook_action_info()
  */
 function actions_list($reset = FALSE) {
   static $actions;
@@ -165,19 +132,24 @@ function actions_list($reset = FALSE) {
 }
 
 /**
- * Retrieve all action instances from the database.
+ * Retrieves all action instances from the database.
  *
- * Compare with actions_list() which gathers actions by invoking
- * hook_action_info(). The two are synchronized by visiting
- * /admin/structure/actions (when actions.module is enabled) which runs
- * actions_synchronize().
+ * This function differs from the actions_list() function, which gathers
+ * actions by invoking hook_action_info(). The actions returned by this
+ * function and the actions returned by actions_list() are partially
+ * synchronized. Non-configurable actions from hook_action_info()
+ * implementations are put into the database when actions_synchronize() is
+ * called, which happens when admin/config/system/actions is visited. Configurable
+ * actions are not added to the database until they are configured in the
+ * user interface, in which case a database row is created for each
+ * configuration of each action.
  *
  * @return
- *   Associative array keyed by action ID. Each value is an associative array
- *   with keys 'callback', 'description', 'type' and 'configurable'.
+ *   Associative array keyed by numeric action ID. Each value is an associative
+ *   array with keys 'callback', 'label', 'type' and 'configurable'.
  */
 function actions_get_all_actions() {
-  $actions = db_query("SELECT aid, type, callback, parameters, description FROM {actions}")->fetchAllAssoc('aid', PDO::FETCH_ASSOC);
+  $actions = db_query("SELECT aid, type, callback, parameters, label FROM {actions}")->fetchAllAssoc('aid', PDO::FETCH_ASSOC);
   foreach ($actions as &$action) {
     $action['configurable'] = (bool) $action['parameters'];
     unset($action['parameters']);
@@ -187,28 +159,26 @@ function actions_get_all_actions() {
 }
 
 /**
- * Create an associative array keyed by md5 hashes of function names.
+ * Creates an associative array keyed by md5 hashes of function names or IDs.
  *
  * Hashes are used to prevent actual function names from going out into HTML
  * forms and coming back.
  *
  * @param $actions
- *   An associative array with function names as keys and associative arrays
- *   with keys 'description', 'type', etc. as values. Generally the output of
- *   actions_list() or actions_get_all_actions() is given as input to this
- *   function.
- *
+ *   An associative array with function names or action IDs as keys
+ *   and associative arrays with keys 'label', 'type', etc. as values.
+ *   This is usually the output of actions_list() or actions_get_all_actions().
  * @return
- *   An associative array keyed on md5 hash of function names. The value of
- *   each key is an associative array of function, description, and type for
- *   the action.
+ *   An associative array whose keys are md5 hashes of the input array keys, and
+ *   whose corresponding values are associative arrays with components
+ *   'callback', 'label', 'type', and 'configurable' from the input array.
  */
 function actions_actions_map($actions) {
   $actions_map = array();
   foreach ($actions as $callback => $array) {
     $key = md5($callback);
     $actions_map[$key]['callback']     = isset($array['callback']) ? $array['callback'] : $callback;
-    $actions_map[$key]['description']  = $array['description'];
+    $actions_map[$key]['label']        = $array['label'];
     $actions_map[$key]['type']         = $array['type'];
     $actions_map[$key]['configurable'] = $array['configurable'];
   }
@@ -216,17 +186,19 @@ function actions_actions_map($actions) {
 }
 
 /**
- * Given an md5 hash of a function name, return the function name.
+ * Given an md5 hash of an action array key, returns the key (function or ID).
  *
- * Faster than actions_actions_map() when you only need the function name.
+ * Faster than actions_actions_map() when you only need the function name or ID.
  *
  * @param $hash
- *   MD5 hash of a function name.
- *
+ *   MD5 hash of a function name or action ID array key. The array key
+ *   is a key into the return value of actions_list() (array key is the action
+ *   function name) or actions_get_all_actions() (array key is the action ID).
  * @return
- *   The corresponding function name or FALSE if none is found.
+ *   The corresponding array key, or FALSE if no match is found.
  */
 function actions_function_lookup($hash) {
+  // Check for a function name match.
   $actions_list = actions_list();
   foreach ($actions_list as $function => $array) {
     if (md5($function) == $hash) {
@@ -234,26 +206,26 @@ function actions_function_lookup($hash) {
     }
   }
 
-  // Must be an instance; must check database.
+  // Must be a configurable action; check database.
   return db_query("SELECT aid FROM {actions} WHERE MD5(aid) = :hash AND parameters <> ''", array(':hash' => $hash))->fetchField();
 }
 
 /**
- * Synchronize actions that are provided by modules.
+ * Synchronizes actions that are provided by modules in hook_action_info().
  *
- * Actions provided by modules are synchronized with actions that are stored in
- * the actions table. This is necessary so that actions that do not require
- * configuration can receive action IDs. This is not necessarily the best
- * approach, but it is the most straightforward.
+ * Actions provided by modules in hook_action_info() implementations are
+ * synchronized with actions that are stored in the actions database table.
+ * This is necessary so that actions that do not require configuration can
+ * receive action IDs.
  *
  * @param $delete_orphans
- *   Boolean if TRUE, any actions that exist in the database but are no longer
+ *   If TRUE, any actions that exist in the database but are no longer
  *   found in the code (for example, because the module that provides them has
  *   been disabled) will be deleted.
  */
 function actions_synchronize($delete_orphans = FALSE) {
   $actions_in_code = actions_list(TRUE);
-  $actions_in_db = db_query("SELECT aid, callback, description FROM {actions} WHERE parameters = ''")->fetchAllAssoc('callback', PDO::FETCH_ASSOC);
+  $actions_in_db = db_query("SELECT aid, callback, label FROM {actions} WHERE parameters = ''")->fetchAllAssoc('callback', PDO::FETCH_ASSOC);
 
   // Go through all the actions provided by modules.
   foreach ($actions_in_code as $callback => $array) {
@@ -272,10 +244,10 @@ function actions_synchronize($delete_orphans = FALSE) {
             'type' => $array['type'],
             'callback' => $callback,
             'parameters' => '',
-            'description' => $array['description'],
+            'label' => $array['label'],
             ))
           ->execute();
-        watchdog('actions', "Action '%action' added.", array('%action' => filter_xss_admin($array['description'])));
+        watchdog('actions', "Action '%action' added.", array('%action' => filter_xss_admin($array['label'])));
       }
     }
   }
@@ -285,10 +257,10 @@ function actions_synchronize($delete_orphans = FALSE) {
     $orphaned = array_keys($actions_in_db);
 
     if ($delete_orphans) {
-      $actions = db_query('SELECT aid, description FROM {actions} WHERE callback IN (:orphaned)', array(':orphaned' => $orphaned))->fetchAll();
+      $actions = db_query('SELECT aid, label FROM {actions} WHERE callback IN (:orphaned)', array(':orphaned' => $orphaned))->fetchAll();
       foreach ($actions as $action) {
         actions_delete($action->aid);
-        watchdog('actions', "Removed orphaned action '%action' from database.", array('%action' => filter_xss_admin($action->description)));
+        watchdog('actions', "Removed orphaned action '%action' from database.", array('%action' => filter_xss_admin($action->label)));
       }
     }
     else {
@@ -301,7 +273,7 @@ function actions_synchronize($delete_orphans = FALSE) {
 }
 
 /**
- * Save an action and its associated user-supplied parameter values to the database.
+ * Saves an action and its user-supplied parameter values to the database.
  *
  * @param $function
  *   The name of the function to be called when this action is performed.
@@ -311,16 +283,15 @@ function actions_synchronize($delete_orphans = FALSE) {
  * @param $params
  *   An associative array with parameter names as keys and parameter values as
  *   values.
- * @param $desc
- *   A user-supplied description of this particular action, e.g., 'Send e-mail
+ * @param $label
+ *   A user-supplied label of this particular action, e.g., 'Send e-mail
  *   to Jim'.
  * @param $aid
  *   The ID of this action. If omitted, a new action is created.
- *
  * @return
  *   The ID of the action.
  */
-function actions_save($function, $type, $params, $desc, $aid = NULL) {
+function actions_save($function, $type, $params, $label, $aid = NULL) {
   // aid is the callback for singleton actions so we need to keep a separate
   // table for numeric aids.
   if (!$aid) {
@@ -333,29 +304,28 @@ function actions_save($function, $type, $params, $desc, $aid = NULL) {
       'callback' => $function,
       'type' => $type,
       'parameters' => serialize($params),
-      'description' => $desc,
+      'label' => $label,
     ))
     ->execute();
 
-  watchdog('actions', 'Action %action saved.', array('%action' => $desc));
+  watchdog('actions', 'Action %action saved.', array('%action' => $label));
   return $aid;
 }
 
 /**
- * Retrieve a single action from the database.
+ * Retrieves a single action from the database.
  *
  * @param $aid
  *   The ID of the action to retrieve.
- *
  * @return
  *   The appropriate action row from the database as an object.
  */
 function actions_load($aid) {
-  return db_query("SELECT aid, type, callback, parameters, description FROM {actions} WHERE aid = :aid", array(':aid' => $aid))->fetchObject();
+  return db_query("SELECT aid, type, callback, parameters, label FROM {actions} WHERE aid = :aid", array(':aid' => $aid))->fetchObject();
 }
 
 /**
- * Delete a single action from the database.
+ * Deletes a single action from the database.
  *
  * @param $aid
  *   The ID of the action to delete.