Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/eclipxe13/CfdiUtils/llms.txt

Use this file to discover all available pages before exploring further.

CfdiUtils is distributed as a Composer package and requires PHP 8.0 or higher. The recommended installation path is through Composer, which handles dependency resolution, autoloading, and enforces the required PHP extension constraints automatically. If your project does not use Composer, a manual workaround is also described below.

​
Requirements

The following PHP extensions are required and must be enabled before installing:
ExtensionPurpose
ext-libxmlXML parsing foundation used across the library
ext-domDOM document creation and manipulation
ext-xslXSLT transformations needed to build the cadena de origen
ext-simplexmlSimple XML reading for quick document access
ext-mbstringMulti-byte string handling for RFC and name fields
ext-opensslCertificate parsing and SHA-256 digital signing
ext-iconvCharacter set conversion for XML encoding
ext-jsonJSON encoding used in utilities and helpers
The following are optional but unlock additional functionality:
Extension / PackageFeature
ext-bcmathPrecise decimal arithmetic for Pagos 2.0 complement totals
ext-soapConsume the SAT CFDI status web service
genkgo/xslAlternative XSLT v2 processor via the Genkgo XSL library
Most PHP installations on Linux, macOS, and Windows already include libxml, dom, simplexml, mbstring, openssl, iconv, and json. You may only need to explicitly enable ext-xsl (on Debian/Ubuntu: sudo apt install php-xml).

​
Install with Composer

Run the following command in your project root: 
composer require eclipxe/cfdiutils
Composer will:
  • Download the latest stable 3.x release.
  • Verify your PHP version is >=8.0.
  • Check that all required extensions are present.
  • Install the two runtime dependencies: eclipxe/xmlresourceretriever and eclipxe/xmlschemavalidator.

​
Install without Composer

If your project does not use Composer, you can install CfdiUtils into a dedicated sub-directory and include only its generated autoloader: 
cd my_project
mkdir cfdiutils
composer require --working-dir=cfdiutils eclipxe/cfdiutils
Then include the generated autoloader at the top of any PHP script that needs the library: 
<?php
require __DIR__ . '/cfdiutils/vendor/autoload.php';
This keeps the library isolated from the rest of your project while still benefiting from Composer’s dependency management.

​
What’s Included

After installation the package is unpacked into vendor/eclipxe/cfdiutils/. The distribution package (what Composer downloads) contains:
PathContents
*.mdLicense and general project files
src/All library source code (autoloaded via PSR-4 as CfdiUtils\)
docs/Full Spanish-language documentation for the project
build/Empty directory; a resources/ sub-directory is created here at runtime to cache XSD, XSLT, and CER files downloaded from the SAT
The build/resources/ path is the default local cache for SAT XML resources. It can be changed by configuring the XmlResolver object — see Configure SAT Resource Cache below.

​
Upgrading from 2.x

Version 3.x was released in March 2025 primarily to ensure compatibility with PHP 8.4. It also removes all previously deprecated code and updates internal dependencies. PHP 7.3 and 7.4 are no longer supported.
Version 3.x contains multiple backward-incompatible changes. Review each section below before upgrading to avoid runtime errors in production code.
Support for PHP 7.3 and 7.4 has been removed. Both versions were end-of-life at the time of the 3.x release (March 2025). The minimum supported PHP version is now 8.0.
The eclipxe/xmlresourceretriever dependency was upgraded from 1.x to 2.x. The root namespace changed from XmlResourceRetriever\ to Eclipxe\XmlResourceRetriever\. Update any direct references in your code accordingly.
On CfdiUtils\PemPrivateKey\PemPrivateKey:
  • isOpened(): bool is removed — use isOpen(): bool instead.
  • isPEM(string $text): bool is removed — use the following replacement:
