Elements: Typed CFDI Node Classes for 3.3 and 4.0

The CfdiUtils\Elements namespace contains a set of typed PHP classes — called elements — that wrap the generic Node data structure with named, version-aware methods for building valid CFDI documents. Instead of manually creating child nodes and remembering element names, you call methods like addEmisor(), addConcepto(), or addTraslado() and the element manages the XML hierarchy for you. Every element is a node. All methods and properties of NodeInterface — array-style attribute access, child iteration, search helpers — are available on every element. The Elements layer simply adds a typed API on top.

Difference Between Nodes and Elements

Aspect	`CfdiUtils\Nodes\Node`	`CfdiUtils\Elements\*`
Purpose	Generic in-memory XML tree	Typed structure matching the CFDI specification
Child creation	`addChild(new Node(...))`	`addEmisor([...])`, `addConcepto([...])` etc.
Attribute access	`$node['Attr']`	`$element['Attr']` (same — it’s still a Node)
Element ordering	Manual `setOrder()`	Defined in `getChildrenOrder()` automatically
Fixed attributes	None	`getFixedAttributes()` pre-populates namespace declarations
Version awareness	None	Separate class tree per CFDI version

Every element class implements CfdiUtils\Elements\Common\ElementInterface, which extends NodeInterface with:

getElementName()

string

Returns the qualified XML element name, e.g. cfdi:Comprobante.

getFixedAttributes()

array

Returns attributes that are always pre-set when the element is constructed, such as xmlns:cfdi namespace declarations on the root Comprobante.

getChildrenOrder()

array

Returns the ordered list of child element names that the SAT specification requires, used to automatically sort children when they are added.

CFDI 4.0 Elements

Namespace: CfdiUtils\Elements\Cfdi40 The CFDI 4.0 element tree mirrors the structure defined in the SAT Anexo 20 for version 4.0.

Class	Element name	Role
`Comprobante`	`cfdi:Comprobante`	Root element; provides `addEmisor`, `addReceptor`, `addConcepto`, `addImpuestos`, `addComplemento`, `addAddenda`
`Emisor`	`cfdi:Emisor`	Issuer information
`Receptor`	`cfdi:Receptor`	Recipient information
`InformacionGlobal`	`cfdi:InformacionGlobal`	Global information for simplified invoices
`CfdiRelacionados`	`cfdi:CfdiRelacionados`	Container for related CFDI references
`CfdiRelacionado`	`cfdi:CfdiRelacionado`	A single related CFDI UUID
`Conceptos`	`cfdi:Conceptos`	Container for line items
`Concepto`	`cfdi:Concepto`	A single invoice line item
`Impuestos`	`cfdi:Impuestos`	Tax summary at comprobante or concepto level
`Traslado`	`cfdi:Traslado`	Transferred tax (IVA, IEPS, etc.)
`Retencion`	`cfdi:Retencion`	Withheld tax (ISR, IVA)
`Complemento`	`cfdi:Complemento`	Container for SAT-defined complements
`Addenda`	`cfdi:Addenda`	Container for free-form addenda

CFDI 3.3 Elements

Namespace: CfdiUtils\Elements\Cfdi33 The CFDI 3.3 element tree provides the same structural pattern as 4.0 but targeting the prior version of the specification. The class names are identical (Comprobante, Emisor, Receptor, Conceptos, Concepto, etc.) — only the namespace and getFixedAttributes() differ. Switch from Cfdi33 to Cfdi40 by changing the import namespace.

Complement Elements

CfdiUtils ships typed element classes for many SAT-defined complements. Each complement namespace follows the same get* / add* / multi* pattern.

Complement	Namespace	Root class
Nómina 1.2	`CfdiUtils\Elements\Nomina12`	`Nomina`
Carta Porte 3.0	`CfdiUtils\Elements\CartaPorte30`	`CartaPorte`
Carta Porte 3.1	`CfdiUtils\Elements\CartaPorte31`	`CartaPorte`
Comercio Exterior 2.0	`CfdiUtils\Elements\Cce20`	`ComercioExterior`
Pagos 2.0	`CfdiUtils\Elements\Pagos20`	`Pagos`
Pagos 1.0	`CfdiUtils\Elements\Pagos10`	`Pagos`
Retenciones 2.0	`CfdiUtils\Elements\Retenciones20`	`Retenciones`
Timbre Fiscal Digital 1.1	`CfdiUtils\Elements\Tfd11`	`TimbreFiscalDigital`

Naming Conventions

Elements follow a consistent three-prefix naming convention.

get* prefix — obtain a singleton child

ElementoPadre::getElementoHijo(): ElementoHijo returns the single child instance of that type. If it does not exist yet, it is created and added automatically before being returned.Use get* when the specification allows at most one child of a given type (e.g., there can only be one Emisor inside a Comprobante).

<?php
use CfdiUtils\Elements\Cfdi40\Comprobante;

