Writer
extends XMLWriter
in package
Uses
ContextStackTrait
The XML Writer class.
This class works exactly as PHP's built-in XMLWriter, with a few additions.
Namespaces can be registered beforehand, globally. When the first element is written, namespaces will automatically be declared.
The writeAttribute, startElement and writeElement can now take a clark-notation element name (example: {http://www.w3.org/2005/Atom}link).
If, when writing the namespace is a known one a prefix will automatically be selected, otherwise a random prefix will be generated.
Instead of standard string values, the writer can take Element classes (as defined by this library) to delegate the serialization.
The write() method can take array structures to quickly write out simple xml trees.
Tags
Table of Contents
- $classMap : array<string|int, mixed>
- This is a list of custom serializers for specific classes.
- $contextUri : string|null
- A contextUri pointing to the document being parsed / written.
- $elementMap : array<string|int, mixed>
- This is the element map. It contains a list of XML elements (in clark notation) as keys and PHP class names as values.
- $namespaceMap : array<string|int, mixed>
- This is a list of namespaces that you want to give default prefixes.
- $adhocNamespaces : array<string|int, mixed>
- Any namespace that the writer is asked to write, will be added here.
- $contextStack : array<string|int, mixed>
- Backups of previous contexts.
- $namespacesWritten : bool
- When the first element is written, this flag is set to true.
- popContext() : mixed
- Restore the previous "context".
- pushContext() : mixed
- Create a new "context".
- startElement() : bool
- Opens a new element.
- write() : mixed
- Writes a value to the output stream.
- writeAttribute() : bool
- Writes a new attribute.
- writeAttributes() : mixed
- Writes a list of attributes.
- writeElement() : bool
- Write a full element tag and it's contents.
Properties
$classMap
This is a list of custom serializers for specific classes.
public
array<string|int, mixed>
$classMap
= []
The writer may use this if you attempt to serialize an object with a class that does not implement XmlSerializable.
Instead it will look at this classmap to see if there is a custom serializer here. This is useful if you don't want your value objects to be responsible for serializing themselves.
The keys in this classmap need to be fully qualified PHP class names, the values must be callbacks. The callbacks take two arguments. The writer class, and the value that must be written.
function (Writer $writer, object $value)
$contextUri
A contextUri pointing to the document being parsed / written.
public
string|null
$contextUri
This uri may be used to resolve relative urls that may appear in the document.
The reader and writer don't use this property, but as it's an extremely common use-case for parsing XML documents, it's added here as a convenience.
$elementMap
This is the element map. It contains a list of XML elements (in clark notation) as keys and PHP class names as values.
public
array<string|int, mixed>
$elementMap
= []
The PHP class names must implement Sabre\Xml\Element.
Values may also be a callable. In that case the function will be called directly.
$namespaceMap
This is a list of namespaces that you want to give default prefixes.
public
array<string|int, mixed>
$namespaceMap
= []
You must make sure you create this entire list before starting to write. They should be registered on the root element.
$adhocNamespaces
Any namespace that the writer is asked to write, will be added here.
protected
array<string|int, mixed>
$adhocNamespaces
= []
Any of these elements will get a new namespace definition every single time they are used, but this array allows the writer to make sure that the prefixes are consistent anyway.
$contextStack
Backups of previous contexts.
protected
array<string|int, mixed>
$contextStack
= []
$namespacesWritten
When the first element is written, this flag is set to true.
protected
bool
$namespacesWritten
= false
This ensures that the namespaces in the namespaces map are only written once.
Methods
popContext()
Restore the previous "context".
public
popContext() : mixed
Return values
mixed —pushContext()
Create a new "context".
public
pushContext() : mixed
This allows you to safely modify the elementMap, contextUri or namespaceMap. After you're done, you can restore the old data again with popContext.
Return values
mixed —startElement()
Opens a new element.
public
startElement(string $name) : bool
You can either just use a local elementname, or you can use clark- notation to start a new element.
Example:
$writer->startElement('{http://www.w3.org/2005/Atom}entry');
Would result in something like:
<entry xmlns="http://w3.org/2005/Atom">
Note: this function doesn't have the string typehint, because PHP's XMLWriter::startElement doesn't either.
Parameters
- $name : string
Return values
bool —write()
Writes a value to the output stream.
public
write(mixed $value) : mixed
The following values are supported:
- Scalar values will be written as-is, as text.
- Null values will be skipped (resulting in a short xml tag).
- If a value is an instance of an Element class, writing will be delegated to the object.
- If a value is an array, two formats are supported.
Array format 1: [ "{namespace}name1" => "..", "{namespace}name2" => "..", ]
One element will be created for each key in this array. The values of this array support any format this method supports (this method is called recursively).
Array format 2:
[ [ "name" => "{namespace}name1" "value" => "..", "attributes" => [ "attr" => "attribute value", ] ], [ "name" => "{namespace}name1" "value" => "..", "attributes" => [ "attr" => "attribute value", ] ] ]
Parameters
- $value : mixed
Return values
mixed —writeAttribute()
Writes a new attribute.
public
writeAttribute(string $name, string $value) : bool
The name may be specified in clark-notation.
Returns true when successful.
Note: this function doesn't have typehints, because for some reason PHP's XMLWriter::writeAttribute doesn't either.
Parameters
- $name : string
- $value : string
Return values
bool —writeAttributes()
Writes a list of attributes.
public
writeAttributes(array<string|int, mixed> $attributes) : mixed
Attributes are specified as a key->value array.
The key is an attribute name. If the key is a 'localName', the current xml namespace is assumed. If it's a 'clark notation key', this namespace will be used instead.
Parameters
- $attributes : array<string|int, mixed>
Return values
mixed —writeElement()
Write a full element tag and it's contents.
public
writeElement(mixed $name[, array<string|int, mixed>|string|object|null $content = null ]) : bool
This method automatically closes the element as well.
The element name may be specified in clark-notation.
Examples:
$writer->writeElement('{http://www.w3.org/2005/Atom}author',null);
becomes:
$writer->writeElement('{http://www.w3.org/2005/Atom}author', [
'{http://www.w3.org/2005/Atom}name' => 'Evert Pot',
]);
becomes:
Note: this function doesn't have the string typehint, because PHP's XMLWriter::startElement doesn't either.
Parameters
- $name : mixed
- $content : array<string|int, mixed>|string|object|null = null