Download the PHP package carlos-veizaga/xml-flow without Composer

XmlFlow

A fluent PHP library for building well-formed XML documents, validating them against XSD schemas, and signing them with RSA-SHA256 digital signatures — purpose-built for electronic invoicing systems and any integration that demands strict schema compliance.

Features

• Fluent builder — chainable API from root declaration to final XML string
• Native xsi:nil support — emit <field xsi:nil="true"/> for absent but schema-required fields
• Root element attributes — set any attribute on the root element (e.g. xsi:noNamespaceSchemaLocation) without string manipulation
• Multi-driver architecture — swap rendering backends without touching application code
• XSD validation — validate against any schema with a structured error report
• XMLDSig signing — enveloped RSA-SHA256 signatures via a dedicated, decoupled XmlSigner
• Sequential array collections — arrays of items automatically repeat the parent tag
• Precision-safe decimal formatting — asDecimal(n) serializes strings without float conversion; transform() lets you bring your own arithmetic (BCMath, GMP, etc.)

Requirements

• PHP 8.2+
• Extensions: ext-dom, ext-xmlwriter, ext-openssl

Installation

Basic usage

Output:

Power features

Root element attributes — ->attributes()

Some schemas require attributes on the root element that are not namespace declarations — for example xsi:noNamespaceSchemaLocation. Use ->attributes() to set them directly on the builder:

Multiple calls to ->attributes() are merged, consistent with ->namespaces().

Null fields — Node::nil()

Some XSD schemas require absent fields to appear explicitly with xsi:nil="true" rather than being omitted. XmlFlow handles this natively.

Note: The xsi namespace must be declared via ->namespaces(). XmlFlow does not inject it automatically — neither driver does.

Elements with custom attributes and text content use Node::create():

Decimal precision — asDecimal() and transform()

PHP silently drops decimal places when casting numbers to strings — (string) 150.0 produces '150', not '150.00'. If your XSD field is xs:decimal, this causes validation failures. asDecimal() fixes it:

value() accepts string, int, or float. The precision defaults to 2 if omitted.

String values — no float conversion

When value() receives a string, asDecimal() normalizes decimal places via string operations — no (float) cast. This is safe for values that exceed IEEE 754 double precision (e.g. amounts from a BCMath-based SDK):

Custom arithmetic — transform(callable)

For rounding, BCMath, GMP, or any other arithmetic strategy, use transform(). The callable receives the raw value and returns the final string. It takes full precedence over asDecimal().

XSD validation

validate() returns $this, so it composes naturally in the chain. It throws XsdValidationException with the raw LibXMLError[] list on failure.

Digital signing — XMLDSig RSA-SHA256

The signature is inserted as the last child of the root element, as required by enveloped XMLDSig. The <ds:Signature> node declares xmlns:ds explicitly to satisfy strict schema validators.

Note: XmlSigner accepts any XML string — it is not coupled to XmlFlow. You can sign documents generated by other means.

High-volume generation — useStreamMode()

For batch jobs generating thousands of documents, switch to the StreamDriver. It uses PHP's XMLWriter extension and keeps memory usage O(1) regardless of document size.

When to use each driver:

Scenario	Driver
XMLDSig digital signing	DomDriver (default) — signing requires DOM node access
XSD validation via ->validate()	DomDriver (default)
Batch / high-volume generation (no signing)	StreamDriver via ->useStreamMode()

Switching drivers is transparent — both implement XmlDriverInterface and produce semantically identical output.

Architecture

XmlFlow follows SOLID principles throughout:

• Strategy pattern — XmlDriverInterface decouples the rendering backend from the builder. Implement it to add a custom driver without modifying any existing class.
• Value Object — Node is immutable by convention; it carries no identity, only data.
• Decoupled signing — XmlSigner depends on robrichards/xmlseclibs and is entirely separate from the builder. Applications that do not need signing do not pay any cost for it.

Running the tests

The suite covers the builder, Node semantics, driver parity (DomDriver vs StreamDriver), and cryptographic signature verification.

License

MIT © Carlos Veizaga