Search by

xaamin / array-analizer

xaamin

Builds a brand new array from a template: reorders keys and removes unknown or empty values

Package info

gitlab.com/xaamin/array-analizer

Issues

pkg:composer/xaamin/array-analizer

Statistics

Installs: 2 612

Dependents: 0

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:09 UTC


README

Builds a brand new PHP array from a template ("key map" or "skeleton"): the result is reordered following the map, keys are matched case-insensitively and returned with the map's canonical name, and, in strict mode, unknown keys and empty values are removed.

Within sat-suite it runs in the pre-stamping stage, right before sat-suite/cfdi-builder: the builder writes nodes in the order of the input array, and the SAT XSD requires a fixed element sequence. The maps have the format of the output/*/input/*.php artifacts generated by sat-suite/cfdi-bones (e.g. output/comprobantes/v40/input/Comprobante.php). Amounts can be adjusted beforehand with sat-suite/delta-fixer. The package itself has no CFDI-specific logic: everything depends on the map you give it.

Requirements

  • PHP ^8.3.
  • Optional: ext-mbstring, for multibyte-safe case-insensitive key matching (e.g. Año / AÑO). Without it, matching falls back to strtolower.

No Composer dependencies.

Installation

composer require xaamin/array-analizer

Usage

Order and clean (strict mode)

use Xaamin\ArrayAnalizer\ArrayBonesAnalizer;

$analizer = new ArrayBonesAnalizer([
    'Version', 'Serie', 'Folio',
    'Emisor' => ['Rfc', 'Nombre', 'RegimenFiscal'],
    'Conceptos' => ['Concepto' => ['ClaveProdServ', 'Cantidad', 'Descripcion', 'Importe']],
]);

$data = $analizer->clean([
    'conceptos' => ['Concepto' => [
        ['Importe' => '100.00', 'Descripcion' => 'Producto A', 'Cantidad' => '1', 'ClaveProdServ' => '01010101'],
        ['Importe' => '50.00', 'Descripcion' => '', 'cantidad' => '2', 'Unknown' => 'x'],
    ]],
    'EMISOR' => ['Nombre' => 'ESCUELA KEMPER URGATE', 'Rfc' => 'EKU9003173C9'],
    'Folio' => null,
    'Serie' => '',
    'Version' => '4.0',
    'Extra' => 'dropped',
]);

// [
//     'Version' => '4.0',
//     'Emisor' => ['Rfc' => 'EKU9003173C9', 'Nombre' => 'ESCUELA KEMPER URGATE'],
//     'Conceptos' => ['Concepto' => [
//         ['ClaveProdServ' => '01010101', 'Cantidad' => '1', 'Descripcion' => 'Producto A', 'Importe' => '100.00'],
//         ['Cantidad' => '2', 'Importe' => '50.00'],
//     ]],
// ]

Order only (non-strict mode)

With $strict = false the result contains every key of the map, in order; missing keys are null.

$analizer->clean(['version' => '4.0', 'Extra' => 'x'], false);

// ['Version' => '4.0', 'Serie' => null, 'Folio' => null, 'Emisor' => null, 'Conceptos' => null]

Using a cfdi-bones skeleton

$keys = require '/path/to/cfdi-bones/output/comprobantes/v40/input/Comprobante.php';

$analizer = new ArrayBonesAnalizer($keys);              // or ->setKeys($keys)
$analizer->setExtensionNodes(['Complemento', 'Addenda']); // optional, returns $this

$data = $analizer->clean(['Comprobante' => $input]);

Complements and addenda are only kept if their skeleton is part of the map, e.g. by merging it: $keys['Comprobante']['Complemento'] = require '/path/to/cfdi-bones/output/comprobantes/v40/input/complemento/Pagos.php';.

Extension nodes

Empty sub-arrays are normally removed in strict mode. Direct children of the nodes passed to setExtensionNodes() are kept even when empty:

$analizer = (new ArrayBonesAnalizer(['Complemento' => ['Pagos' => []]]))
    ->setExtensionNodes(['Complemento']);

$analizer->clean(['Complemento' => ['Pagos' => []]]); // ['Complemento' => ['Pagos' => []]]

Invalid input

If the data has a non-empty scalar where the map expects a node (or a scalar item inside a list of nodes), clean() throws Xaamin\ArrayAnalizer\Exceptions\InvalidNodeException (extends InvalidArgumentException); getPath() returns the dot path of the node:

use Xaamin\ArrayAnalizer\Exceptions\InvalidNodeException;

try {
    $analizer->clean(['Conceptos' => ['Concepto' => [['Importe' => '1'], 'oops']]]);
} catch (InvalidNodeException $e) {
    $e->getPath();    // 'Conceptos.Concepto.1'
    $e->getMessage(); // 'The node "Conceptos.Concepto.1" must be an array, scalar value given.'
}

API

ArrayBonesAnalizer implements Xaamin\ArrayAnalizer\Contracts\ArrayAnalizerContract:

MethodDescription
__construct(array $keys = [])Creates the analizer with a map.
setKeys(array $keys) / getKeys()Sets / returns the map.
setExtensionNodes(array $extensions) / getExtensionNodes()Nodes whose empty children are preserved. setExtensionNodes() returns $this.
clean(array $data, $strict = true)Returns the ordered (and, if strict, cleaned) array.

Behaviour notes

  • Keys not in the map are always dropped, even with $strict = false, because the result is built from the map, not from the data.
  • Keys are matched case-insensitively and returned with the map's name. On case-insensitive duplicates in the input, the first key wins.
  • In strict mode only null, '' and whitespace-only strings are considered empty: false, 0 and '0' are kept. Empty nodes are removed (except direct children of extension nodes); an extension node that ends up empty itself is still removed.
  • Lists of nodes ('Concepto' => [[...], [...]]) are ordered and cleaned item by item with the node's map and reindexed. Lists of scalars are returned as they are.
  • The exemption of setExtensionNodes() only covers empty sub-arrays; scalars inside those nodes are still filtered by the map and by emptiness.
  • The package registers global helper functions (string_to_lowercase, array_get, array_is_associative, array_is_associative_values) guarded by function_exists: if your project already defines one of them (e.g. old Laravel's array_get), that version is used. Note that array_is_associative_values() returns true when the array is a list; the name is kept for backwards compatibility.
  • "analizer" (sic) is part of the package name and namespace.

Development

composer install && npm install   # npm install sets up the husky commit-msg hook (commitlint)
npm test                          # Pest (or: composer test)
npm run lint:check                # phpcs PSR12 on src/ (npm run lint:fix to fix)
npm run code:scan                 # phpstan level 5

Releases use release-it: npm run release[:patch|:minor|:major] bumps package.json and composer.json, updates CHANGELOG.md, commits and tags vX.Y.Z (no push); then git push --follow-tags. Commit messages follow Conventional Commits.

License

MIT. See LICENSE.