Last updated July 7, 2014. Created on January 10, 2011.
Edited by gagarine, targoo, eojthebrave, Frank Ralf. Log in to edit this page.

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:

<?php
/**
 * 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.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

Jax’s picture

It's really unclear what should happen in a function set as property_callback. There isn't an example or documentation available.

fago’s picture

You should return the value of your property. The value has to be formatted has documented for your data type (see the data types page), e.g. if you implement a 'date' property you have to return it as a timestamp.

gagarine’s picture

The best documentation i found is this blog post (3 part) http://www.istos.it/blog/drupal/drupal-entities-part-1-moving-beyond-nodes

------
cloud33.com

JvE’s picture

Note that the "getter callback" and "setter callback" functions are only used by Entity metadata wrappers.
Not by entity_load or Views and such.

You can not use these to convert a different timestamp format in a database to a timestamp for use with the 'date' type unless you specifically create a wrapper for each of your entity instances.

I tried to get my (int)yyyymmdd values from the database to show up in Views as dates and mistakenly thought I could use the "getter callback" for the transformation.
Example of when callback is and is not used:

<?php
    $entity
= entity_load('myentity', array(1));
    print
$entity->day; // this gives 20110721 (from the database)
   
$item = entity_metadata_wrapper('myentity', $entity);
    print
$item->day->value(); // this gives 1311206400 (from the "getter callback")
?>

In Views my day shows up as "08/21/1970 - 19:18" ...
so if someone can point me in the right direction to get my "days" as timestamps, I'm all ears.

havran’s picture

I have same experience. I'm need solution too.

--
My site - Svoji.SK
My first Drupal site - http://www.enigma.sk/

Pierco’s picture

Add the following in your hook_entity_property_info()

  'computed' => TRUE,
  'entity views field' => TRUE,

Your property will be exposed as a view property.
see: http://drupalcontrib.org/api/drupal/contributions!entity!entity.api.php/function/hook_entity_property_info/7

jfinkel’s picture

Properties may be read only, like the 'edit-url' or may support writing like 'author'.

I do not see 'edit-url' anywhere. Am I missing something?

alexweber’s picture

The above example is incomplete, if you look at entity/modules/node.info.inc you will find the full hook implementation, including 'edit-url':

<?php
  $properties
['edit_url'] = array(
   
'label' => t("Edit URL"),
   
'description' => t("The URL of the node's edit page."),
   
'getter callback' => 'entity_metadata_node_get_properties',
   
'type' => 'uri',
   
'computed' => TRUE,
  );
?>
magtak’s picture

what happens in this case when the property is an entity but we cannot know beforehand what kind of entity it will be? How can we handle this so the entity in the property will be available in views and such? I've been meddling with getter callbacks but I can't seem to find a solution.

Support Engineer at Acquia

alexweber’s picture

As far as I know this just isn't possible in Drupal 7 because of the way core entities are implemented.

afinnarn’s picture

This might not be what you're looking for, but the Entity API docs for hook_entity_property_info() list an 'entity' type for unknown entities at the time of declaration. Also check out the section on Views integration in this set of docs.

"entity: A special type to be used generically for entities where the entity type is not known beforehand. The entity has to be represented using an EntityMetadataWrapper."

-Finn