Actions

The action objects are the part of the Hooks API that connects it to WordPress’s familiar action/filter API. Action objects are used by the Hooks API’s router to transform a call of a WordPress action into a form that the Hooks API can digest.

A basic action object comes bundled with WordPoints, called WordPoints_Hook_Action. For many actions that you want to hook into, this class will be sufficient for you. For example, WordPoints uses it for the user_register action.

How do you know whether you can use WordPoints_Hook_Action or whether you’ll need a custom class? Before we can answer that question, we need to talk a little bit more about how actions work.

At the core of the Hooks API is a router that listens for WordPress actions, maps them to action objects, and triggers the rest of the Hooks API to fire. In order to do this, of course, it needs to know what actions to listen for, and which class to use when creating an object for each action. The router learns this information by you registering your actions when WordPoints initializes the action class registry, like this:

What we have here is just a function that is hooked to the initialization of the Hook Actions registry. The Action registry itself is passed as an argument to this action, and so all you need to do is call $actions->register() to register each of your actions.

The interesting part, of course, is when we come to the arguments that you need to pass to the action register method. The action registry is just a class registry, where you register a list of named classes. So the first argument is the slug for the class, and the second argument is the name of the class itself. The slug is a unique identifier that we can use to reference that class in other places without actually referencing the class name. This gives us the freedom to switch to a different class for handling this action later, without affecting any other code, since the slug can remain the same.

The real magic is in the third parameter, which as you can see is an associative array. The first key is 'action', and the value is 'user_register'. This is the information that will be used to tell the router that it should listen for this action, and that it should use this class to convert the action to an object. In this case, we’re listening to the 'user_register' action, which WordPress calls when a new user registers on the site.

The second element in this array has the key 'data', and its value is an array that can contain several different pieces of information. In the simple example above, we see that it has only one element, the 'arg_index'. The arg index is passed to the action object when it is constructed, along with the args that were passed to do_action() when the action was triggered. The arg index is used by the action object to convert the array of raw args from the WordPress action into an array of Hook Arg objects that can be used by the Hooks API.

In this case, our action has just one arg, the user ID, so the 'arg_index' is array( 'user' => 0 ). The keys of the arg index array here tell the Hooks API what type of entity each arg is, and the values indicate the index of that arg in the list of values from the WordPress action. So in this case, the 'user_register' action is called with just a single arg, and it is a user ID. So we indicate that the first arg (which will have the index 0 since the array of values is 0-indexed) should be converted to a 'user' entity object.

The job of converting the raw value to an entity object is handled by Arg objects. For more information about that, you can see the Hook Arg docs. You can also take a look at the Hook Event docs to find out how you can compose your actions together into events that can be used to trigger reactions.