Project

General

Profile

Paste
Download (20.1 KB) Statistics
| Branch: | Revision:

root / drupal7 / modules / trigger / trigger.module @ 27e02aed

1
<?php
2

    
3
/**
4
 * @file
5
 * Enables functions to be stored and executed at a later time.
6
 */
7

    
8
/**
9
 * Implements hook_help().
10
 */
11
function trigger_help($path, $arg) {
12
  // Generate help text for admin/structure/trigger/(module) tabs.
13
  $matches = array();
14
  if (preg_match('|^admin/structure/trigger/(.*)$|', $path, $matches)) {
15
    $explanation = '<p>' . t('Triggers are events on your site, such as new content being added or a user logging in. The Trigger module associates these triggers with actions (functional tasks), such as unpublishing content containing certain keywords 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 advanced actions (actions requiring configuration, such as an e-mail address or a list of banned words).', array('@url' => url('admin/config/system/actions'))) . '</p>';
16

    
17
    $module = $matches[1];
18
    $trigger_info = _trigger_tab_information();
19
    if (!empty($trigger_info[$module])) {
20
      $explanation .= '<p>' . t('There is a tab on this page for each module that defines triggers. On this tab you can assign actions to run when triggers from the <a href="@module-help">@module-name module</a> happen.', array('@module-help' => url('admin/help/' . $module), '@module-name' => $trigger_info[$module])) . '</p>';
21
    }
22

    
23
    return $explanation;
24
  }
25

    
26
  if ($path == 'admin/help#trigger') {
27
    $output = '';
28
    $output .= '<h3>' . t('About') . '</h3>';
29
    $output .= '<p>' . t('The Trigger module provides the ability to cause <em>actions</em> to run when certain <em>triggers</em> take place on your site. Triggers are events, such as new content being added to your site or a user logging in, and actions are tasks, such as unpublishing content or e-mailing an administrator. For more information, see the online handbook entry for <a href="@trigger">Trigger module</a>.', array('@trigger' => 'http://drupal.org/documentation/modules/trigger/')) . '</p>';
30
    $output .= '<h3>' . t('Uses') . '</h3>';
31
    $output .= '<dl>';
32
    $output .= '<dt>' . t('Configuring triggers and actions') . '</dt>';
33
    $output .= '<dd>' . 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. To set up a trigger/action combination, first visit the <a href="@actions-page">Actions configuration page</a>, where you can either verify that the action you want is already listed, or create a new <em>advanced</em> action. You will need to set up an advanced action if there are configuration options in your trigger/action combination, such as specifying an e-mail address or a list of banned words. After configuring or verifying your action, visit the <a href="@triggers-page">Triggers configuration page</a> and choose the appropriate tab (Comment, Taxonomy, etc.), where you can assign the action to run when the trigger event occurs.', array('@triggers-page' => url('admin/structure/trigger'), '@actions-page' => url('admin/config/system/actions'))) . '</dd>';
34
    $output .= '</dl>';
35
    return $output;
36
  }
37
}
38

    
39
/**
40
 * Implements hook_menu().
41
 */
