Introduction to Triggers

Triggers come in two flavours: calls and filters. If you invoke a trigger, you must provide a unique name for it so that modules can respond to it. If you want to respond to a trigger, you create a function in your module matching the name of the trigger. A list of the triggers in the codebase can be found in the file triggers_list.txt.

Calls

A call executes named functions at a certain point in the program flow, optionally with a set of arguments. The unique name is the only required argument; any additional arguments supplied to the call are passed on to the responders. Multiple names can be supplied as an array to a single invocation. When a call is invoked, active modules will be scanned for responder functions (or aliases) matching the unique name, and any responders discovered will be executed. A module is able to set the priority of each of its responders.

Here is an example of a call:

Trigger::current()->call("runtime");

The return value from the call is:

  1. A concatenated string if all calls return a string, or;
  2. false if none of the triggers exist, or;
  3. the most substantial returned value decided by oneof().

Filters

The goal of a filter is to modify a particular target and return the modification. The target for filtering is the first argument, and the unique name is the second argument; any additional arguments supplied to the filter are passed on to the responders. Multiple names can be supplied as an array to a single invocation. When a filter is invoked, active modules will be scanned for responder functions (or aliases) matching the unique name, and any responders discovered will be executed. A module is able to set the priority of each of its responders.

Here is an example of a filter:

Trigger::current()->filter($function, "send_mail");

The return value from the filter is the modified target.