Entities

Entity objects are the part of the Entities API that encapsulate various objects to provide a common interface for interacting with them. Examples of object types for which WordPoints provides Entity classes would be users, posts, and comments.

Entity Classes #

The class for a particular type of entity needs to extend the WordPoints_Entity class. It could also extend any of the children of that class that are included with WordPoints to provide a bootstrap for common types of entities. For example, if your class is for an entity that is stored in a database table, it could extend WordPoints_Entity_Stored_DB_Table. Since this is the most common case, let’s look at an example using the user entity class:

We see that mostly this class consists of protected properties, with just one method. That’s because most of the heavy-lifting is provided by the base classes, so we just need to fill in the blanks, as it were. So what does each of these do?

  • $wpdb_table_name — the name of the property on the $wpdb global that contains name of this table. WordPress stores the name of the table that users are stored in in $wpdb->users, so the value here is 'users'. If the table name for an entity type isn’t available on $wpdb, you can either add it yourself, or override the get_storage_info() method in your child class to provide the storage information for the entity, rather than defining this field.
  • $context — the context that entities of this type exist within. Usually entities exist within the context of a particular site on the network. For example, a post is tied to a particular site, so its context value would be 'site'. That’s the default, so we could just omit this field entirely in our child class. However, users are global to the install, even when in multisite, so the context here is just an empty string, which indicates global context.
  • $id_field — the field of the objects for this type of entity which contains the entity’s ID. WP_User objects provide the user ID via the ID field, so the value in this case is 'ID'. This is used by the base entity class to get the ID of an entity when an object is passed to the set_the_value() method.
  • $getter — the function to use to retrieve an object for an entity given the entity ID. In this case we can use the get_userdata() function included with WordPress, since it takes a user ID as the only required parameter and returns the object for that user. However, in some cases a suitable function may not exist, so you would need to override the get_entity() method to get the entity  object by ID in your child class instead of defining this property.
  • $human_id_field — the field on objects for entities of this type that contains a value that provides a human-readable ID for this entity. In this case, we can use the display_name field to provide a more human-readable identifier for an entity than the user ID. The human-readable ID doesn’t have to be unique to each entity of that type, but it should be generally useful in helping someone know exactly what entity object it refers to. If the objects for entities of a particular type don’t provide a field that makes a good human-readable ID, you can override the get_human_entity_id() method in your child class to provide an ID rather than defining this field. The WordPoints_Entity_Comment class does this to provide a comment excerpt as the human-readable ID.

The single method that all entity classes need to define is the get_title() method. This method should return a string that is the title for an entity of this type. In this case, 'User'.

In some cases, our entity class may also need to supplemented in other parts of the entities API. For example:

  • Entity Restrictions API — When not all users are always allowed to view a particular entity. For example, posts can be private, so we need to check the whether the user has the 'read_post' capability for a particular post before we allow them to view it.

Registering an Entity #

Once you’ve created an entity class, you need to let WordPoints know that it exists so that it can be used by the Hooks API and other features. To do this, you just need to register your entity class with the entity class registry:

It’s as simple as that. Just hook into the initialization of the entities class registry and register your entity class with a unique slug.