42
function trigger_menu() {
43
  $items['admin/structure/trigger'] = array(
44
    'title' => 'Triggers',
45
    'description' => 'Configure when to execute actions.',
46
    'page callback' => 'trigger_assign',
47
    'access arguments' => array('administer actions'),
48
    'file' => 'trigger.admin.inc',
49
  );
50

    
51
  $trigger_info = _trigger_tab_information();
52
  foreach ($trigger_info as $module => $module_name) {
53
    $items["admin/structure/trigger/$module"] = array(
54
      'title' => $module_name,
55
      'page callback' => 'trigger_assign',
56
      'page arguments' => array($module),
57
      'access arguments' => array('administer actions'),
58
      'type' => MENU_LOCAL_TASK,
59
      'file' => 'trigger.admin.inc',
60
    );
61
  }
62

    
63
  $items['admin/structure/trigger/unassign'] = array(
64
    'title' => 'Unassign',
65
    'description' => 'Unassign an action from a trigger.',
66
    'page callback' => 'drupal_get_form',
67
    'page arguments' => array('trigger_unassign'),
68
    // Only accessible if there are any actions that can be unassigned.
69
    'access callback' => 'trigger_menu_unassign_access',
70
    // Only output in the breadcrumb, not in menu trees.
71
    'type' => MENU_VISIBLE_IN_BREADCRUMB,
72
    'file' => 'trigger.admin.inc',
73
  );
74

    
75
  return $items;
76
}
77

    
78
/**
79
 * Access callback: Determines if triggers can be unassigned.
80
 *
81
 * @return bool
82
 *   TRUE if there are triggers that the user can unassign, FALSE otherwise.
83
 *
84
 * @see trigger_menu()
85
 */
86
function trigger_menu_unassign_access() {
87
  if (!user_access('administer actions')) {
88
    return FALSE;
89
  }
90
  $count = db_select('trigger_assignments')
91
    ->countQuery()
92
    ->execute()
93
    ->fetchField();
94
  return $count > 0;
95
}
96

    
97
/**
98
 * Implements hook_trigger_info().
99
 *
100
 * Defines all the triggers that this module implements triggers for.
101
 */
102
function trigger_trigger_info() {
103
   return array(
104
     'node' => array(
105
       'node_presave' => array(
106
         'label' => t('When either saving new content or updating existing content'),
107
       ),
108
       'node_insert' => array(
109
         'label' => t('After saving new content'),
110
       ),
111
       'node_update' => array(
112
         'label' => t('After saving updated content'),
113
       ),
114
       'node_delete' => array(
115
         'label' => t('After deleting content'),
116
       ),
117
       'node_view' => array(
118
         'label' => t('When content is viewed by an authenticated user'),
119
       ),
120
     ),
121
     'comment' => array(
122
       'comment_presave' => array(
123
         'label' => t('When either saving a new comment or updating an existing comment'),
124
       ),
125
       'comment_insert' => array(
126
         'label' => t('After saving a new comment'),
127
       ),
128
       'comment_update' => array(
129
         'label' => t('After saving an updated comment'),
130
       ),
131
       'comment_delete' => array(
132
         'label' => t('After deleting a comment'),
133
       ),
134
       'comment_view' => array(
135
         'label' => t('When a comment is being viewed by an authenticated user'),
136
       ),
137
     ),
138
     'taxonomy' => array(
139
       'taxonomy_term_insert' => array(
140
         'label' => t('After saving a new term to the database'),
141
       ),
142
       'taxonomy_term_update' => array(
143
         'label' => t('After saving an updated term to the database'),
144
       ),
145
       'taxonomy_term_delete' => array(
146
         'label' => t('After deleting a term'),
147
       ),
148
     ),
149
     'system' => array(
150
       'cron' => array(
151
         'label' => t('When cron runs'),
152
       ),
153
     ),
154
     'user' => array(
155
       'user_insert' => array(
156
         'label' => t('After creating a new user account'),
157
       ),
158
       'user_update' => array(
159
         'label' => t('After updating a user account'),
160
       ),
161
       'user_delete' => array(
162
         'label' => t('After a user has been deleted'),
163
       ),
164
       'user_login' => array(
165
         'label' => t('After a user has logged in'),
166
       ),
167
       'user_logout' => array(
168
         'label' => t('After a user has logged out'),
169
       ),
170
       'user_view' => array(
171
         'label' => t("When a user's profile is being viewed"),
172
       ),
173
     ),
174
   );
175
 }
176

    
177
/**
178
 * Gets the action IDs of actions to be executed for a hook.
179
 *
180
 * @param $hook
181
 *   The name of the hook being fired.
182
 *
183
 * @return
184
 *   An array whose keys are action IDs that the user has associated with
185
 *   this trigger, and whose values are arrays containing the action type and
186
 *   label.
187
 */