$openSSL = new \CfdiUtils\OpenSSL\OpenSSL();
return $openSSL->readPemContents($text)->hasPrivateKey();
The SAT CFDI status query component has breaking changes. Consider switching to the dedicated phpcfdi/sat-estado-cfdi package instead.
  • CfdiUtils\ConsultaCfdiSat\Config::DEFAULT_WSDL_URL constant removed — use DEFAULT_SERVICE_URL . '?singleWsdl'.
  • The $wsdlLocation parameter was removed from the Config constructor.
  • All parameters in the StatusResponse constructor are now required (none are optional).
  • Config::getWsdlUrl() removed — use getServiceUrl().
  • Config::getWsdlLocation() and Config::getLocalWsdlLocation() removed.
  • New method WebService::requestExpression(string $expression) added for direct expression queries.
  • Support file ConsultaCFDIServiceSAT.svc.xml removed.
  • CfdiUtils\CadenaOrigen\CadenaOrigenBuilder removed — use CfdiUtils\CadenaOrigen\DOMBuilder.
  • CfdiUtils\CadenaOrigen\CadenaOrigenLocations removed — use CfdiUtils\CadenaOrigen\CfdiDefaultLocations.
  • CfdiUtils\CadenaOrigen\DefaultLocations removed — use CfdiUtils\CadenaOrigen\CfdiDefaultLocations.
getCfdiRelacionados() on the CFDI 3.3 creator helper no longer accepts parameters. Calling it with arguments will cause an error. Update any call sites to use the parameterless form.The multiCfdiRelacionado() method has also been standardized.
Only relevant if you extended or implemented CfdiUtils\Nodes\NodeInterface directly:
  • CfdiUtils\Nodes\NodeInterface\NodeHasValueInterface removed — its methods (value(), setValue()) are now part of NodeInterface directly.
  • New method exists(string $attribute): bool added to NodeInterface.
  • searchNode() return type is now explicitly null|self (was previously undefined).
  • CfdiUtils\Cleaner\Cleaner::removeIncompleteSchemaLocation() removed.
  • CfdiUtils\Cfdi::CFDI_NAMESPACE constant removed — use CFDI_SPECS['3.3'].
  • CfdiUtils\Retenciones\Retenciones::RET_NAMESPACE constant removed — use RET_SPECS['1.0'].
  • CfdiUtils\Certificado\SerialNumber::baseConvert() removed.
  • CfdiUtils\Validate\Cfdi33\Xml\XmlFollowSchema removed — use CfdiUtils\Validate\Xml\XmlFollowSchema.
  • CfdiUtils\Elements\Cfdi33\Helpers\SumasConceptosWriter removed — use CfdiUtils\SumasConceptos\SumasConceptosWriter.
  • CfdiUtils\Elements\Cfdi40\Helpers\SumasConceptosWriter removed — use CfdiUtils\SumasConceptos\SumasConceptosWriter.
  • CfdiUtils\Utils\Crp20277Fixer removed — the class was non-functional and should not have been used.
  • CfdiUtils\Nodes\NodeHasValueInterface removed — methods are now in NodeInterface.
Two new methods were added to QuickReader to make it easier to work with without relying on magic calls:
  • getChildren(string $name = ''): QuickReader[] — returns all child elements, optionally filtered by name.
  • getAttributes(): array<string, string> — returns all attributes as a name-to-value array.
These additions are backward-compatible.

​
Configure SAT Resource Cache

CfdiUtils downloads XSD schema files and XSLT stylesheets from the SAT the first time they are needed, then caches them locally so subsequent calls are fast and offline-capable. By default the cache is stored in vendor/eclipxe/cfdiutils/build/resources/. You can change the cache location by configuring an XmlResolver and passing it to the creator: 
<?php
$xmlResolver = new \CfdiUtils\XmlResolver\XmlResolver('/var/cache/cfdi-resources/');

$creator = new \CfdiUtils\CfdiCreator40(
    $comprobanteAttributes,
    $certificado,
    $xmlResolver
);
To disable local caching entirely and always fetch resources from the network, call setLocalPath('') on the resolver: 
$xmlResolver->setLocalPath('');
For production systems, point the local path to a writable directory outside of vendor/ so the cache survives Composer updates. See the XML Resolver component documentation for the full configuration reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us