trigger.module 17.1 KB
Newer Older
1 2 3 4
<?php
// $Id$

/**
5 6 7 8
 * @file
 * Enables functions to be stored and executed at a later time when
 * triggered by other modules or by one of Drupal's core API hooks.
 */
9 10

/**
11 12
 * Implementation of hook_help().
 */
13
function trigger_help($path, $arg) {
14
  $explanation = '<p>' . t('Triggers are system events, such as when new content is added or when a user logs in. Trigger module combines these triggers with actions (functional tasks), such as unpublishing content or e-mailing an administrator. The <a href="@url">Actions settings page</a> contains a list of existing actions and provides the ability to create and configure additional actions.', array('@url' => url('admin/settings/actions'))) . '</p>';
15
  switch ($path) {
16
    case 'admin/build/trigger/comment':
17
      return $explanation . '<p>' . t('Below you can assign actions to run when certain comment-related triggers happen. For example, you could promote a post to the front page when a comment is added.') . '</p>';
18
    case 'admin/build/trigger/node':
19
      return $explanation . '<p>' . t('Below you can assign actions to run when certain content-related triggers happen. For example, you could send an e-mail to an administrator when a post is created or updated.') . '</p>';
20
    case 'admin/build/trigger/cron':
21
      return $explanation . '<p>' . t('Below you can assign actions to run during each pass of a <a href="@cron">cron maintenance task</a>.', array('@cron' => url('admin/reports/status'))) . '</p>';
22
    case 'admin/build/trigger/taxonomy':
23
      return $explanation . '<p>' . t('Below you can assign actions to run when certain taxonomy-related triggers happen. For example, you could send an e-mail to an administrator when a term is deleted.') . '</p>';
24
    case 'admin/build/trigger/user':
25
      return $explanation . '<p>' . t("Below you can assign actions to run when certain user-related triggers happen. For example, you could send an e-mail to an administrator when a user account is deleted.") . '</p>';
26
    case 'admin/help#trigger':
27 28 29
      $output = '<p>' . t('The Trigger module provides the ability to trigger <a href="@actions">actions</a> upon system events, such as when new content is added or when a user logs in.', array('@actions' => url('admin/settings/actions'))) . '</p>';
      $output .= '<p>' . t('The combination of actions and triggers can perform many useful tasks, such as e-mailing an administrator if a user account is deleted, or automatically unpublishing comments that contain certain words. By default, there are five "contexts" of events (Comments, Content, Cron, Taxonomy, and Users), but more may be added by additional modules.') . '</p>';
      $output .= '<p>' . t('For more information, see the online handbook entry for <a href="@trigger">Trigger module</a>.', array('@trigger' => 'http://drupal.org/handbook/modules/trigger/')) . '</p>';
30
      return $output;
31 32 33 34
  }
}

/**
35 36
 * Implementation of hook_menu().
 */
