Entity property information

For a general introduction of metadata about entity properties and its purpose, check this blog post.

In short hook_entity_property_info() is for collecting information about all the available entity properties - regardless of whether they are fields or not - in order to make them all accessible in the same way.

For simply making use of that information, the entity API provides the so called "Entity metadata wrappers".

Providing information about entity properties

To provide information about properties (including fields), you'll have to implement hook_entity_property_info(). You may put your hook implementations in the include yourmodule.info.inc, however any callbacks have to reside in files that are always included.

Let's consider the node module integration as an example:

/**
 * Implements hook_entity_property_info() on top of node module.
 *
 * @see entity_metadata_entity_property_info()
 */
function entity_metadata_node_entity_property_info() {
  $info = array();
  // Add meta-data about the basic node properties.
  $properties = &$info['node']['properties'];

  $properties['nid'] = array(
    'label' => t("Node ID"),
    'type' => 'integer',
    'description' => t("The unique ID of the node."),
    'schema field' => 'nid',
  );
  $properties['language'] = array(
    'label' => t("Language"),
    'type' => 'token',
    'description' => t("The language the node is written in."),
    'setter callback' => 'entity_metadata_verbatim_set',
    'options list' => 'entity_metadata_language_list',
    'schema field' => 'language',
    'setter permission' => 'administer nodes',
  );
  $properties['author'] = array(
    'label' => t("Author"),
    'type' => 'user',
    'description' => t("The author of the node."),
    'getter callback' => 'entity_metadata_node_get_properties',
    'setter callback' => 'entity_metadata_node_set_properties',
    'setter permission' => 'administer nodes',
    'required' => TRUE,
    'schema field' => 'uid',
  );
  // ...
  return $info;
}

As you can see you have to specify a label and optionally a description for each property. Properties may be read only, like the 'edit-url' or may support writing like 'author'. Check the docs of hook_entity_property_info() or the page about data types for a complete list of supported keys.

Handling entity references

In case of properties containing entity references like "uid" one should not expose an "uid" integer property, but a property that exposes the entity relationship. Just expose a property "user" or "author" of type "user", as seen in the example above.
Then, do not expose both the id and the entity reference, only expose the entity relationship. The id is accessible via the referenced entity (without having to load it) anyway.

Internally, an entity property is represented by its identifier, thus the setter callback has to accept the entity id as value. The getter callback may return the id or the full entity object though.

More

https://www.bluespark.com/blog/drupal-entities-part-1-moving-beyond-nodes