addAttribute()

Introdução

SimpleXML é uma extensão PHP que fornece uma API simples e fácil de usar para trabalhar com documentos XML. A função SimpleXMLElement::addAttribute() é uma das muitas funções que o SimpleXML oferece para trabalhar com documentos XML. É uma ferramenta poderosa que pode ser usada para adicionar atributos a um elemento de um documento XML. Neste artigo, vamos discutir em detalhe a função SimpleXMLElement::addAttribute() e como ela pode ser usada em PHP.

Sintaxe

addAttribute() é um método do objeto SimpleXMLElement. Ele adiciona um atributo ao elemento em que é chamado e não retorna nada (void):

public SimpleXMLElement::addAttribute(
    string $name,
    string $value = "",
    ?string $namespace = null
): void

Como o método muta o elemento no lugar, não é necessário atribuir o resultado a nada — o novo atributo simplesmente aparece no elemento após a chamada.

Exemplo básico

O uso mais comum é adicionar um ou mais atributos a um elemento recém-criado:

Isso cria um elemento <book>, adiciona um atributo isbn a ele e, em seguida, adiciona dois elementos filhos antes de serializar o documento de volta para uma string com asXML(). A saída é:

<?xml version="1.0"?>
<book isbn="123456789"><title>PHP Basics</title><author>John Doe</author></book>

Por que usar addAttribute() em vez da sintaxe de array?

O SimpleXML permite que você leia atributos com a sintaxe de array — $element['isbn'] — e você pode até escrever neles dessa forma. Então, por que addAttribute() existe?

• É a forma documentada de criar um atributo. A sintaxe de escrita por array funciona para alterar um valor que já existe, mas addAttribute() é explícito sobre adicionar um novo.
• Suporta namespaces. A sintaxe de array não consegue anexar um namespace ao atributo que define; o terceiro parâmetro de addAttribute() pode fazer isso.

<?php

$xml = new SimpleXMLElement('<book isbn="123456789"></book>');

// Update an existing attribute (array syntax is fine here):
$xml['isbn'] = '000000000';

// Add a brand-new attribute:
$xml->addAttribute('language', 'en');

echo $xml->asXML();

Adicionando um atributo com namespace

Quando um documento usa namespaces XML, passe o URI do namespace como terceiro argumento. O nome do atributo deve incluir o prefixo ao qual você deseja vinculá-lo:

<?php

$xml = new SimpleXMLElement('<book></book>');
$xml->addAttribute('xml:lang', 'en', 'http://www.w3.org/XML/1998/namespace');

echo $xml->asXML();

Isso produz <book xml:lang="en"/>. Sem o argumento de namespace, o : no nome seria tratado como parte literal do nome do atributo, e não como um prefixo de namespace.

Armadilhas comuns

• Não substitui valores existentes. Chamar addAttribute() com um nome que já existe adiciona um segundo atributo com esse nome, produzindo XML inválido. Para alterar um valor existente, use a sintaxe de escrita por array ($xml['isbn'] = '...').
• Caracteres especiais são escapados automaticamente. Valores como Tom & Jerry são automaticamente codificados para Tom & Jerry na saída, portanto, você não precisa escapá-los manualmente.
• A ordem importa com namespaces. Adicione atributos com namespace após a existência do elemento; não é possível aplicar namespace a um atributo em um elemento que não esteja dentro do escopo daquele namespace sem declará-lo.

<?php

$xml = new SimpleXMLElement('<book></book>');
$xml->addAttribute('isbn', '123 & 456');

echo $xml->asXML(); // <book isbn="123 &amp; 456"/>

Funções relacionadas

• addChild() — adiciona um elemento filho em vez de um atributo.
• asXML() — serializa o SimpleXMLElement de volta para uma string XML.
• attributes() — lê os atributos existentes em um elemento.

Conclusão

SimpleXMLElement::addAttribute() é a forma explícita e consciente de namespaces para adicionar atributos ao construir XML com SimpleXML. Use-o ao criar atributos (especialmente com namespace), e use a sintaxe de escrita por array quando precisar apenas atualizar um valor já existente. Tenha em mente que ele nunca substitui valores existentes e que escapa caracteres especiais automaticamente.

Prática