addAttribute()

Introduction

SimpleXML is a PHP extension that provides a simple and easy-to-use API for working with XML documents. The SimpleXMLElement::addAttribute() function is one of the many functions that SimpleXML provides to work with XML documents. It is a powerful tool that can be used to add attributes to an element in an XML document. In this article, we will be discussing the SimpleXMLElement::addAttribute() function in detail and how it can be used in PHP.

Syntax

addAttribute() is a method on a SimpleXMLElement object. It adds an attribute to the element you call it on and returns nothing (void):

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

Because it mutates the element in place, you don't assign the result to anything — the new attribute simply appears on the element after the call.

Basic example

The most common use is adding one or more attributes to an element you just created:

This creates a <book> element, adds an isbn attribute to it, then adds two child elements before serializing the document back to a string with asXML(). The output is:

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

Why use addAttribute() instead of array syntax?

SimpleXML lets you read attributes with array syntax — $element['isbn'] — and you can even write to them that way. So why does addAttribute() exist?

• It's the documented way to create an attribute. Array-write syntax works for changing a value that already exists, but addAttribute() is explicit about adding a new one.
• It supports namespaces. Array syntax can't attach a namespace to the attribute it sets; the third parameter of addAttribute() can.

<?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();

Adding a namespaced attribute

When a document uses XML namespaces, pass the namespace URI as the third argument. The attribute name should include the prefix you want to bind it to:

<?php

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

echo $xml->asXML();

This produces <book xml:lang="en"/>. Without the namespace argument, the : in the name would be treated as a literal part of the attribute name rather than a namespace prefix.

Common gotchas

• It does not overwrite. Calling addAttribute() with a name that already exists adds a second attribute with that name, producing invalid XML. To change an existing value, use array-write syntax ($xml['isbn'] = '...') instead.
• Special characters are escaped for you. Values like Tom & Jerry are automatically encoded to Tom & Jerry in the output, so you don't escape them yourself.
• Order matters with namespaces. Add namespaced attributes after the element exists; you can't namespace an attribute on an element that isn't in that namespace's scope without declaring it.

<?php

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

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

Related functions

• addChild() — add a child element rather than an attribute.
• asXML() — serialize the SimpleXMLElement back to an XML string.
• attributes() — read the attributes already on an element.

Conclusion

SimpleXMLElement::addAttribute() is the explicit, namespace-aware way to add attributes when building XML with SimpleXML. Reach for it when creating attributes (especially namespaced ones), and use array-write syntax when you only need to update a value that already exists. Keep in mind that it never overwrites and that it escapes special characters automatically.

Practice