37 38 39
function trigger_menu() {
  $items['admin/build/trigger'] = array(
    'title' => 'Triggers',
40
    'description' => 'Tell Drupal when to execute actions.',
41 42 43
    'page callback' => 'trigger_assign',
    'access callback' => 'trigger_access_check',
    'access arguments' => array('node'),
44
  );
45 46 47
  // We don't use a menu wildcard here because these are tabs,
  // not invisible items.
  $items['admin/build/trigger/node'] = array(
48
    'title' => 'Content',
49
    'page callback' => 'trigger_assign',
50
    'page arguments' => array('node'),
51
    'access callback' => 'trigger_access_check',
52
    'access arguments' => array('node'),
53 54
    'type' => MENU_LOCAL_TASK,
  );
55 56 57
  $items['admin/build/trigger/user'] = array(
    'title' => 'Users',
    'page callback' => 'trigger_assign',
58
    'page arguments' => array('user'),
59
    'access callback' => 'trigger_access_check',
60
    'access arguments' => array('user'),
61 62
    'type' => MENU_LOCAL_TASK,
  );
63 64 65
  $items['admin/build/trigger/comment'] = array(
    'title' => 'Comments',
    'page callback' => 'trigger_assign',
66
    'page arguments' => array('comment'),
67
    'access callback' => 'trigger_access_check',
68 69 70
    'access arguments' => array('comment'),
    'type' => MENU_LOCAL_TASK,
  );
71
  $items['admin/build/trigger/taxonomy'] = array(
72
    'title' => 'Taxonomy',
73
    'page callback' => 'trigger_assign',
74
    'page arguments' => array('taxonomy'),
75
    'access callback' => 'trigger_access_check',
76 77 78
    'access arguments' => array('taxonomy'),
    'type' => MENU_LOCAL_TASK,
  );
79
  $items['admin/build/trigger/cron'] = array(
80
    'title' => 'Cron',
81
    'page callback' => 'trigger_assign',
82
    'page arguments' => array('cron'),
83
    'access arguments' => array('administer actions'),
84 85 86 87 88 89 90
    'type' => MENU_LOCAL_TASK,
  );

  // We want contributed modules to be able to describe
  // their hooks and have actions assignable to them.
  $hooks = module_invoke_all('hook_info');
  foreach ($hooks as $module => $hook) {
91
    // We've already done these.
92 93 94 95 96 97
    if (in_array($module, array('node', 'comment', 'user', 'system', 'taxonomy'))) {
      continue;
    }
    $info = db_result(db_query("SELECT info FROM {system} WHERE name = '%s'", $module));
    $info = unserialize($info);
    $nice_name = $info['name'];
98
    $items["admin/build/trigger/$module"] = array(
99
      'title' => $nice_name,
100
      'page callback' => 'trigger_assign',
101
      'page arguments' => array($module),
102
      'access arguments' => array($module),
103 104 105
      'type' => MENU_LOCAL_TASK,
    );
  }
106
  $items['admin/build/trigger/unassign'] = array(
107
    'title' => 'Unassign',
108
    'description' => 'Unassign an action from a trigger.',
109
    'page callback' => 'drupal_get_form',
110
    'page arguments' => array('trigger_unassign'),
111
    'access arguments' => array('administer actions'),
112 113 114
    'type' => MENU_CALLBACK,
  );

115
  return $items;
116 117 118 119 120
}

/**
 * Access callback for menu system.
 */
121
function trigger_access_check($module) {
122 123 124 125 126 127 128 129 130 131 132 133 134 135
  return (module_exists($module) && user_access('administer actions'));
}

/**
 * Get the aids of actions to be executed for a hook-op combination.
 *
 * @param $hook
 *   The name of the hook being fired.
 * @param $op
 *   The name of the operation being executed. Defaults to an empty string
 *   because some hooks (e.g., hook_cron()) do not have operations.
 * @return
 *   An array of action IDs.
 */
136
function _trigger_get_hook_aids($hook, $op = '') {
137
  $aids = array();
138
  $result = db_query("SELECT aa.aid, a.type FROM {trigger_assignments} aa LEFT JOIN {actions} a ON aa.aid = a.aid WHERE aa.hook = '%s' AND aa.op = '%s' ORDER BY weight", $hook, $op);
139 140 141 142 143 144 145 146 147
  while ($action = db_fetch_object($result)) {
    $aids[$action->aid]['type'] = $action->type;
  }
  return $aids;
}

/**
 * Implementation of hook_theme().
 */
148
function trigger_theme() {
149
  return array(
150
    'trigger_display' => array(
151 152
      'arguments' => array('element'),
      'file' => 'trigger.admin.inc',
153 154 155 156 157 158 159 160
    ),
  );
}

/**
 * Implementation of hook_forms(). We reuse code by using the
 * same assignment form definition for each node-op combination.
 */
