The Rules plugin uses the definitions for ECA’s (events, conditions, and actions) to determine how they can be fit together into operable rules. A definition is simply an associative array which provides important details about the ECA and how it is structured. The associative array can be provided directly, or via a callback function.
A callback function is preferred whenever the definition is generated dynamically, since the callback function allows it to be lazy loaded. The callback function is only ever called once, even in cases where the definition is used multiple times.
@Events
rules_describe_event( $type, $hook, $definition );
/**
* @param array|callable (required) $definition {
*
* The event definition. If a callback is provided, it must return the definition array.
*
* @type string (required) 'title' The event title to be displayed in summaries
* @type string (optional) 'group' An arbitrary name to group your event under (usually your plugin name)
* @type string (optional) 'description' A possibly more descriptive event summary
* @type array (optional) 'arguments' {
*
* An associative array of argument descriptions (if any) which are used in the hook.
* The keys for each array item are the name of the argument (which will be used as a
* variable name). The value of each key is another associative array describing the
* argument. The arguments need to be in the same order that they are passed in the
* event hook.
*
* arg_name => array {
* Argument description.
*
* @type string (required) 'argtype' The type of the argument. Possible choices:
* 'int', 'float', 'bool', 'string', 'mixed',
* 'array', 'object'.
* @type string (required) 'label' The label of the argument used for generating
* form elements.
* @type string (optional) 'description' A more detailed description of the argument
* value.
* @type string (optional) 'class' A mapped class that this argument represents.
* For example, a user id integer would have the
* class of 'WP_User'.
* @type string (optional) 'nullable' This indicates of the value of this argument
* is sometimes purposely NULL.
* Default: false
* @type array (optional) 'keys' {
* An associative array used to describe the key/value pairs for array argtypes.
*
* @type bool (optional) 'associative' Indicates the array keys are associative.
* @type bool (optional) 'fixed' Indicates the only keys available for the
* array are those which are mapped.
* @type callable (optional) 'getter' {
* A callback function that can be used to retrieve the value for a given key.
*
* param object $object The object that the array belongs to
* param string $key The key to retrieve from the array
* return mixed
* }
* @type array (optional) 'default' A default argument description which applies
* to all array values not specifically mapped.
* @type array (optional) 'mappings' {
* An associative array of argument descriptions associated with specific array keys.
* }
* }
* }
* }
* }
*/
For example code, see the Events documentation.
@Conditions / Actions
Conditions and actions have the same definition format.
rules_register_condition( $condition_key, $definition ); rules_define_action( $action_key, $definition );
/**
* @param array|callable (required) $definition {
*
* The condition/action definition. If a callback is provided, it must return the definition array.
*
* @type string (required) 'title' The condition/action title to be displayed in summaries
* @type string (optional) 'description' A possibly more descriptive condition/action summary
* @type callable (required) 'callback' {
* The callback which performs the condition check, or for actions... the work.
*
* params ... The arguments from this definition
* params array $values The saved operation configuration values
* params array $arg_map The event arguments mapped by key
* params object $operation The instance of the condition/action being invoked
* return bool
* }
* @type array (optional) 'configuration' {
* @type callable (optional) 'form' {
* This callback allows you to add any configuration fields needed to control the
* overall behavior of the condition/action.
*
* param object $form The form builder (MWP\Framework\Helpers\Form)
* param array $values The values previously saved in the config
* param object $operation The instance of the condition/action being configured
* return void
* }
* @type callable (optional) 'saveValues' {
* This callback can be used to process form submission values before they are saved.
*
* param array $values The values previously saved in the config
* param object $operation The instance of the condition/action being configured
* return void
* }
* }
* @type array (optional) 'arguments' {
*
* An associative array that describes the parameters which your callback function uses.
* The keys for each array item are the name of the argument (which will also be used as
* a variable name). The value of each key is another associative array describing the
* argument. The arguments need to be in the same order that they will be passed to your
* callback function.
*
* arg_name => array {
* Parameter description.
*
* @type string (required) 'label' The label of the argument used for generating
* form elements.
* @type array (optional) 'argtypes' {
*
* An associative array of the argument types that are acceptable to your callback
* for this parameter. Array keys correspond to acceptable argument types, i.e.
* 'int', 'float', 'bool', 'string', 'mixed', 'array', 'object'
*
* argtype => array {
*
* Argument details.
*
* @type string 'description' A description of what this argtype is
* @type array 'classes' {
* An array of acceptable classes (fully qualified classnames) for this argtype.
* @type string
* }
* }
* }
* @type string (optional) 'default' The default configuration method for the argument.
* Choices: 'event', 'manual', 'phpcode'
* Default: event
* @type bool (optional) 'required' Indicates if a NULL value for this argument is
* acceptable or not.
* Default: false
* @type array (optional) 'configuration' {
* @type callable (optional) 'form' {
* This callback (if provided) will enable the user to select the 'manual' config option
* for this operational parameter. Add any necessary fields to the form to allow the user
* to manually set the value for this parameter.
*
* param object $form The form builder (MWP\Framework\Helpers\Form)
* param array $values The values previously saved in the config
* param object $operation The instance of the condition/action being configured
* return void
* }
* @type callable (optional) 'saveValues' {
* This callback can be used to process form submission values before they are saved.
*
* param array $values The values previously saved in the config
* param object $operation The instance of the condition/action being configured
* return void
* }
* @type callable (required) 'getArg' {
* This callback is called to get the value to use for the parameter.
*
* param array $values The values previously saved in the config
* params array $arg_map The event arguments mapped by key
* param object $operation The instance of the condition/action being configured
* return mixed
* }
* }
* }
* }
* }
*/
For example code, see the Conditions or Actions documentation.
@Definition Optimization
When a callback is provided as a definition, the callback will be used to retrieve the definition only when details about the ECA are needed, such as if there are rules assigned to it which need to be evaluated. Otherwise, the callback is not invoked. This optimizes performance when any calculations are needed to arrive at the definition, since those calculations can be bypassed unless they are absolutely needed.
rules_describe_event( 'action', 'hook_name', function() {
return array(
'title' => do_expensive_calculation(),
);
});
Also, the definition callback is only ever invoked a maximum of one time, as the result is automatically cached for the duration of the script run.