BASIC USAGE
First step, create the wrapper.
// You need the entity type and entity id. $type = 'node'; $nid = 123; $wrapper = entity_metadata_wrapper($type, $nid); // You can also pass in a fully- or partially-loaded entity object instead of the id. // Only do this if you're handed the object; i.e., don't bother loading the object just to pass into EMW. $node = node_load($nid); // Node loaded somewhere before your code. $wrapper = entity_metadata_wrapper($type, $node);
Get the entity object back out of the wrapper.
$wrapper = entity_metadata_wrapper('node', $nid);
$node = $wrapper->value();
Working with Text field data.
// OLD & BUSTED: Field API arrays $l = $node->langugage; $old_value = $node->field_my_text[$l][0]['value']; $node->field_my_text[$l][0]['value'] = 'new value'; // New Hotness: EMW $old_value = $wrapper->field_my_text->value(); $wrapper->field_my_text = 'new value';
Working with Longtext field data.
$wrapper->body->value(); // Array of: value, safe_value, format, and optionally summary + safe_summary. $wrapper->body->value->value(); // Filtered value. $wrapper->body->value->raw(); // Unfiltered value. $wrapper->body->format->value(); // The selected text format. $wrapper->body->value = 'new value';
Working with Link field data.
$wrapper->field_my_link->value(); // Array of: url, title, attributes. $wrapper->field_my_link->url->value(); // Hyperlink destination. $wrapper->field_my_link->title->value(); // Hyperlink text. $wrapper->field_my_link->attributes->value(); // Array of: target, title, etc. $wrapper->field_my_link->url = 'http://mediacurrent.com'; $wrapper->field_my_link->title = 'Do Drupal Right';
Working with fields of a referenced entity. Chaining is a really neat part of EMW. Consider a Commerce Line Item entity which has a reference to its Commerce Order:
// Display "Order submitted by jane.doe".
$line_item = entity_metadata_wrapper('commerce_line_item', $line_item_id);
$name = $line_item->order->owner->label();
echo t('Order submitted by %label', array('%label' => $name));
...
// Display the second Line Item's date of creation.
$order = entity_metadata_wrapper('commerce_order', $order_id);
$label = $order->commerce_line_items[1]->label();
$date = $order->commerce_line_items[1]->created->value();
echo t('%label created on %date', array(
'%label' => $label,
'%date' => format_date($date),
));
Deleting a value.
$wrapper->field_foobar = NULL;
Looping over multi-value field data. Let's again consider a Commerce scenario. Say we need to perform logic against each Line Item of an Order:
$order = entity_metadata_wrapper('commerce_order', $order_id);
// Use count() to gracefully handle emptyset; this isn't required.
if (0 == $order->commerce_line_items->count()) {
echo t('Order has no line items!');
return;
}
foreach ($order->commerce_line_items as $line_item) {
echo t('Processing Line Item %label', array('%label' => $line_item->label()));
...
}
Note that the d.o documentation demonstrates using the getIterator() method for looping. This is unncecessary; the method gets called automagically and need not be called explicitly except in rare cases.
COMMON MISTAKES
Loading the entity object just for passing into EMW. Unless you already have the pre-populated entity, it's more efficient to just pass the entity id to entity_metadata_wrapper(); EMW will lazy load the field and property data that it needs, hoorah! So much magic.
// Unnecessary node load...
$node = node_load($nid);
$wrapper = entity_metadata_wrapper('node', $node);
// More efficient (if the object isn't handed to you)...
$wrapper = entity_metadata_wrapper('node', $nid);
Using set(), get(), offsetSet(), and offsetGet(). While these methods must exist under the hood to satisfy EMW's implementation of the ArrayAccess interface, you rarely need to use them. Improve your code readability and WOW your code reviewers by using the PHP magic methods that EMW has implemented! Disregard the d.o documentation that shows examples of using these methods.
// Instead of set() to assign new field values...
$wrapper->field_foobar->set('new value');
// Let the PHP magic method do its work!
$wrapper->field_foobar = 'new value';
// And Instead of offsetGet()/offsetSet() to access multi-value field data...
$old_value = $wrapper->field_foobar->offsetGet(2);
$wrapper->field_foobar->offsetSet(2, $new_value);
// You can treat that field like an array!
$old_value = $wrapper->field_foobar[2]->value();
$wrapper->field_foobar[2] = $new_value;
$wrapper->field_foobar[] = $additional_value;
Saving the entity with node_save(), taxonomy_term_save(), etc. instead of the EMW save() method. Fun fact: both EMW and standard entity controllers include save() methods, so you can call e.g. $node->save() on properly instantiated entity objects and wrappers.
// If you don't already have the node object, don't bother loading it just to save... $wrapper->field_foobar = 'new value'; $node = $wrapper->value(); node_save($node); // Easier and prettier... $wrapper->field_foobar = 'new value'; $wrapper->save();
Forgetting that modifications to the wrapper likewise affect the passed entity object! Because objects are passed by reference in PHP, this relationship holds when the entity object is passed into the wrapper or the entity object is gotten via the wrapper.
// Changes to the wrapper affect its entity object.
$node->field_foobar[$l][0]['value'] = 'foo';
$wrapper = entity_metadata_wrapper('node', $node);
$wrapper->field_foobar = 'bar';
return $node->field_foobar[$l][0]['value']; // Returns 'bar'.
And vice versa...
// Changes to the entity object affect its wrapper.
$wrapper = entity_metadata_wrapper('node', $nid);
$wrapper->field_foobar = 'bar';
$node = $wrapper->value();
$node->field_foobar[$l][0]['value'] = 'foo';
return $wrapper->field_foobar->value(); // Returns 'foo'.
USING EMW TO CHECK FOR EMPTY FIELD DATA
Beware using EMW to check for empty field data. Let's say the "page" content type has field_foobar defined in its field configuration. Then the following will never* change, no matter whether a given page node actually has a value for field_foobar.
isset($wrapper->field_foobar); // Always TRUE empty($wrapper->field_foobar); // Always FALSE
*Exception to the rule: Entities not loaded via the API (e.g., during programmatic creation, cached entity hydration, etc.) may lack field members and cause EMW to report them as missing.
Checking for empty textfields.
$value = $wrapper->field_my_text->value();
if (isset($value)) {
// Entity has a non-null value for field_my_text, but it might be 0 or empty string.
}
if (!empty($value)) {
// Entity has a value for field_my_text, and it is not 0, empty string, etc.
}
Checking for empty entity references.
// If efficiency is primary, use raw() to only load the referenced entity's ID. // However, you can't assume the referenced entity actually exists. $value = $wrapper->field_my_reference->raw(); // Using value() is less efficient because it loads all the entity data // But it tells you whether the referenced entity actually exists. $value = $wrapper->field_my_reference->value(); // Now use isset/!empty($value) as above.
Checking for empty fields of a referenced entity. Things get tricky here.
// First, make a shortcut variable.
$reference = $wrapper->field_my_reference; // An EMW object.
// Next, find out whether the reference is specified and exists.
// See above on using value() vs. raw() on entity references.
// Finally, follow the same "field is empty" checks as above. E.g.,
$value = $reference->field_foobar->value();
if (empty($value)) {
$field_info = $reference->field_foobar->info();
echo t("No value specified for %label"), array('%label' => $field_info['label']));
}
// For the curious, note this EMW output when the wrapper points to a
// non-existant entity or the value is not set on a reference field.
isset($wrapper->title); // TRUE for any entity property.
isset($wrapper->field_foobar); // FALSE for any bundle field.
$wrapper->title->value(); // PHP fatal error for any field or property.
ADVANCED TIPS AND TRICKS
value() versus raw(): the differences between these methods vary by EMW class and by field type.
- Wrapped entities (EntityDrupalWrapper instances): No difference. Both value() and raw() return the fully-loaded entity object.
- Entity reference fields: value() returns the loaded entity object while raw() returns the entity id.
- Unfiltered text fields: No difference. The two methods return identical output.
- Filtered text fields: raw() returns the unfiltered user input while value() first passes the input through the field's selected text format.
Other important EMW methods: A smattering of the various EMW functions I use regularly. Note that there exists a wealth of additional useful methods, and I recommend exploring the API documentation on DrupalContrib to become familiar with it.
- label(): For most entity types, label() simply returns the title property. For user entities, it returns the username property. And if using the realname module, it returns the user's name as defined by that module's configuration. For Commerce Orders, it returns "Order order id". The bottom line: In most cases, use label() as a simpler, prettier, more canonical version of $wrapper->title->value().
- getIdentifier(): instead of $node_wrapper->nid->value(), $user_wrapper->uid->value(), $order_wrapper->order_id->value(), etc.
- getPropertyInfo(): An invaluable debugging tool, this method outputs all the properties and fields that EMW knows about. Trying to access any item not in the list reported by getPropertyInfo() will result in a PHP exception, even if the item exists on the loaded entity object. getPropertyInfo() is a method of the EntityStructureWrapper class, which includes wrapped entities and complex fields; calling it against EntityValueWrapper instances (e.g., simple fields/properties like title or an unfiltered Text fields) results in a PHP fatal error.
- getBundle(): Determine the entity's bundle (e.g., for nodes, the content type).
- info(): Provides detailed information about the item (entity or field). E.g., I use this when I need a field's label during error handling.
- validate(): Attempting to set an invalid value via EMW throws a PHP exception, so validate() is a very important in error handling! E.g., the following will output "Bad field value":
// $value is NULL, title is required. if ($wrapper->title->validate($value)) { $wrapper->title = $value; } else { echo t("Bad field value"); }
- See more at: http://www.mediacurrent.com/blog/entity-metadata-wrapper#sthash.oNP6Hfz1.dpuf
http://www.mediacurrent.com/blog/entity-metadata-wrapper
BASIC USAGE
First step, create the wrapper.
// You need the entity type and entity id. $type = 'node'; $nid = 123; $wrapper = entity_metadata_wrapper($type, $nid); // You can also pass in a fully- or partially-loaded entity object instead of the id. // Only do this if you're handed the object; i.e., don't bother loading the object just to pass into EMW. $node = node_load($nid); // Node loaded somewhere before your code. $wrapper = entity_metadata_wrapper($type, $node);
Get the entity object back out of the wrapper.
$wrapper = entity_metadata_wrapper('node', $nid);
$node = $wrapper->value();
Working with Text field data.
// OLD & BUSTED: Field API arrays $l = $node->langugage; $old_value = $node->field_my_text[$l][0]['value']; $node->field_my_text[$l][0]['value'] = 'new value'; // New Hotness: EMW $old_value = $wrapper->field_my_text->value(); $wrapper->field_my_text = 'new value';
Working with Longtext field data.
$wrapper->body->value(); // Array of: value, safe_value, format, and optionally summary + safe_summary. $wrapper->body->value->value(); // Filtered value. $wrapper->body->value->raw(); // Unfiltered value. $wrapper->body->format->value(); // The selected text format. $wrapper->body->value = 'new value';
Working with Link field data.
$wrapper->field_my_link->value(); // Array of: url, title, attributes. $wrapper->field_my_link->url->value(); // Hyperlink destination. $wrapper->field_my_link->title->value(); // Hyperlink text. $wrapper->field_my_link->attributes->value(); // Array of: target, title, etc. $wrapper->field_my_link->url = 'http://mediacurrent.com'; $wrapper->field_my_link->title = 'Do Drupal Right';
Working with fields of a referenced entity. Chaining is a really neat part of EMW. Consider a Commerce Line Item entity which has a reference to its Commerce Order:
// Display "Order submitted by jane.doe".
$line_item = entity_metadata_wrapper('commerce_line_item', $line_item_id);
$name = $line_item->order->owner->label();
echo t('Order submitted by %label', array('%label' => $name));
...
// Display the second Line Item's date of creation.
$order = entity_metadata_wrapper('commerce_order', $order_id);
$label = $order->commerce_line_items[1]->label();
$date = $order->commerce_line_items[1]->created->value();
echo t('%label created on %date', array(
'%label' => $label,
'%date' => format_date($date),
));
Deleting a value.
$wrapper->field_foobar = NULL;
Looping over multi-value field data. Let's again consider a Commerce scenario. Say we need to perform logic against each Line Item of an Order:
$order = entity_metadata_wrapper('commerce_order', $order_id);
// Use count() to gracefully handle emptyset; this isn't required.
if (0 == $order->commerce_line_items->count()) {
echo t('Order has no line items!');
return;
}
foreach ($order->commerce_line_items as $line_item) {
echo t('Processing Line Item %label', array('%label' => $line_item->label()));
...
}
Note that the d.o documentation demonstrates using the getIterator() method for looping. This is unncecessary; the method gets called automagically and need not be called explicitly except in rare cases.
COMMON MISTAKES
Loading the entity object just for passing into EMW. Unless you already have the pre-populated entity, it's more efficient to just pass the entity id to entity_metadata_wrapper(); EMW will lazy load the field and property data that it needs, hoorah! So much magic.
// Unnecessary node load...
$node = node_load($nid);
$wrapper = entity_metadata_wrapper('node', $node);
// More efficient (if the object isn't handed to you)...
$wrapper = entity_metadata_wrapper('node', $nid);
Using set(), get(), offsetSet(), and offsetGet(). While these methods must exist under the hood to satisfy EMW's implementation of the ArrayAccess interface, you rarely need to use them. Improve your code readability and WOW your code reviewers by using the PHP magic methods that EMW has implemented! Disregard the d.o documentation that shows examples of using these methods.
// Instead of set() to assign new field values...
$wrapper->field_foobar->set('new value');
// Let the PHP magic method do its work!
$wrapper->field_foobar = 'new value';
// And Instead of offsetGet()/offsetSet() to access multi-value field data...
$old_value = $wrapper->field_foobar->offsetGet(2);
$wrapper->field_foobar->offsetSet(2, $new_value);
// You can treat that field like an array!
$old_value = $wrapper->field_foobar[2]->value();
$wrapper->field_foobar[2] = $new_value;
$wrapper->field_foobar[] = $additional_value;
Saving the entity with node_save(), taxonomy_term_save(), etc. instead of the EMW save() method. Fun fact: both EMW and standard entity controllers include save() methods, so you can call e.g. $node->save() on properly instantiated entity objects and wrappers.
// If you don't already have the node object, don't bother loading it just to save... $wrapper->field_foobar = 'new value'; $node = $wrapper->value(); node_save($node); // Easier and prettier... $wrapper->field_foobar = 'new value'; $wrapper->save();
Forgetting that modifications to the wrapper likewise affect the passed entity object! Because objects are passed by reference in PHP, this relationship holds when the entity object is passed into the wrapper or the entity object is gotten via the wrapper.
// Changes to the wrapper affect its entity object.
$node->field_foobar[$l][0]['value'] = 'foo';
$wrapper = entity_metadata_wrapper('node', $node);
$wrapper->field_foobar = 'bar';
return $node->field_foobar[$l][0]['value']; // Returns 'bar'.
And vice versa...
// Changes to the entity object affect its wrapper.
$wrapper = entity_metadata_wrapper('node', $nid);
$wrapper->field_foobar = 'bar';
$node = $wrapper->value();
$node->field_foobar[$l][0]['value'] = 'foo';
return $wrapper->field_foobar->value(); // Returns 'foo'.
USING EMW TO CHECK FOR EMPTY FIELD DATA
Beware using EMW to check for empty field data. Let's say the "page" content type has field_foobar defined in its field configuration. Then the following will never* change, no matter whether a given page node actually has a value for field_foobar.
isset($wrapper->field_foobar); // Always TRUE empty($wrapper->field_foobar); // Always FALSE
*Exception to the rule: Entities not loaded via the API (e.g., during programmatic creation, cached entity hydration, etc.) may lack field members and cause EMW to report them as missing.
Checking for empty textfields.
$value = $wrapper->field_my_text->value();
if (isset($value)) {
// Entity has a non-null value for field_my_text, but it might be 0 or empty string.
}
if (!empty($value)) {
// Entity has a value for field_my_text, and it is not 0, empty string, etc.
}
Checking for empty entity references.
// If efficiency is primary, use raw() to only load the referenced entity's ID. // However, you can't assume the referenced entity actually exists. $value = $wrapper->field_my_reference->raw(); // Using value() is less efficient because it loads all the entity data // But it tells you whether the referenced entity actually exists. $value = $wrapper->field_my_reference->value(); // Now use isset/!empty($value) as above.
Checking for empty fields of a referenced entity. Things get tricky here.
// First, make a shortcut variable.
$reference = $wrapper->field_my_reference; // An EMW object.
// Next, find out whether the reference is specified and exists.
// See above on using value() vs. raw() on entity references.
// Finally, follow the same "field is empty" checks as above. E.g.,
$value = $reference->field_foobar->value();
if (empty($value)) {
$field_info = $reference->field_foobar->info();
echo t("No value specified for %label"), array('%label' => $field_info['label']));
}
// For the curious, note this EMW output when the wrapper points to a
// non-existant entity or the value is not set on a reference field.
isset($wrapper->title); // TRUE for any entity property.
isset($wrapper->field_foobar); // FALSE for any bundle field.
$wrapper->title->value(); // PHP fatal error for any field or property.
ADVANCED TIPS AND TRICKS
value() versus raw(): the differences between these methods vary by EMW class and by field type.
- Wrapped entities (EntityDrupalWrapper instances): No difference. Both value() and raw() return the fully-loaded entity object.
- Entity reference fields: value() returns the loaded entity object while raw() returns the entity id.
- Unfiltered text fields: No difference. The two methods return identical output.
- Filtered text fields: raw() returns the unfiltered user input while value() first passes the input through the field's selected text format.
Other important EMW methods: A smattering of the various EMW functions I use regularly. Note that there exists a wealth of additional useful methods, and I recommend exploring the API documentation on DrupalContrib to become familiar with it.
- label(): For most entity types, label() simply returns the title property. For user entities, it returns the username property. And if using the realname module, it returns the user's name as defined by that module's configuration. For Commerce Orders, it returns "Order order id". The bottom line: In most cases, use label() as a simpler, prettier, more canonical version of $wrapper->title->value().
- getIdentifier(): instead of $node_wrapper->nid->value(), $user_wrapper->uid->value(), $order_wrapper->order_id->value(), etc.
- getPropertyInfo(): An invaluable debugging tool, this method outputs all the properties and fields that EMW knows about. Trying to access any item not in the list reported by getPropertyInfo() will result in a PHP exception, even if the item exists on the loaded entity object. getPropertyInfo() is a method of the EntityStructureWrapper class, which includes wrapped entities and complex fields; calling it against EntityValueWrapper instances (e.g., simple fields/properties like title or an unfiltered Text fields) results in a PHP fatal error.
- getBundle(): Determine the entity's bundle (e.g., for nodes, the content type).
- info(): Provides detailed information about the item (entity or field). E.g., I use this when I need a field's label during error handling.
- validate(): Attempting to set an invalid value via EMW throws a PHP exception, so validate() is a very important in error handling! E.g., the following will output "Bad field value":
// $value is NULL, title is required. if ($wrapper->title->validate($value)) { $wrapper->title = $value; } else { echo t("Bad field value"); }
- See more at: http://www.mediacurrent.com/blog/entity-metadata-wrapper#sthash.oNP6Hfz1.dpuf
http://www.mediacurrent.com/blog/entity-metadata-wrapper
http://www.mediacurrent.com/blog/entity-metadata-wrapper
BASIC USAGE
First step, create the wrapper.
// You need the entity type and entity id. $type = 'node'; $nid = 123; $wrapper = entity_metadata_wrapper($type, $nid); // You can also pass in a fully- or partially-loaded entity object instead of the id. // Only do this if you're handed the object; i.e., don't bother loading the object just to pass into EMW. $node = node_load($nid); // Node loaded somewhere before your code. $wrapper = entity_metadata_wrapper($type, $node);
Get the entity object back out of the wrapper.
$wrapper = entity_metadata_wrapper('node', $nid);
$node = $wrapper->value();
Working with Text field data.
// OLD & BUSTED: Field API arrays $l = $node->langugage; $old_value = $node->field_my_text[$l][0]['value']; $node->field_my_text[$l][0]['value'] = 'new value'; // New Hotness: EMW $old_value = $wrapper->field_my_text->value(); $wrapper->field_my_text = 'new value';
Working with Longtext field data.
$wrapper->body->value(); // Array of: value, safe_value, format, and optionally summary + safe_summary. $wrapper->body->value->value(); // Filtered value. $wrapper->body->value->raw(); // Unfiltered value. $wrapper->body->format->value(); // The selected text format. $wrapper->body->value = 'new value';
Working with Link field data.
$wrapper->field_my_link->value(); // Array of: url, title, attributes. $wrapper->field_my_link->url->value(); // Hyperlink destination. $wrapper->field_my_link->title->value(); // Hyperlink text. $wrapper->field_my_link->attributes->value(); // Array of: target, title, etc. $wrapper->field_my_link->url = 'http://mediacurrent.com'; $wrapper->field_my_link->title = 'Do Drupal Right';
Working with fields of a referenced entity. Chaining is a really neat part of EMW. Consider a Commerce Line Item entity which has a reference to its Commerce Order:
// Display "Order submitted by jane.doe".
$line_item = entity_metadata_wrapper('commerce_line_item', $line_item_id);
$name = $line_item->order->owner->label();
echo t('Order submitted by %label', array('%label' => $name));
...
// Display the second Line Item's date of creation.
$order = entity_metadata_wrapper('commerce_order', $order_id);
$label = $order->commerce_line_items[1]->label();
$date = $order->commerce_line_items[1]->created->value();
echo t('%label created on %date', array(
'%label' => $label,
'%date' => format_date($date),
));
Deleting a value.
$wrapper->field_foobar = NULL;
Looping over multi-value field data. Let's again consider a Commerce scenario. Say we need to perform logic against each Line Item of an Order:
$order = entity_metadata_wrapper('commerce_order', $order_id);
// Use count() to gracefully handle emptyset; this isn't required.
if (0 == $order->commerce_line_items->count()) {
echo t('Order has no line items!');
return;
}
foreach ($order->commerce_line_items as $line_item) {
echo t('Processing Line Item %label', array('%label' => $line_item->label()));
...
}
Note that the d.o documentation demonstrates using the getIterator() method for looping. This is unncecessary; the method gets called automagically and need not be called explicitly except in rare cases.
COMMON MISTAKES
Loading the entity object just for passing into EMW. Unless you already have the pre-populated entity, it's more efficient to just pass the entity id to entity_metadata_wrapper(); EMW will lazy load the field and property data that it needs, hoorah! So much magic.
// Unnecessary node load...
$node = node_load($nid);
$wrapper = entity_metadata_wrapper('node', $node);
// More efficient (if the object isn't handed to you)...
$wrapper = entity_metadata_wrapper('node', $nid);
Using set(), get(), offsetSet(), and offsetGet(). While these methods must exist under the hood to satisfy EMW's implementation of the ArrayAccess interface, you rarely need to use them. Improve your code readability and WOW your code reviewers by using the PHP magic methods that EMW has implemented! Disregard the d.o documentation that shows examples of using these methods.
// Instead of set() to assign new field values...
$wrapper->field_foobar->set('new value');
// Let the PHP magic method do its work!
$wrapper->field_foobar = 'new value';
// And Instead of offsetGet()/offsetSet() to access multi-value field data...
$old_value = $wrapper->field_foobar->offsetGet(2);
$wrapper->field_foobar->offsetSet(2, $new_value);
// You can treat that field like an array!
$old_value = $wrapper->field_foobar[2]->value();
$wrapper->field_foobar[2] = $new_value;
$wrapper->field_foobar[] = $additional_value;
Saving the entity with node_save(), taxonomy_term_save(), etc. instead of the EMW save() method. Fun fact: both EMW and standard entity controllers include save() methods, so you can call e.g. $node->save() on properly instantiated entity objects and wrappers.
// If you don't already have the node object, don't bother loading it just to save... $wrapper->field_foobar = 'new value'; $node = $wrapper->value(); node_save($node); // Easier and prettier... $wrapper->field_foobar = 'new value'; $wrapper->save();
Forgetting that modifications to the wrapper likewise affect the passed entity object! Because objects are passed by reference in PHP, this relationship holds when the entity object is passed into the wrapper or the entity object is gotten via the wrapper.
// Changes to the wrapper affect its entity object.
$node->field_foobar[$l][0]['value'] = 'foo';
$wrapper = entity_metadata_wrapper('node', $node);
$wrapper->field_foobar = 'bar';
return $node->field_foobar[$l][0]['value']; // Returns 'bar'.
And vice versa...
// Changes to the entity object affect its wrapper.
$wrapper = entity_metadata_wrapper('node', $nid);
$wrapper->field_foobar = 'bar';
$node = $wrapper->value();
$node->field_foobar[$l][0]['value'] = 'foo';
return $wrapper->field_foobar->value(); // Returns 'foo'.
USING EMW TO CHECK FOR EMPTY FIELD DATA
Beware using EMW to check for empty field data. Let's say the "page" content type has field_foobar defined in its field configuration. Then the following will never* change, no matter whether a given page node actually has a value for field_foobar.
isset($wrapper->field_foobar); // Always TRUE empty($wrapper->field_foobar); // Always FALSE
*Exception to the rule: Entities not loaded via the API (e.g., during programmatic creation, cached entity hydration, etc.) may lack field members and cause EMW to report them as missing.
Checking for empty textfields.
$value = $wrapper->field_my_text->value();
if (isset($value)) {
// Entity has a non-null value for field_my_text, but it might be 0 or empty string.
}
if (!empty($value)) {
// Entity has a value for field_my_text, and it is not 0, empty string, etc.
}
Checking for empty entity references.
// If efficiency is primary, use raw() to only load the referenced entity's ID. // However, you can't assume the referenced entity actually exists. $value = $wrapper->field_my_reference->raw(); // Using value() is less efficient because it loads all the entity data // But it tells you whether the referenced entity actually exists. $value = $wrapper->field_my_reference->value(); // Now use isset/!empty($value) as above.
Checking for empty fields of a referenced entity. Things get tricky here.
// First, make a shortcut variable.
$reference = $wrapper->field_my_reference; // An EMW object.
// Next, find out whether the reference is specified and exists.
// See above on using value() vs. raw() on entity references.
// Finally, follow the same "field is empty" checks as above. E.g.,
$value = $reference->field_foobar->value();
if (empty($value)) {
$field_info = $reference->field_foobar->info();
echo t("No value specified for %label"), array('%label' => $field_info['label']));
}
// For the curious, note this EMW output when the wrapper points to a
// non-existant entity or the value is not set on a reference field.
isset($wrapper->title); // TRUE for any entity property.
isset($wrapper->field_foobar); // FALSE for any bundle field.
$wrapper->title->value(); // PHP fatal error for any field or property.
ADVANCED TIPS AND TRICKS
value() versus raw(): the differences between these methods vary by EMW class and by field type.
- Wrapped entities (EntityDrupalWrapper instances): No difference. Both value() and raw() return the fully-loaded entity object.
- Entity reference fields: value() returns the loaded entity object while raw() returns the entity id.
- Unfiltered text fields: No difference. The two methods return identical output.
- Filtered text fields: raw() returns the unfiltered user input while value() first passes the input through the field's selected text format.
Other important EMW methods: A smattering of the various EMW functions I use regularly. Note that there exists a wealth of additional useful methods, and I recommend exploring the API documentation on DrupalContrib to become familiar with it.
- label(): For most entity types, label() simply returns the title property. For user entities, it returns the username property. And if using the realname module, it returns the user's name as defined by that module's configuration. For Commerce Orders, it returns "Order order id". The bottom line: In most cases, use label() as a simpler, prettier, more canonical version of $wrapper->title->value().
- getIdentifier(): instead of $node_wrapper->nid->value(), $user_wrapper->uid->value(), $order_wrapper->order_id->value(), etc.
- getPropertyInfo(): An invaluable debugging tool, this method outputs all the properties and fields that EMW knows about. Trying to access any item not in the list reported by getPropertyInfo() will result in a PHP exception, even if the item exists on the loaded entity object. getPropertyInfo() is a method of the EntityStructureWrapper class, which includes wrapped entities and complex fields; calling it against EntityValueWrapper instances (e.g., simple fields/properties like title or an unfiltered Text fields) results in a PHP fatal error.
- getBundle(): Determine the entity's bundle (e.g., for nodes, the content type).
- info(): Provides detailed information about the item (entity or field). E.g., I use this when I need a field's label during error handling.
- validate(): Attempting to set an invalid value via EMW throws a PHP exception, so validate() is a very important in error handling! E.g., the following will output "Bad field value":
// $value is NULL, title is required. if ($wrapper->title->validate($value)) { $wrapper->title = $value; } else { echo t("Bad field value"); }
- See more at: http://www.mediacurrent.com/blog/entity-metadata-wrapper#sthash.oNP6Hfz1.dpuf
8610
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