161
function trigger_forms() {
162 163 164 165
  $hooks = module_invoke_all('hook_info');
  foreach ($hooks as $module => $info) {
    foreach ($hooks[$module] as $hook => $ops) {
      foreach ($ops as $op => $description) {
166
        $forms['trigger_' . $hook . '_' . $op . '_assign_form'] = array('callback' => 'trigger_assign_form');
167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
      }
    }
  }

  return $forms;
}

/**
 * When an action is called in a context that does not match its type,
 * the object that the action expects must be retrieved. For example, when
 * an action that works on users is called during the node hook, the
 * user object is not available since the node hook doesn't pass it.
 * So here we load the object the action expects.
 *
 * @param $type
 *   The type of action that is about to be called.
 * @param $node
 *   The node that was passed via the nodeapi hook.
 * @return
 *   The object expected by the action that is about to be called.
 */
188
function _trigger_normalize_node_context($type, $node) {
189 190 191 192 193 194 195 196 197 198 199 200 201 202
  switch ($type) {
    // If an action that works on comments is being called in a node context,
    // the action is expecting a comment object. But we do not know which comment
    // to give it. The first? The most recent? All of them? So comment actions
    // in a node context are not supported.

    // An action that works on users is being called in a node context.
    // Load the user object of the node's author.
    case 'user':
      return user_load(array('uid' => $node->uid));
  }
}

/**
203 204
 * Simple wrapper function to make user hooks work with new entry points.
 *
205
 * @TODO: Take advantage of the new API and reorganise/remove this function.
206
 */
207
function _trigger_nodeapi($node, $op, $a3 = NULL, $a4 = NULL) {
208 209 210 211 212 213 214 215 216 217
  // Keep objects for reuse so that changes actions make to objects can persist.
  static $objects;
  // Prevent recursion by tracking which operations have already been called.
  static $recursion;
  // Support a subset of operations.
  if (!in_array($op, array('view', 'update', 'presave', 'insert', 'delete')) || isset($recursion[$op])) {
    return;
  }
  $recursion[$op] = TRUE;

218
  $aids = _trigger_get_hook_aids('nodeapi', $op);
219 220 221 222 223 224 225 226 227 228 229 230 231 232
  if (!$aids) {
    return;
  }
  $context = array(
    'hook' => 'nodeapi',
    'op' => $op,
  );

  // We need to get the expected object if the action's type is not 'node'.
  // We keep the object in $objects so we can reuse it if we have multiple actions
  // that make changes to an object.
  foreach ($aids as $aid => $action_info) {
    if ($action_info['type'] != 'node') {
      if (!isset($objects[$action_info['type']])) {
233
        $objects[$action_info['type']] = _trigger_normalize_node_context($action_info['type'], $node);
234 235 236 237 238 239 240 241 242 243
      }
      // Since we know about the node, we pass that info along to the action.
      $context['node'] = $node;
      $result = actions_do($aid, $objects[$action_info['type']], $context, $a4, $a4);
    }
    else {
      actions_do($aid, $node, $context, $a3, $a4);
    }
  }
}
244

245 246 247
/**
 * Implementation of hook_nodeapi_view().
 */
248 249
function trigger_nodeapi_view($node, $teaser, $page) {
  _trigger_nodeapi($node, 'view', $teaser, $page);
250 251 252 253 254
}

/**
 * Implementation of hook_nodeapi_update().
 */
255 256
function trigger_nodeapi_update($node) {
  _trigger_nodeapi($node, 'update');
257 258 259 260 261
}

/**
 * Implementation of hook_nodeapi_presave().
 */
262 263
function trigger_nodeapi_presave($node) {
  _trigger_nodeapi($node, 'presave');
264 265 266 267 268
}

/**
 * Implementation of hook_nodeapi_insert().
 */
269 270
function trigger_nodeapi_insert($node) {
  _trigger_nodeapi($node, 'insert');
271 272 273 274 275
}

/**
 * Implementation of hook_nodeapi_delete().
 */
