Entity Storage Info

Most objects, relationships, and attributes encapsulated by the Entity API are stored somewhere, like in the database. Knowing where and how they are stored is very useful information that can allow developers to do really cool things with entities that they wouldn’t otherwise be able to do. To facilitate providing storage information for elements in the entity API, their classes can implement the WordPoints_Entityish_StoredI interface and return their storage info from the get_storage_info() method that interface requires.

The get_storage_info() method’s return value will always be an associative array with two keys:

  • 'type' — the storage type.
  • 'info' — an array of other info.

The currently supported storage types are:

  • db — stored in a table in the database.

The elements in the info array will vary based on the storage type and the type of entityish thing in question (an entity, attribute, or relationship).

Entities #

For entities, here is the supported syntax for the info for each storage type:

db

  • type — the type of database storage. Currently 'table' is the only supported value.
  • table_name — the name of the table that entities of this type are stored in.

Attributes #

Here is the supported syntax for the info for entity attributes for each storage type:

db

  • type — the type of database storage. Currently supported values are 'field', 'table', and 'meta_table'.

field

When the attribute data is stored in a field of the table for entities of this type, the syntax is:

  • field — the name of the column that this attribute’s value is stored in.

table

When the attribute data is stored in a field of a table other than the table for entities of this type, the syntax is:

  • table_name — the name of the table in the database where these attributes are stored.
  • entity_id_field — the column in the database table where the ID of the entity is stored.
  • attr_field — the column in the database table where the entity attribute value is stored.

meta_table

When the attribute data is stored in a field of another table, post-meta style, the syntax is:

  • table_name — the name of the table in the database where these attributes are stored.
  • entity_id_field — the column in the database table where the ID of the entity is stored.
  • meta_key — the name of the attribute to search for in the meta key column.
  • meta_key_field — the column in the database table where the name of the attribute (“meta key”) is stored.
  • meta_value_field — the column in the database table where the value of the attribute is stored.

Currently this syntax is only intended to support cases where there is only one value per attribute per entity. When multiple entries for an attribute name occur per entity, the behavior is undefined. The syntax will be extended to support this in the future if it is needed.

Relationships #

Here is the supported syntax for the info for entity relationships for each storage type:

db

  • type — the type of database storage. Currently supported values are 'field' and 'table'.

field

When the relationship data is stored in a field of the table for entities of this type, the syntax is:

  • field — the name of the column that this relationship’s value is stored in.

table

When the relationship data is stored in a field of another table, the syntax is:

  • table_name — the name of the table in the database where these relationships are stored.
  • primary_id_field — the column in the database table where the ID of the primary entity in the relationship is stored.
  • related_id_field — the column in the database table where the ID of the related entity is stored.
  • conditions — an optional array of additional conditions to query on.

The primary_id_field and related_id_field can also be an array providing additional info about the field:

  • field — the name column in the database.
  • type — the type of field. Supported values include: 'serialized_array'.

Sometimes getting the related value requires a join on another table. In that case, you can provide an array for the related_id_field using the following syntax:

  • table_name — the name of the table in the database to perform the JOIN on.
  • on — the fields to join on:
    • primary_field — the name of the column in the main table being joined from.
    • join_field — the name of the column in the table being joined to.

Each value in the conditions array is an array with the following syntax:

  • field — the name of the column in the database to set this condition on.
  • value — a specific value that this column must match.

Both one-to-one and one-to-many relationships can be stored in this way. That is, you could have each value for the primary_id_field be unique in the table, or a single value in the primary_id_field could occur in multiple rows with different values for the related_id_field column.