188
function trigger_get_assigned_actions($hook) {
189
  $actions = &drupal_static(__FUNCTION__, array());
190
  if (!isset($actions[$hook])) {
191
    $actions[$hook] = db_query("SELECT ta.aid, a.type, a.label FROM {trigger_assignments} ta LEFT JOIN {actions} a ON ta.aid = a.aid WHERE ta.hook = :hook ORDER BY ta.weight", array(
192
      ':hook' => $hook,
193
    ))->fetchAllAssoc('aid', PDO::FETCH_ASSOC);
194
  }
195
  return $actions[$hook];
196
}
197

    
198
/**
199
 * Implements hook_theme().
200
 */
201
function trigger_theme() {
202
  return array(
203
    'trigger_display' => array(
204
      'render element' => 'element',
205
      'file' => 'trigger.admin.inc',
206
    ),
207
  );
208
}
209

    
210
/**
211
 * Implements hook_forms().
212
 *
213
 * We re-use code by using the same assignment form definition for each hook.
214
 */
215
function trigger_forms() {
216
  $trigger_info = _trigger_get_all_info();
217
  $forms = array();
218
  foreach ($trigger_info as $module => $hooks) {
219
    foreach ($hooks as $hook => $description) {
220
      $forms['trigger_' . $hook . '_assign_form'] = array('callback' => 'trigger_assign_form');
221
    }
222
  }
223

    
224
  return $forms;
225
}
226

    
227
/**
228
 * Loads associated objects for node triggers.
229
 *
230
 * When an action is called in a context that does not match its type, the
231
 * object that the action expects must be retrieved. For example, when an action
232
 * that works on users is called during a node hook implementation, the user
233
 * object is not available since the node hook call doesn't pass it. So here we
234
 * load the object the action expects.
235
 *
236
 * @param $type
237
 *   The type of action that is about to be called.
238
 * @param $node
239
 *   The node that was passed via the node hook.
240
 *
241
 * @return
242
 *   The object expected by the action that is about to be called.
243
 */
244
function _trigger_normalize_node_context($type, $node) {
245
  // Note that comment-type actions are not supported in node contexts,
246
  // because we wouldn't know which comment to choose.
247
  switch ($type) {
248
    // An action that works on users is being called in a node context.
249
    // Load the user object of the node's author.
250
    case 'user':
251
      return user_load($node->uid);
252
  }
253
}
254

    
255
/**
256
 * Calls action functions for node triggers.
257
 *
258
 * @param $node
259
 *   Node object.
260
 * @param $hook
261
 *   Hook to trigger.
262
 * @param $a3
263
 *   Additional argument to action function.
264
 * @param $a4
265
 *   Additional argument to action function.
266
 */
267
function _trigger_node($node, $hook, $a3 = NULL, $a4 = NULL) {
268
  // Keep objects for reuse so that changes actions make to objects can persist.
269
  static $objects;
270
  // Prevent recursion by tracking which operations have already been called.
271
  static $recursion;
272

    
273
  $aids = trigger_get_assigned_actions($hook);
274
  if (!$aids) {
275
    return;
276
  }
277

    
278
  if (isset($recursion[$hook])) {
279
    return;
280
  }
281
  $recursion[$hook] = TRUE;
282

    
283
  $context = array(
284
    'group' => 'node',
285
    'hook' => $hook,
286
  );
287

    
288
  // We need to get the expected object if the action's type is not 'node'.
289
  // We keep the object in $objects so we can reuse it if we have multiple actions
290
  // that make changes to an object.
291
  foreach ($aids as $aid => $info) {
292
    $type = $info['type'];
293
    if ($type != 'node') {
294
      if (!isset($objects[$type])) {
295
        $objects[$type] = _trigger_normalize_node_context($type, $node);
296
      }
297
      // Since we know about the node, we pass that info along to the action.
298
      $context['node'] = $node;
299
      $result = actions_do($aid, $objects[$type], $context, $a3, $a4);
300
    }
301
    else {
302
      actions_do($aid, $node, $context, $a3, $a4);
303
    }
304
  }
305

    
306
  unset($recursion[$hook]);
307
}
308

    
309
/**
310
 * Implements hook_node_view().
311
 */
