1. Home
  2. Docs
  3. Rules Developer Guide
  4. Extending Rules
  5. Definitions

Definitions

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.

Was this article helpful to you? Yes No

How can we help?