$comprobante = new Comprobante();
$emisor = $comprobante->getEmisor(); // creates it if absent, always returns same instance
$emisor['Rfc'] = 'EKU9003173C9';

add* prefix — add attributes to a singleton, or create a new child

ElementoPadre::addElementoHijo(array $attributes): ElementoHijoFor singleton children (e.g., Emisor): merges $attributes into the existing (or newly created) child and returns it.For repeatable children (e.g., Concepto): creates a brand-new instance with $attributes, appends it to the parent, and returns the new instance.

<?php
// Singleton: addEmisor updates the one Emisor
$comprobante->addEmisor(['Rfc' => 'EKU9003173C9', 'RegimenFiscal' => '601']);

// Repeatable: addConcepto creates a new Concepto each time
$concepto = $comprobante->addConcepto([
    'Descripcion'    => 'Desarrollo de software',
    'ValorUnitario'  => '10000.00',
    'Cantidad'       => '1',
    'ClaveUnidad'    => 'E48',
    'ClaveProdServ'  => '81112100',
]);

multi* prefix — add multiple children in one call

ElementoPadre::multiElementoHijo(array ...$elementAttributes): ElementoPadreCreates one child per argument array, adds each to the parent, and returns the parent for method chaining. This is equivalent to calling the corresponding add* method multiple times.

<?php
$cfdiRelacionados->multiCfdiRelacionado(
    ['UUID' => 'uuid-1-...'],
    ['UUID' => 'uuid-2-...'],
);

Usage Pattern: Building a CFDI 4.0 Document

The example below shows how elements chain together to build the core structure of a CFDI 4.0 invoice.

<?php
use CfdiUtils\Elements\Cfdi40\Comprobante;

$comprobante = new Comprobante([
    'Version'     => '4.0',
    'Fecha'       => '2024-01-15T10:00:00',
    'SubTotal'    => '10000.00',
    'Total'       => '11600.00',
    'Moneda'      => 'MXN',
    'TipoDeComprobante' => 'I',
]);

// Add issuer (singleton — only one Emisor allowed)
$comprobante->addEmisor([
    'Rfc'          => 'EKU9003173C9',
    'Nombre'       => 'ESCUELA KEMPER URGATE',
    'RegimenFiscal'=> '601',
]);

// Add recipient (singleton)
$comprobante->addReceptor([
    'Rfc'                    => 'COSC8001137NA',
    'Nombre'                 => 'CARLOS CORTES SOTO',
    'DomicilioFiscalReceptor'=> '06600',
    'RegimenFiscalReceptor'  => '605',
    'UsoCFDI'                => 'G03',
]);

// Add a line item (repeatable)
$concepto = $comprobante->addConcepto([
    'ClaveProdServ'  => '81112100',
    'Cantidad'       => '1',
    'ClaveUnidad'    => 'E48',
    'Descripcion'    => 'Desarrollo de software',
    'ValorUnitario'  => '10000.00',
    'Importe'        => '10000.00',
    'ObjetoImp'      => '02',
]);

// Add IVA to the line item
$concepto->addImpuestos()->addTraslados()->addTraslado([
    'Base'          => '10000.00',
    'Impuesto'      => '002',
    'TipoFactor'    => 'Tasa',
    'TasaOCuota'    => '0.160000',
    'Importe'       => '1600.00',
]);

// Add tax totals to the Comprobante
$comprobante->addImpuestos([
    'TotalImpuestosTrasladados' => '1600.00',
])->addTraslados()->addTraslado([
    'Impuesto'      => '002',
    'TipoFactor'    => 'Tasa',
    'TasaOCuota'    => '0.160000',
    'Importe'       => '1600.00',
    'Base'          => '10000.00',
]);

You rarely need to instantiate Comprobante directly. Use CfdiUtils\CfdiCreator40 instead — it creates a Comprobante for you, wires up the XmlResolver and XsltBuilder, and exposes buildCadenaDeOrigen() and addSello() convenience methods.

Getting Started

Reading CFDI

Creating CFDI

Validating CFDI

Core Components

Utilities

Elements: Typed CFDI Node Classes for 3.3 and 4.0

Difference Between Nodes and Elements

CFDI 4.0 Elements

CFDI 3.3 Elements

Complement Elements

Naming Conventions

Usage Pattern: Building a CFDI 4.0 Document

Build docs developers (and LLMs) love

Getting Started

Reading CFDI

Creating CFDI

Validating CFDI

Core Components

Utilities

Documentation Index

​Difference Between Nodes and Elements

​CFDI 4.0 Elements

​CFDI 3.3 Elements

​Complement Elements

​Naming Conventions

​Usage Pattern: Building a CFDI 4.0 Document

Build docs developers (and LLMs) love

Difference Between Nodes and Elements

CFDI 4.0 Elements

CFDI 3.3 Elements

Complement Elements

Naming Conventions

Usage Pattern: Building a CFDI 4.0 Document