276 277
function trigger_nodeapi_delete($node) {
  _trigger_nodeapi($node, 'delete');
278
}
279 280 281 282 283 284 285 286 287 288 289 290 291 292 293

/**
 * When an action is called in a context that does not match its type,
 * the object that the action expects must be retrieved. For example, when
 * an action that works on nodes is called during the comment hook, the
 * node object is not available since the comment hook doesn't pass it.
 * So here we load the object the action expects.
 *
 * @param $type
 *   The type of action that is about to be called.
 * @param $comment
 *   The comment that was passed via the comment hook.
 * @return
 *   The object expected by the action that is about to be called.
 */
294
function _trigger_normalize_comment_context($type, $comment) {
295 296 297 298 299 300 301 302 303 304 305 306 307 308
  switch ($type) {
    // An action that works with nodes is being called in a comment context.
    case 'node':
      return node_load(is_array($comment) ? $comment['nid'] : $comment->nid);

    // An action that works on users is being called in a comment context.
    case 'user':
      return user_load(array('uid' => is_array($comment) ? $comment['uid'] : $comment->uid));
  }
}

/**
 * Implementation of hook_comment().
 */
309
function trigger_comment($a1, $op) {
310 311 312 313 314 315
  // Keep objects for reuse so that changes actions make to objects can persist.
  static $objects;
  // We support a subset of operations.
  if (!in_array($op, array('insert', 'update', 'delete', 'view'))) {
    return;
  }
316
  $aids = _trigger_get_hook_aids('comment', $op);
317 318 319 320 321 322 323 324 325 326
  $context = array(
    'hook' => 'comment',
    'op' => $op,
  );
  // We need to get the expected object if the action's type is not 'comment'.
  // We keep the object in $objects so we can reuse it if we have multiple actions
  // that make changes to an object.
  foreach ($aids as $aid => $action_info) {
    if ($action_info['type'] != 'comment') {
      if (!isset($objects[$action_info['type']])) {
327
        $objects[$action_info['type']] = _trigger_normalize_comment_context($action_info['type'], $a1);
328 329 330 331 332 333 334
      }
      // Since we know about the comment, we pass it along to the action
      // in case it wants to peek at it.
      $context['comment'] = (object) $a1;
      actions_do($aid, $objects[$action_info['type']], $context);
    }
    else {
335 336
      $a1 = (object) $a1;
      actions_do($aid, $a1, $context);
337 338 339 340 341 342 343
    }
  }
}

/**
 * Implementation of hook_cron().
 */
344 345
function trigger_cron() {
  $aids = _trigger_get_hook_aids('cron');
346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368
  $context = array(
    'hook' => 'cron',
    'op' => '',
  );
  // Cron does not act on any specific object.
  $object = NULL;
  actions_do(array_keys($aids), $object, $context);
}

/**
 * When an action is called in a context that does not match its type,
 * the object that the action expects must be retrieved. For example, when
 * an action that works on nodes is called during the user hook, the
 * node object is not available since the user hook doesn't pass it.
 * So here we load the object the action expects.
 *
 * @param $type
 *   The type of action that is about to be called.
 * @param $account
 *   The account object that was passed via the user hook.
 * @return
 *   The object expected by the action that is about to be called.
 */
369
function _trigger_normalize_user_context($type, $account) {
370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386
  switch ($type) {
    // If an action that works on comments is being called in a user context,
    // the action is expecting a comment object. But we have no way of
    // determining the appropriate comment object to pass. So comment
    // actions in a user context are not supported.

    // An action that works with nodes is being called in a user context.
    // If a single node is being viewed, return the node.
    case 'node':
      // If we are viewing an individual node, return the node.
      if ((arg(0) == 'node') && is_numeric(arg(1)) && (arg(2) == NULL)) {
        return node_load(array('nid' => arg(1)));
      }
  }
}

/**
387
 * trigger_user_login
388
 */
