HLKD7FOTW - field_get_items()
1 February 2011 - 7:07pm — Dave Reid
Today chx and timplunkett inspired me to start a regular, short weekly blog post about my experience and knowledge with 'helpful lesser-known Drupal 7 functions' (HLKD7F Of The Week). So I'd like to start sharing these fun Drupal 7 tidbits because even though they are obscure, they can be very helpful as a module or core developer. So with that short introduction, I present... *drumroll* field_get_items().
Trying to get the raw data from a node's field can be confusing and complicated; field data is stored at least two levels deep from the entity object itself. For example, a simple taxonomy field stores its node data on the node object with the following structure:
<?php
stdClass::__set_state(array(
'title' => 'My tagged node',
'nid' => '1',
'uid' => '1',
'type' => 'article',
'language' => 'und',
...
'field_tags' => array(
'und' => array(
0 => array('tid' => '5'),
1 => array('tid' => '28'),
2 => array('tid' => '29'),
),
),
))
?>We cannot know for certain that the data in the 'field_tags' array is always associated with the unknown language ('und'), so this is where field_get_items() comes in handy. All we need to provide it with is an entity type, the entity object itself, and the field name and it will automatically determine what language the field's data is and return the array of items for you.
<?php
$items = field_get_items('node', $node, 'field_tags');
var_export($items);
?>Results:
array(
0 => array('tid' => '5'),
1 => array('tid' => '28'),
2 => array('tid' => '29'),
)It's important to note that if the specified entity has that field attached to it, but does not currently have any data, this will return an empty array(). But if the entity does not have that field attached (e.g. if my article content type did not have a field named 'field_tags'), then it will return FALSE. I highly recommend using this function rather than trying to get the values directly using statements like $items = $node->field_tags[LANGUAGE_NONE];.
Have any functions that you've discovered that you would like me to blog about? Please let me know in the comments or contact me!
Very timely article. I new there had to be a better way than stringing together things like
$node->field_name[$node->language]....Just out curiosity: Why is the $node->language undefined and how do you set it to be defined, is there some documentation on this $node->language
The language isn't undefined. 'und' is the ISO language code for 'Undetermined' which is more useful and accurate than using an empty string like we did with Drupal 6.
More precisely, since there can be values of the field for the object in several languages (field translation - see Gabor's blog post :
this function returns the values that would be displayed given the current language settings.
Never use und, use LANGUAGE_NONE if you must.
Thanks! I overlooked the usage in my tiny example at the end, so I've adjusted that to enforce that the constant should be used whenever possible.
Thanks for the post.
Is there a convenient way to set the value of a field too, something like field_set_items() ?
Paul
Hi, thanks for this tip. I just tried it, and the array I get returned, is a little different (output is from the dpm function):
0 (Array, 3 elements)
value (String, 5 characters ) Hello
format (NULL)
safe_value (String, 5 characters ) Hello
1 (Array, 3 elements)
value (String, 30 characters ) Hello again!
format (NULL)
safe_value (String, 36 characters ) Hello again! <some nasty code>
I guess, the structure of the array depends on the kind of field type you ask for.
You can also use this function to get fields from the user object, although you need to pass it a full user object as returned by user_load().
We are working on improving the situation, see http://drupal.org/node/1232120#comment-4795532 and http://drupal.org/node/1232120#comment-4807340.