312
function trigger_node_view($node, $view_mode) {
313
  _trigger_node($node, 'node_view', $view_mode);
314
}
315

    
316
/**
317
 * Implements hook_node_update().
318
 */
319
function trigger_node_update($node) {
320
  _trigger_node($node, 'node_update');
321
}
322

    
323
/**
324
 * Implements hook_node_presave().
325
 */
326
function trigger_node_presave($node) {
327
  _trigger_node($node, 'node_presave');
328
}
329

    
330
/**
331
 * Implements hook_node_insert().
332
 */
333
function trigger_node_insert($node) {
334
  _trigger_node($node, 'node_insert');
335
}
336

    
337
/**
338
 * Implements hook_node_delete().
339
 */
340
function trigger_node_delete($node) {
341
  _trigger_node($node, 'node_delete');
342
}
343

    
344
/**
345
 * Loads associated objects for comment triggers.
346
 *
347
 * When an action is called in a context that does not match its type, the
348
 * object that the action expects must be retrieved. For example, when an action
349
 * that works on nodes is called during the comment hook, the node object is not
350
 * available since the comment hook doesn't pass it. So here we load the object
351
 * the action expects.
352
 *
353
 * @param $type
354
 *   The type of action that is about to be called.
355
 * @param $comment
356
 *   The comment that was passed via the comment hook.
357
 *
358
 * @return
359
 *   The object expected by the action that is about to be called.
360
 */
