PHPackages                             icmbio/validate-upload-registers-from-spreadsheet - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. icmbio/validate-upload-registers-from-spreadsheet

ActiveLibrary[Validation & Sanitization](/categories/validation)

icmbio/validate-upload-registers-from-spreadsheet
=================================================

validate upload registers from spreadsheet

v1.0.7(1w ago)047—0%PHP

Since May 8Pushed 1w agoCompare

[ Source](https://github.com/jotapeicmbio/validade-upload-spreadsheet)[ Packagist](https://packagist.org/packages/icmbio/validate-upload-registers-from-spreadsheet)[ RSS](/packages/icmbio-validate-upload-registers-from-spreadsheet/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (8)Dependencies (12)Versions (9)Used By (0)

Validate Upload Registers from Spreadsheet
==========================================

[](#validate-upload-registers-from-spreadsheet)

Biblioteca PHP para ler planilhas Excel, estruturar linhas repetidas, validar os dados com base em uma definição de formulário, calcular campos derivados, verificar anexos de imagem e gerar XML no formato esperado.

Requisitos
----------

[](#requisitos)

- PHP 8.2+
- `phpoffice/phpspreadsheet`
- `icmbio/validate-xpath-expression`
- `ramsey/uuid`

Instalação
----------

[](#instalação)

```
composer require icmbio/validate-upload-registers-from-spreadsheet
```

Visão geral
-----------

[](#visão-geral)

O pacote cobre o fluxo abaixo:

1. Lê a planilha XLSX.
2. Estrutura blocos repetidos a partir de linhas-modelo.
3. Monta os validadores a partir da definição do formulário.
4. Valida campos obrigatórios, regras XPath, escolhas e tipos.
5. Resolve escolhas dinâmicas.
6. Calcula campos derivados, como `uuid()`.
7. Gera XML final para cada coleta.

Fluxo recomendado
-----------------

[](#fluxo-recomendado)

### 1. Ler e estruturar a planilha

[](#1-ler-e-estruturar-a-planilha)

Use `DataCollectionSpreadsheetReviewPipeline` para carregar a planilha e preparar os dados:

```
use Icmbio\ValidateRegister\DataCollectionSpreadsheetReviewPipeline;

$reviewPipeline = (new DataCollectionSpreadsheetReviewPipeline())
    ->setDataCollection(__DIR__ . '/planilha.xlsx')
    ->validateCollectionFromJson($formDefinition, $dynamicChoices)
    ->validateCollection();

if (! $reviewPipeline->valid()) {
    var_dump($reviewPipeline->errors());
    exit;
}

$collection = $reviewPipeline->process();
```

### 2. Gerar XML

[](#2-gerar-xml)

Depois de validar, use `DataCollectionSpreadsheetConvertPipeline`:

```
use Icmbio\ValidateRegister\DataCollectionSpreadsheetConvertPipeline;

$files = (new DataCollectionSpreadsheetConvertPipeline())
    ->collection($reviewPipeline)
    ->instanceInfo('Nome-da-instancia', '2026.1')
    ->timestamp('2026-04-10T18:01:45.000-03:00')
    ->outputDirectory(__DIR__ . '/xmls')
    ->generate();
```

`generate()` retorna uma lista com os caminhos dos arquivos XML criados.

Exemplo completo
----------------

[](#exemplo-completo)

```
use Icmbio\ValidateRegister\DataCollectionSpreadsheetReviewPipeline;
use Icmbio\ValidateRegister\DataCollectionSpreadsheetConvertPipeline;

$formDefinition = json_decode(file_get_contents(__DIR__ . '/form.json'), true);
$dynamicChoices = [
    'uc' => [
        ['label' => 'Reserva Extrativista do Tapajós', 'name' => 789],
    ],
];

$reviewPipeline = (new DataCollectionSpreadsheetReviewPipeline())
    ->setDataCollection(__DIR__ . '/planilha.xlsx')
    ->validateCollectionFromJson($formDefinition, $dynamicChoices)
    ->validateCollection();

if (! $reviewPipeline->valid()) {
    foreach ($reviewPipeline->errors() as $error) {
        echo $error['message'] . PHP_EOL;
    }
    exit(1);
}

$xmlFiles = (new DataCollectionSpreadsheetConvertPipeline())
    ->collection($reviewPipeline)
    ->instanceInfo('MinhaInstancia', '2026.1')
    ->generate();
```

Definição do formulário
-----------------------

[](#definição-do-formulário)

`CreateValidatorsStructure::build()` converte a árvore do formulário em uma lista de validadores indexada pelo caminho do campo.

```
use Icmbio\ValidateRegister\CreateValidatorsStructure;

$validators = CreateValidatorsStructure::build($formDefinition['children'] ?? [], $dynamicChoices);
```

Os validadores gerados guardam, entre outros dados:

- `type`
- `label`
- `required`
- `required_message`
- `constraint`
- `constraint_message`
- `relevant`
- `calculate`
- `choices`
- `choices_labels`

Leitura da planilha
-------------------

[](#leitura-da-planilha)

`SpreadsheetReader::load($path)` lê a planilha como matriz.

Regras importantes:

- Se existir apenas uma aba, ela será usada automaticamente.
- Se houver mais de uma aba, o pacote tenta usar a aba `Preenchimento`.
- Se a planilha não existir, uma exceção é lançada.

Estruturação de dados
---------------------

[](#estruturação-de-dados)

`StructureSpreadsheetData` transforma uma matriz de worksheet em uma coleção estruturada.

```
use Icmbio\ValidateRegister\Validator\StructureSpreadsheetData;

$structured = (new StructureSpreadsheetData($worksheet))
    ->estruture()
    ->toArray();
```

Isso é útil quando a planilha usa linhas repetidas ou colunas agrupadas por prefixo, como `coletor/nome`.

Validação
---------

[](#validação)

`ValidateCollectionData::createErrorsList()` valida uma coleta já estruturada.

```
use Icmbio\ValidateRegister\ValidateCollectionData;

$errors = ValidateCollectionData::createErrorsList($collection, $validators);
```

O pacote valida, entre outros pontos:

- campos obrigatórios
- expressões XPath de `constraint` e `relevant`
- escolhas válidas
- valores inteiros
- UUIDs gerados para campos `calculate` com `uuid()`

Campos calculados
-----------------

[](#campos-calculados)

`CalculateFields::apply()` executa cálculos declarados nos validadores.

```
use Icmbio\ValidateRegister\CalculateFields;

$collection = CalculateFields::apply($collection, $validators);
```

O caso mais comum é `uuid()`, que gera um UUID v4 para o campo correspondente.

Anexos de foto
--------------

[](#anexos-de-foto)

`PhotoAttachments` ajuda a identificar e validar fotos referenciadas na coleta.

```
use Icmbio\ValidateRegister\PhotoAttachments;

$photos = PhotoAttachments::getPhotosFromCollection($collection, $validators);
$errors = PhotoAttachments::validatePhotos($collection, $validators, $existingPhotos);
```

Geração de XML
--------------

[](#geração-de-xml)

`XformXmlBuilder::build()` gera o XML final.

```
use Icmbio\ValidateRegister\XformXmlBuilder;

$xml = XformXmlBuilder::build(
    $collection,
    array_keys($validators),
    'coleta',
    'coleta_id',
    '2026.1',
    null,
    '2026-04-01T12:00:00.000-03:00',
    $formDefinition,
);
```

Se a definição do formulário for informada, a estrutura do XML segue o formulário. Caso contrário, o pacote usa as chaves recebidas para montar a saída.

Pipeline de conversão
---------------------

[](#pipeline-de-conversão)

`DataCollectionSpreadsheetConvertPipeline` aceita tanto uma coleção pronta quanto o pipeline de revisão:

```
use Icmbio\ValidateRegister\DataCollectionSpreadsheetConvertPipeline;

$files = (new DataCollectionSpreadsheetConvertPipeline())
    ->collection($reviewPipeline)
    ->formInfo($formDefinition)
    ->instanceInfo('MinhaInstancia', '2026.1')
    ->outputDirectory(__DIR__ . '/xmls')
    ->timestamp('2026-04-10T18:01:45.000-03:00')
    ->generate();
```

### Métodos principais

[](#métodos-principais)

- `collection(array|DataCollectionSpreadsheetReviewPipeline $collection)`
- `formInfo(array $formDefinition)`
- `outputDirectory(string $outputDirectory)`
- `instanceInfo(string $instanceName, string|int $instanceVersion = '1')`
- `timestamp(?string $timestamp = null)`
- `generate(): array`

Pipeline de revisão
-------------------

[](#pipeline-de-revisão)

### Métodos principais

[](#métodos-principais-1)

- `setDataCollection(string $path)`
- `transform(string|callable $fn, DataCollectionSelectorKey $selectorKey = DataCollectionSelectorKey::NAME, array $keys = [])`
- `validateCollectionFromJson(array $formDefinition = [], array $dynamicChoices = [])`
- `validateCollection()`
- `process(): array`
- `valid(): bool`
- `errors(): array`

### Transformação de colunas

[](#transformação-de-colunas)

Você pode transformar valores por nome de coluna ou por índice:

```
use Icmbio\ValidateRegister\Enums\DataCollectionSelectorKey;

$reviewPipeline->transform(
    fn ($value) => mb_strtoupper($value),
    DataCollectionSelectorKey::NAME,
    ['estacao_amostral']
);
```

Convenções importantes
----------------------

[](#convenções-importantes)

- Campos com tipo `repeat` são tratados como listas de sub-registros.
- Campos com prefixo `_` são ignorados na geração do XML.
- O campo `meta.instanceID` é preservado quando já existe na entrada.
- Quando não houver `instanceID`, o XML recebe `uuid:...` automaticamente.

Execução dos testes
-------------------

[](#execução-dos-testes)

```
composer test
```

Ou diretamente:

```
vendor/bin/phpunit --colors=always --testdox
```

Licença
-------

[](#licença)

Consulte o repositório do projeto para detalhes de licenciamento.

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance98

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 89.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

8

Last Release

12d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/222866887?v=4)[João Pedro Garcia](/maintainers/jotapeicmbio)[@jotapeicmbio](https://github.com/jotapeicmbio)

---

Top Contributors

[![jotapeicmbio](https://avatars.githubusercontent.com/u/222866887?v=4)](https://github.com/jotapeicmbio "jotapeicmbio (71 commits)")[![jotapegue](https://avatars.githubusercontent.com/u/6393845?v=4)](https://github.com/jotapegue "jotapegue (7 commits)")[![MarcioBastosN](https://avatars.githubusercontent.com/u/10235539?v=4)](https://github.com/MarcioBastosN "MarcioBastosN (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/icmbio-validate-upload-registers-from-spreadsheet/health.svg)

```
[![Health](https://phpackages.com/badges/icmbio-validate-upload-registers-from-spreadsheet/health.svg)](https://phpackages.com/packages/icmbio-validate-upload-registers-from-spreadsheet)
```

###  Alternatives

[craftcms/cms

Craft CMS

3.6k3.6M2.9k](/packages/craftcms-cms)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.4M506](/packages/shopware-core)[yajra/laravel-datatables-export

Laravel DataTables Queued Export Plugin.

352.1M4](/packages/yajra-laravel-datatables-export)[vanilla/garden-schema

A simple data validation and cleaning library based on JSON Schema.

21225.6k7](/packages/vanilla-garden-schema)[2lenet/crudit-bundle

The easy like Crud'it Bundle.

1715.6k12](/packages/2lenet-crudit-bundle)[markocupic/calendar-event-booking-bundle

Contao Calendar Event Booking Bundle

135.1k1](/packages/markocupic-calendar-event-booking-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)