Search by

sat-suite / support

xaamin

Shared utilities for the SAT Suite packages: CFDI/Retenciones namespaces, version discovery, XML loading, temporary paths, silent calls (Quietly), UUID and shell execution

Package info

gitlab.com/sat-suite/support

Issues

pkg:composer/sat-suite/support

Statistics

Installs: 2 982

Dependents: 1

Suggesters: 0

Stars: 0

1.0.0 2026-11-14 19:33 UTC

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 DOMDocument o un SimpleXMLElement.
  • 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-builder usa los catálogos de namespaces para armar el XML y su xsi:schemaLocation.
  • sat-suite/cfdi-status usa la detección de versión.
  • sat-suite/rfc-blob usa WithTempFileStorageManager, Quietly (para la descarga) y SatSuiteException.

Requisitos

  • PHP ^8.3
  • ext-dom, ext-libxml y ext-simplexml
  • Shell necesita la función proc_open habilitada.

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:

ClaseComprobantePagosComercio ExteriorOtros
Comprobante40Namespacescfd/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…
Comprobante33Namespacescfd/3 (cfdv33.xsd)1.0 (pago10)1.1 (cce11)Los mismos complementos que 4.0
Retenciones10Namespacesretencionpago/1Complementos de retenciones (dividendos, intereses, pagos a extranjeros, plataformas tecnológicas…) y TFD
Retenciones20Namespacesretencionpago/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 XmlLoadException con 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, Pagos y ComercioExterior. 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 del TimbreFiscalDigitalv11.xsd de CFDI. Es intencional.
  • get() registra la entrada consultada en used(). Si reutilizas la misma instancia para varios documentos, llama a reset() 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.