Qual é o objetivo da função entity_metadata_wrapper () e por que devo usá-la?

Parece que estou desenvolvendo complementos para muitos módulos que usam a API de entidade no momento, e a entity_metadata_wrapper()função continua aparecendo.

A página de documentos diz o seguinte:

Retorna um invólucro de propriedade para os dados fornecidos.

Se uma entidade for quebrada, o wrapper poderá ser usado para recuperar outros wrappers para as propriedades de entidade.

Ignorando a grafia maravilhosamente freudiana da palavra "entidade", não entendo realmente qual é o objetivo desses invólucros.

Eu entendo que a função essencialmente retorna uma EntityDrupalWrapperclasse:

O wrapper facilita a aplicação de retornos de chamada getter e setter de propriedades da entidade

Mas o que não consigo entender é como isso facilita as coisas.

Por exemplo, para atualizar a propriedade status de um nó, eu poderia usar este código:

$node = node_load($nid);
$node->status = 1;
node_save($node);

Isso é bem limpo. Pelo que entendi (mas pode estar errado) o código equivalente usando entity_metadata_wrapper()seria mais detalhado do que isso.

Não tenho certeza se é simplesmente o uso do termo 'wrapper' que está me atrapalhando aqui, mas também examinei o código no módulo Entity e não estou nem perto de entendê-lo.

Alguém é capaz de explicar quais são os benefícios do uso dessa função e talvez fornecer um exemplo de código simples para um caso de uso comum?

Sim, alterar o status de um nó é trivial, pois é uma propriedade codificada.

Os campos, por outro lado, são muito mais complicados. Eles estão aninhados em três níveis de profundidade, enquanto houver field_get_items () para obtê-los no idioma correto, não existe essa função para definir valores de campo. Portanto, você sempre precisa verificar se um campo é traduzível ou não e precisa saber qual propriedade contém exatamente os valores que você está procurando / deseja definir.

Dois exemplos, que mostram o que o wrapper de entidade pode fazer:

• A linha a seguir adiciona o item de linha comercial ao pedido, cuidando do idioma e da propriedade real que contém o ID de referência, retirado da resposta a seguir /drupal//a/23513/31

  $order_wrapper->commerce_line_items[] = $line_item;

• De maneira semelhante, ser capaz de acessar diretamente o valor de um campo, sem precisar verificar o idioma ou o delta, mesmo sendo capaz de acessar diretamente as entidades referenciadas, obtidas em /drupal//a/ 33010/31

  $subnode = entity_metadata_wrapper('node', $node)->field_subnode->value();
  $default = $subnode->title;

O wrapper de entidade é a força motriz por trás de módulos flexíveis e poderosos, como a API de pesquisa e as regras , pois permite que eles trabalhem em vários níveis de referências, para que você possa, por exemplo, acessar um campo do produto que um usuário comprou em um pedido com algo como [commerce-order:commerce-line-items:0:commerce-product:some-field](pode não estar realmente correto, mas algo assim) ou adicione o resumo do corpo de um nó referenciado ao seu índice de pesquisa.

Dito isto, não gosto necessariamente da API real do wrapper, são enormes matrizes internas e que mesmo propriedades simples são novamente classes de wrapper. Espero que o sistema aprimorado de entidade (e, esperançosamente, em campo) no Drupal 8 remova a necessidade de um invólucro desse tipo, graças à classificação de entidades.