sat-suite / support
Shared utilities for the SAT Suite packages: CFDI/Retenciones namespaces, version discovery, XML loading, temporary paths, silent calls (Quietly), UUID and shell execution
Requires
- php: ^8.3
- ext-dom: *
- ext-libxml: *
- ext-simplexml: *
Requires (Dev)
- pestphp/pest: ^3.0
- phpstan/phpstan: ^2.1
- squizlabs/php_codesniffer: ^3.8
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 17:17:37 UTC
README
Utilidades compartidas por los paquetes de sat-suite. No genera ni sella CFDI. Contiene lo siguiente:
- Catálogo de namespaces XML (prefijo, URI y XSD) de CFDI 3.3/4.0 y Retenciones 1.0/2.0, con sus complementos.
- Detección de la versión de un CFDI o de un CFDI de retenciones.
- Carga flexible de XML desde una ruta, una cadena, un
DOMDocumento unSimpleXMLElement. - Rutas temporales, ejecución de comandos de shell y una alternativa al operador
@(Quietly). - Generación de UUID.
Es transversal en el ciclo del CFDI:
sat-suite/cfdi-builderusa los catálogos de namespaces para armar el XML y suxsi:schemaLocation.sat-suite/cfdi-statususa la detección de versión.sat-suite/rfc-blobusaWithTempFileStorageManager,Quietly(para la descarga) ySatSuiteException.
Requisitos
- PHP
^8.3 ext-dom,ext-libxmlyext-simplexmlShellnecesita la funciónproc_openhabilitada.
No tiene dependencias de Composer.
Instalación
composer require sat-suite/support
Uso
Versión de un CFDI o de un CFDI de retenciones
make() acepta una ruta, el contenido XML, un DOMDocument o un SimpleXMLElement.
use SatSuite\Support\ComprobanteVersionDiscovery;
use SatSuite\Support\RetencionVersionDiscovery;
(new ComprobanteVersionDiscovery())->make('/ruta/factura.xml'); // "4.0", "3.3" o "3.2"
(new RetencionVersionDiscovery())->make($xmlRetenciones); // "1.0" o "2.0"
El CFDI 3.2 se reconoce por el atributo version en minúsculas. CFDI 3.3/4.0 y Retenciones usan Version. Si no hay versión, se lanza UnexpectedValueException. Si el XML está vacío o mal formado, se lanza SatSuite\Support\Exceptions\XmlLoadException.
Namespaces de CFDI y Retenciones
Las clases son Comprobante33Namespaces, Comprobante40Namespaces, Retenciones10Namespaces y Retenciones20Namespaces, todas en SatSuite\Support\Namespaces. Cada entrada es [prefijo, uri, xsd], indexada por el nombre del nodo raíz del comprobante o complemento ('Comprobante', 'Pagos', 'Nomina', 'CartaPorte', 'TimbreFiscalDigital', 'Retenciones', 'Dividendos'…).
use SatSuite\Support\Namespaces\Comprobante40Namespaces;
$ns = new Comprobante40Namespaces();
$ns->has('Nomina'); // true
[$prefix, $uri, $xsd] = $ns->get('Pagos');
// 'pago20', 'http://www.sat.gob.mx/Pagos20',
// 'http://www.sat.gob.mx/sitio_internet/cfd/Pagos/Pagos20.xsd'
$ns->get('NoExiste', $default); // $default si no hay entrada
$ns->all(); // catálogo completo
$ns->used(); // sólo las entradas consultadas con get(), útil para armar xsi:schemaLocation
$ns->reset(); // limpia la lista de usadas
$schemaLocation = implode(' ', array_map(fn ($n) => "{$n[1]} {$n[2]}", $ns->used()));
Versiones que refleja el catálogo:
| Clase | Comprobante | Pagos | Comercio Exterior | Otros |
|---|---|---|---|---|
Comprobante40Namespaces | cfd/4 (cfdv40.xsd) | 2.0 (pago20) | 2.0 (cce20) | Nómina 1.2, TFD 1.1, CartaPorte 2.0, ECC 1.2, ConsumoDeCombustibles 1.1, INE 1.1, Donatarias 1.1, Terceros 1.1… |
Comprobante33Namespaces | cfd/3 (cfdv33.xsd) | 1.0 (pago10) | 1.1 (cce11) | Los mismos complementos que 4.0 |
Retenciones10Namespaces | retencionpago/1 | Complementos de retenciones (dividendos, intereses, pagos a extranjeros, plataformas tecnológicas…) y TFD | ||
Retenciones20Namespaces | retencionpago/2 | Ídem |
Todas implementan SatSuite\Support\Contracts\NamespacesContract.
Cargar XML (WithXmlLoader)
Este trait sirve para clases propias:
use SatSuite\Support\Traits\WithXmlLoader;
class MiLector
{
use WithXmlLoader;
}
$lector = new MiLector();
$dom = $lector->getXmlAsDomDocument('/ruta/factura.xml'); // DOMDocument
$sxml = $lector->getXmlAsSimpleXmlElement('<cfdi:Comprobante ... />');
$xml = $lector->getXmlAsString($dom); // string
$lector->getXmlStringFromFile('/ruta/factura.xml'); // sólo rutas
$lector->loadXmlStringAsDomDocument($contenido); // sólo contenido
- Una cadena que empieza con
<(después de espacios o BOM) siempre se trata como contenido XML. En otro caso se intenta leer como archivo local. - Se rechazan las rutas con stream wrapper (
php://,http://,phar:,data:…). - Un XML vacío o mal formado lanza
XmlLoadExceptioncon el mensaje y la línea que reporta libxml.
Rutas temporales (WithTempFileStorageManager)
use SatSuite\Support\Traits\WithTempFileStorageManager;
class MiDescargador
{
use WithTempFileStorageManager;
public function __construct(array $config = [])
{
$this->config = $config; // ['storage' => '/ruta/base'], opcional
}
}
$d = new MiDescargador(['storage' => '/var/tmp/sat']);
$d->getTmpPath('cfdi'); // "/var/tmp/sat/cfdi/" (lo crea con permisos 0775)
$d->getTmpPathForFile('factura.xml'); // "/var/tmp/sat/tmp/factura.xml"
Sin storage se usa sys_get_temp_dir(). Si el directorio no se puede crear, se lanza RuntimeException. Este trait y WithXmlLoader se pueden usar juntos en la misma clase.
Silenciar warnings esperados (Quietly)
Quietly funciona como el operador @, con dos diferencias: el warning no llega al manejador global de errores, así que Laravel, PHPUnit/Pest o Sentry no lo reportan, y el mensaje queda disponible para enriquecer la excepción.
Úsalo sólo cuando el warning no se puede anticipar: una URL que no responde, stream_select() interrumpido por una señal o un mkdir() en carrera con otro proceso. Para archivos locales comprueba antes (is_file(), is_readable(), is_writable()) y llama la función directamente; para libxml usa libxml_use_internal_errors().
use SatSuite\Support\Quietly;
// Los errores de red (DNS, conexión rechazada, TLS) sólo se conocen al intentarlo
$contenido = Quietly::call(fn () => file_get_contents($url, false, $contexto), $error);
if ($contenido === false) {
throw new RuntimeException("No se pudo descargar {$url}: {$error}");
}
No oculta errores fatales, E_USER_ERROR ni E_RECOVERABLE_ERROR, y las excepciones del callback se propagan. Las arrow functions capturan variables por valor: si la llamada escribe en un argumento por referencia ($pipes de proc_open, $read de stream_select), usa function () use (&$var).
Ejecutar comandos (Shell)
use SatSuite\Support\Shell;
use SatSuite\Support\Exceptions\ShellCommandException;
$shell = new Shell();
// Con un arreglo, cada argumento se escapa con escapeshellarg()
$salida = $shell->execute(['openssl', 'x509', '-inform', 'DER', '-in', $cer, '-noout', '-subject']);
// stdin y salida en vivo; el callback recibe cada fragmento de stdout y, al final, ($stderr, true)
$shell->input($xml)
->display(function ($chunk, $isError = false) { /* ... */ })
->execute('xmllint --noout -');
// Sin excepciones: execute() devuelve false y el detalle queda en getError()
$shell->exceptions(false);
if ($shell->execute('comando-que-falla') === false) {
echo $shell->getError();
}
execute() devuelve la salida, true si la salida está vacía o false si falla. Con las excepciones activas (el valor por defecto), un código de salida distinto de 0 lanza ShellCommandException con stderr como mensaje y el código de salida como código. Si proc_open falla, la excepción lleva el código -1. getOutput() y getError() devuelven stdout y stderr de la última ejecución.
UUID
use SatSuite\Support\Uuid;
Uuid::v4(); // aleatorio
Uuid::v1(); // basado en tiempo (requiere enteros de 64 bits)
Uuid::v3('6ba7b810-9dad-11d1-80b4-00c04fd430c8', 'nombre'); // MD5 con namespace
Uuid::v5('6ba7b810-9dad-11d1-80b4-00c04fd430c8', 'nombre'); // SHA-1 con namespace
Uuid::is_valid($uuid); // bool
v3() y v5() devuelven false si el namespace no es un UUID válido.
Excepciones
SatSuite\Support\Exceptions\SatSuiteException es la base de ShellCommandException y XmlLoadException, y otros paquetes de la suite la extienden. Los mensajes están en español.
Notas de comportamiento
- Los dos catálogos de CFDI comparten complementos y sólo difieren en
Comprobante,PagosyComercioExterior. CartaPorte sigue en 2.0 en ambos. - En los catálogos de Retenciones, el XSD del TFD es
http://www.sat.gob.mx/TimbreFiscalDigital/TimbreFiscalDigital.xsd, distinto delTimbreFiscalDigitalv11.xsdde CFDI. Es intencional. get()registra la entrada consultada enused(). Si reutilizas la misma instancia para varios documentos, llama areset()entre uno y otro.
Desarrollo
composer install && npm install # npm instala los hooks de husky (commitlint)
npm test # Pest (suites Unit y Feature)
npm run lint:check # phpcs PSR12 sobre src/
npm run code:scan # phpstan nivel 5
tests/Fixtures/ contiene XML mínimos de CFDI 3.2/3.3/4.0 y Retenciones 1.0/2.0. NamespacesTest compara cada URI con el targetNamespace del XSD en el paquete hermano ../cfdi-assets/resources. Si ese paquete no está, esas pruebas se omiten.
Los commits siguen Conventional Commits. Para publicar una versión, npm run release (o release:patch, release:minor, release:major) actualiza package.json, composer.json y CHANGELOG.md, hace el commit y crea la etiqueta vX.Y.Z. Después se ejecuta git push --follow-tags.
Licencia
MIT. Consulta LICENSE.