361
function _trigger_normalize_comment_context($type, $comment) {
362
  switch ($type) {
363
    // An action that works with nodes is being called in a comment context.
364
    case 'node':
365
      return node_load(is_array($comment) ? $comment['nid'] : $comment->nid);
366

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

    
373
/**
374
 * Implements hook_comment_presave().
375
 */
376
function trigger_comment_presave($comment) {
377
  _trigger_comment($comment, 'comment_presave');
378
}
379

    
380
/**
381
 * Implements hook_comment_insert().
382
 */
383
function trigger_comment_insert($comment) {
384
  _trigger_comment($comment, 'comment_insert');
385
}
386

    
387
/**
388
 * Implements hook_comment_update().
389
 */
390
function trigger_comment_update($comment) {
391
  _trigger_comment($comment, 'comment_update');
392
}
393

    
394
/**
395
 * Implements hook_comment_delete().
396
 */
397
function trigger_comment_delete($comment) {
398
  _trigger_comment($comment, 'comment_delete');
399
}
400

    
401
/**
402
 * Implements hook_comment_view().
403
 */
404
function trigger_comment_view($comment) {
405
  _trigger_comment($comment, 'comment_view');
406
}
407

    
408
/**
409
 * Calls action functions for comment triggers.
410
 *
411
 * @param $a1
412
 *   Comment object or array of form values.
413
 * @param $hook
414
 *   Hook to trigger.
415
 */
416
function _trigger_comment($a1, $hook) {
417
  // Keep objects for reuse so that changes actions make to objects can persist.
418
  static $objects;
419
  $aids = trigger_get_assigned_actions($hook);
420
  $context = array(
421
    'group' => 'comment',
422
    'hook' => $hook,
423
  );
424
  // We need to get the expected object if the action's type is not 'comment'.
425
  // We keep the object in $objects so we can reuse it if we have multiple
426
  // actions that make changes to an object.
427
  foreach ($aids as $aid => $info) {
428
    $type = $info['type'];
429
    if ($type != 'comment') {
430
      if (!isset($objects[$type])) {
431
        $objects[$type] = _trigger_normalize_comment_context($type, $a1);
432
      }
433
      // Since we know about the comment, we pass it along to the action
434
      // in case it wants to peek at it.
435
      $context['comment'] = (object) $a1;
436
      actions_do($aid, $objects[$type], $context);
437
    }
438
    else {
439
      actions_do($aid, $a1, $context);
440
    }
441
  }
442
}
443

    
444
/**
445
 * Implements hook_cron().
446
 */
447
function trigger_cron() {
448
  $aids = trigger_get_assigned_actions('cron');
449
  $context = array(
450
    'group' => 'cron',
451
    'hook' => 'cron',
452
  );
453
  // Cron does not act on any specific object.
454
  $object = NULL;
455
  actions_do(array_keys($aids), $object, $context);
456
}
457

    
458
/**
459
 * Loads associated objects for user triggers.
460
 *
461
 * When an action is called in a context that does not match its type, the
462
 * object that the action expects must be retrieved. For example, when an action
463
 * that works on nodes is called during the user hook, the node object is not
464
 * available since the user hook doesn't pass it. So here we load the object the
465
 * action expects.
466
 *
467
 * @param $type
468
 *   The type of action that is about to be called.
469
 * @param $account
470
 *   The account object that was passed via the user hook.
471
 *
472
 * @return
473
 *   The object expected by the action that is about to be called.
474
 */
475
function _trigger_normalize_user_context($type, $account) {
476
  // Note that comment-type actions are not supported in user contexts,
477
  // because we wouldn't know which comment to choose.
478
  switch ($type) {
479
    // An action that works with nodes is being called in a user context.
480
    // If a single node is being viewed, return the node.
481
    case 'node':
482
      // If we are viewing an individual node, return the node.
483
      if (arg(0) == 'node' && is_numeric(arg(1)) && arg(2) == NULL) {
484
        return node_load(array('nid' => arg(1)));
485
      }
486
      break;
487
  }
488
}
489

    
490
/**
491
 * Implements hook_user_login().
492
 */
493
function trigger_user_login(&$edit, $account, $category) {
494
  _trigger_user('user_login', $edit, $account, $category);
495
}
496

    
497
/**
498
 * Implements hook_user_logout().
499
 */
500
function trigger_user_logout($account) {
501
  $edit = array();
502
  _trigger_user('user_logout', $edit, $account);
503
}
504

    
505
/**
506
 * Implements hook_user_insert().
507
 */
508
function trigger_user_insert(&$edit, $account, $category) {
509
  _trigger_user('user_insert', $edit, $account, $category);
510
}
511

    
512
/**
513
 * Implements hook_user_update().
514
 */
515
function trigger_user_update(&$edit, $account, $category) {
516
  _trigger_user('user_update', $edit, $account, $category);
517
}
518

    
519
/**
520
 * Implements hook_user_cancel().
521
 */
522
function trigger_user_cancel($edit, $account, $method) {
523
  switch ($method) {
524
    case 'user_cancel_reassign':
525
      _trigger_user('user_delete', $edit, $account, $method);
526
      break;
527
  }
528
}
529

    
530
/**
531
 * Implements hook_user_delete().
532
 */
533
function trigger_user_delete($account) {
534
  $edit = array();
535
  _trigger_user('user_delete', $edit, $account, NULL);
536
}
537

    
538
/**
539
 * Implements hook_user_view().
540
 */
541
function trigger_user_view($account) {
542
  $edit = NULL;
543
  _trigger_user('user_view', $edit, $account, NULL);
544
}
545

    
546
/**
547
 * Calls action functions for user triggers.
548
 *
549
 * @param $hook
550
 *   The hook that called this function.
551
 * @param $edit
552
 *   Edit variable passed in to the hook or empty array if not needed.
553
 * @param $account
554
 *   Account variable passed in to the hook.
555
 * @param $method
556
 *   Method variable passed in to the hook or NULL if not needed.
557
 */
558
function _trigger_user($hook, &$edit, $account, $category = NULL) {
559
  // Keep objects for reuse so that changes actions make to objects can persist.
560
  static $objects;
561
  $aids = trigger_get_assigned_actions($hook);
562
  $context = array(
563
    'group' => 'user',
564
    'hook' => $hook,
565
    'form_values' => &$edit,
566
  );
567
  foreach ($aids as $aid => $info) {
568
    $type = $info['type'];
569
    if ($type != 'user') {
570
      if (!isset($objects[$type])) {
571
        $objects[$type] = _trigger_normalize_user_context($type, $account);
572
      }
573
      $context['user'] = $account;
574
      actions_do($aid, $objects[$type], $context);
575
    }
576
    else {
577
      actions_do($aid, $account, $context, $category);
578
    }
579
  }
580
}
581

    
582
/**
583
 * Calls action functions for taxonomy triggers.
584
 *
585
 * @param $hook
586
 *   Hook to trigger actions for taxonomy_term_insert(),
587
 *   taxonomy_term_update(), and taxonomy_term_delete().
588
 * @param $array
589
 *   Item on which operation is being performed, either a term or
590
 *   form values.
591
 */
592
function _trigger_taxonomy($hook, $array) {
593
  $aids = trigger_get_assigned_actions($hook);
594
  $context = array(
595
    'group' => 'taxonomy',
596
    'hook' => $hook
597
  );
598
  actions_do(array_keys($aids), (object) $array, $context);
599
}
600

    
601
/**
602
 * Implements hook_taxonomy_term_insert().
603
 */
604
function trigger_taxonomy_term_insert($term) {
605
  _trigger_taxonomy('taxonomy_term_insert', (array) $term);
606
}
607

    
608
/**
609
 * Implements hook_taxonomy_term_update().
610
 */
611
function trigger_taxonomy_term_update($term) {
612
  _trigger_taxonomy('taxonomy_term_update', (array) $term);
613
}
614

    
615
/**
616
 * Implements hook_taxonomy_term_delete().
617
 */
618
function trigger_taxonomy_term_delete($term) {
619
  _trigger_taxonomy('taxonomy_term_delete', (array) $term);
620
}
621

    
622
/**
623
 * Implements hook_actions_delete().
624
 *
625
 * Removes all trigger entries for the given action, when an action is deleted.
626
 */
627
function trigger_actions_delete($aid) {
628
  db_delete('trigger_assignments')
629
    ->condition('aid', $aid)
630
    ->execute();
631
  drupal_static_reset('trigger_get_assigned_actions');
632
}
633

    
634
/**
635
 * Retrieves and caches information from hook_trigger_info() implementations.
636
 *
637
 * @return
638
 *   Array of all triggers.
639
 */
640
function _trigger_get_all_info() {
641
  $triggers = &drupal_static(__FUNCTION__);
642

    
643
  if (!isset($triggers)) {
644
    $triggers = module_invoke_all('trigger_info');
645
    drupal_alter('trigger_info', $triggers);
646
  }
647

    
648
  return $triggers;
649
}
650

    
651
/**
652
 * Gathers information about tabs on the triggers administration screen.
653
 *
654
 * @return
655
 *   Array of modules that have triggers, with the keys being the
656
 *   machine-readable name of the module, and the values being the
657
 *   human-readable name of the module.
658
 */
659
function _trigger_tab_information() {
660
  // Gather information about all triggers and modules.
661
  $trigger_info = _trigger_get_all_info();
662
  $modules = system_get_info('module');
663
  $modules = array_intersect_key($modules, $trigger_info);
664

    
665
  $return_info = array();
666
  foreach ($modules as $name => $info) {
667
    $return_info[$name] = $info['name'];
668
  }
669

    
670
  return $return_info;
671
}