xaamin / array-analizer
Builds a brand new array from a template: reorders keys and removes unknown or empty values
Requires
- php: ^8.3
Requires (Dev)
- pestphp/pest: ^3.0
- phpstan/phpstan: ^2.1
- squizlabs/php_codesniffer: ^3.8
Suggests
- ext-mbstring: Multibyte-safe case-insensitive key matching
Provides
None
Conflicts
None
Replaces
None
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 tostrtolower.
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:
| Method | Description |
|---|---|
__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,0and'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 byfunction_exists: if your project already defines one of them (e.g. old Laravel'sarray_get), that version is used. Note thatarray_is_associative_values()returnstruewhen 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.