389
function trigger_user_login(&$edit, &$account, $category) {
390
  _trigger_user('login', $edit, $account, $category);
391 392 393 394 395
}

/**
 * Implementation of hook_user_logout().
 */
396
function trigger_user_logout(&$edit, &$account) {
397
  _trigger_user('logout', $edit, $account);
398 399 400 401 402 403
}

/**
 * Implementation of hook_user_insert().
 */
function trigger_user_insert(&$edit, &$account, $category) {
404
  _trigger_user('insert', $edit, $account, $category);
405 406 407 408 409 410
}

/**
 * Implementation of hook_user_update().
 */
function trigger_user_update(&$edit, &$account, $category) {
411
  _trigger_user('update', $edit, $account, $category);
412 413 414 415 416 417
}

/**
 * Implementation of hook_user_delete().
 */
function trigger_user_delete(&$edit, &$account, $category) {
418
  _trigger_user('delete', $edit, $account, $category);
419 420 421 422 423 424
}

/**
 * Implementation of hook_user_view().
 */
function trigger_user_view(&$edit, &$account, $category) {
425
  _trigger_user('view', $edit, $account, $category);
426 427 428 429 430
}

/**
 * Simple wrapper function to make user hooks work with new entry points.
 *
431
 * @TODO: Take advantage of the new API and reorganise/remove this function.
432 433
 */
function _trigger_user($op, &$edit, &$account, $category = NULL) {
434 435 436 437 438 439
  // Keep objects for reuse so that changes actions make to objects can persist.
  static $objects;
  // We support a subset of operations.
  if (!in_array($op, array('login', 'logout', 'insert', 'update', 'delete', 'view'))) {
    return;
  }
440
  $aids = _trigger_get_hook_aids('user', $op);
441 442 443 444 445 446 447 448
  $context = array(
    'hook' => 'user',
    'op' => $op,
    'form_values' => &$edit,
  );
  foreach ($aids as $aid => $action_info) {
    if ($action_info['type'] != 'user') {
      if (!isset($objects[$action_info['type']])) {
449
        $objects[$action_info['type']] = _trigger_normalize_user_context($action_info['type'], $account);
450 451 452 453 454 455 456 457 458 459 460 461 462
      }
      $context['account'] = $account;
      actions_do($aid, $objects[$action_info['type']], $context);
    }
    else {
      actions_do($aid, $account, $context, $category);
    }
  }
}

/**
 * Implementation of hook_taxonomy().
 */
463
function trigger_taxonomy($op, $type, $array) {
464 465 466
  if ($type != 'term') {
    return;
  }
467
  $aids = _trigger_get_hook_aids('taxonomy', $op);
468 469 470 471
  $context = array(
    'hook' => 'taxonomy',
    'op' => $op
  );
472
  $_array = (object) $array;
473
  foreach ($aids as $aid => $action_info) {
474
    actions_do($aid, $_array, $context);
475 476 477 478 479 480 481 482 483 484 485 486
  }
}

/**
 * Often we generate a select field of all actions. This function
 * generates the options for that select.
 *
 * @param $type
 *   One of 'node', 'user', 'comment'.
 * @return
 *   Array keyed by action ID.
 */
487
function trigger_options($type = 'all') {
488 489 490 491 492 493 494 495 496 497 498 499
  $options = array(t('Choose an action'));
  foreach (actions_actions_map(actions_get_all_actions()) as $aid => $action) {
    $options[$action['type']][$aid] = $action['description'];
  }

  if ($type == 'all') {
    return $options;
  }
  else {
    return $options[$type];
  }
}
500 501 502 503 504 505 506 507 508

/**
 * Implementation of hook_actions_delete().
 *
 * Remove all trigger entries for the given action, when deleted.
 */
function trigger_actions_delete($aid) {
  db_query("DELETE FROM {trigger_assignments} WHERE aid = '%s'", $aid);
}