Drupal7如何使用Entity metadata wrappers (Entity API)

注：本文翻译自：https://www.drupal.org/documentation/entity-metadata-wrappers 由于英文水平有限，某些句子可能理解不是很到位，如有疑虑请自行查阅源文档。


使用wrapper包装类可以更容易的以一致的编程的方式获取和设置字段的值以及内容。
举例来说，当我们需要从一个node节点中获取某个字段的值，以下这种方法是我们经常在drupal的实体中获取值的方式：

$node->field_number[LANGUAGE_NONE][0]['value']

尽管这种方式在大多数情况下可以正常工作，但是这并不理想。比如：用户要求页面需要显示不同的语言或者上面的字段中的'value'并不存在亦或是一个image或file类型的字段呢？
使用Entity模块提供的metadata wrapper我们可以轻松的获取某个字段的值而不用顾虑这些，就像这样：

$node_wrapper->field_number->value();

Drupal中所有的Entities实体类型都有某种类型的label。实体类型的label通常是一个对用户友好的字符名称，例如：所有的节点类型都有title的属性、所有用户都有用户名称，如果是一个标准的实体类型我们将很难知道如何正确的处理这些label。Metadata wrapper提供了一个统一的方法去获取不同实体类型的信息。例如：

//Unifiedwayofgetting$node->title,$user->name,...
$wrapper->label();
//Unifiedwayofgetting$node->nid,$user->uid,...
$wrapper->getIdentifier();
//Unifiedwayofgetting$node->type,...
$wrapper->getBundle();

Examples(例子)

利用一些wrapper的包装类可以很轻松的获取和设置值。
包装一个实体对象，你可以使用程序化的函数，如下：

$wrapper = entity_metadata_wrapper('node', $node);

或者从Entity API 7.x-1.6之后，你也可以使用Entity::wrapper()。

$wrapper = $entity->wrapper();

但这仅限于如果$entity 对象使用了Entity API模块提供的Entity类的情况下。
wrapper支持使用链式操作来获取实体的属性，例如：获取一个node节点的作者的mail address信息：

$wrapper->author->mail->value();

更新用户的mail address：

$wrapper->author->mail->set('sepp@example.com');

或者也可以这样写：

$wrapper->author->mail = 'sepp@example.com';

wrappers总是返回一个描述性的数据对象，可以通过entity_get_property_info()来从一个wrapper中获取：

$mail_info = $wrapper->author->mail->info();

获取文本的值并进行对应的清理工作可以这样：

$wrapper->title->value(array('sanitize' => TRUE));