Arg objects are the part of the Hooks API that help do the work of transforming the args passed to an action through the WordPress action API into Entity objects that can be digested by the Hooks API.

At the heart of the Hooks API is a router that listens for calls to particular WordPress actions called via do_action(), and triggers the Hooks API with the arguments that were passed to the action. Each arg object has the job of providing an Entity object initialized with one of the values relating to the action at hand.

Using the 'user_register' action as an example, it is called by WordPress with a single argument, the ID of the user who is registering. To make that value available to the Hooks API, we’d need to register an Arg class that would take the first (and in this case, the only) action argument and convert it to a 'user' entity.

WordPoints comes bundled with a basic Arg class, WordPoints_Hook_Arg, that can easily convert any action arg into an Entity object. So in most cases, all you need to do to add an Arg to an Action is just specify it in the 'arg_index' when you register that action, and then you can reference that Arg when you register an Event that uses that action.

As you can see in the above example, we just specify that the Action should have an Arg that converts the first value (0 because of 0-indexed arrays) in the list of arguments into a 'user' Entity. Now the WordPoints_Hook_Action class will provide the value for that argument when an Event references it by its slug ('user'). You just need to register the Event Arg along with your Event:

That’s all we need to do, and the WordPoints_Hook_Arg object for the arg will be constructed with the slug 'user' and will pull the value of the 'user' argument from the action.

This is all that you have to do when you are registering an Arg object for a value that is passed as an argument when do_action() is called. However, there are occasionally times when you want to create an Arg for a value pulled from somewhere else. An example of this can be found in the 'current:user' arg for the 'user_visit' event:

As you can see, we override three parts of the parent class:

  • $is_stateful — This tells WordPoints that the value of this Arg is sourced from the current state of the application; the value doesn’t necessarily relate to the event directly, in that it isn’t modified in any way, it is just a bystander. This is different from the Post Arg of the Post Publish event, for example, because the post is being modified by the event (it is being published).
  • get_value() — This is the real meat of the Arg, and it just returns the Arg’s value.
  • get_title() — This is really extra fluff, that could be left out if we wanted to. It returns a title for the arg. Normally, this defaults to the title of the type of Entity that the Arg returns, but we decided that it would be better to describe the “User” as the “Visitor”, since this Arg is used for the Visit event.

In the examples above, we were registering an Arg for the user entity, which is included with WordPoints. However, sometimes you may want to register an Arg for an object type which isn’t a part of WordPress core. In that case, you’ll need to create a class for that Entity and register it via the Entity API.