README

Biblioteca PHP (nextstage-brasil/ns-util) com utilitários, API REST, filas, cache, sessões, storage, MCP e integrações usadas pelos projetos Nextstage.

Requisitos: PHP 8.1+ (compatível com FPM e Swoole).

Instalação

composer require nextstage-brasil/ns-util

Na aplicação consumidora, aplique as variáveis de ambiente antes de usar a lib:

use NsUtil\EnvFile;

EnvFile::applyEnvVariables(); // ou applyEnvVariables($path)

Opcional: copie o CLI com php nsutil configure (ou o fluxo de configure do pacote) para ter php nsutil na raiz do app.

CLI (php nsutil)

Comandos de fila, cache, migrations, generators (make:router, make:dto, make:queue-handler, etc.) e utilitários. Liste tudo com:

php nsutil list

Testes

Os testes devem rodar dentro do container Docker da aplicação (workdir típico: /var/www/html).

# Suite principal (units)
docker exec -it <container_name> sh -c "cd /var/www/html && ./vendor/bin/phpunit --configuration phpunit.xml --testdox"

# Excluir testes de fila longos (opcional)
docker exec -it <container_name> sh -c "cd /var/www/html && ./vendor/bin/phpunit --configuration phpunit.xml --filter '/^((?!QueueRunTest).)*$/' --testdox"

# Sessões
docker exec -it <container_name> sh -c "cd /var/www/html && ./vendor/bin/phpunit --testdox --testsuite='Session Test Suite'"

# MCP
docker exec -it <container_name> sh -c "cd /var/www/html && ./vendor/bin/phpunit tests/Units/MCP/ --testdox"

# Arquivo ou classe específica
docker exec -it <container_name> sh -c "cd /var/www/html && ./vendor/bin/phpunit tests/Units/HelperTest.php --testdox"
docker exec -it <container_name> sh -c "cd /var/www/html && ./vendor/bin/phpunit tests/Units/CsvQuotedNewlineTest.php --testdox"

Suites definidas em phpunit.xml: Application (units), Swoole, Session. NS_UTIL_TEST_MODE=1 evita exit ao enviar resposta da API nos testes.

Análise estática (PHPStan)

docker exec -it <container_name> sh -c "cd /var/www/html && ./vendor/bin/phpstan analyse"

PHPStan também pode ser exercitado via tests/Units/PhpStanTest.php.

Estrutura

Módulos principais

API e modo MCP

Com $api->setMcpMode(true), getResponseData() formata a saída em JSON-RPC 2.0 via NsUtil\MCP\PrepareOutputRFC e ResponseMcpDTO. O campo id da resposta espelha o id do corpo da requisição JSON-RPC (não o UUID interno da Api). Servidores MCP: estender NsUtil\MCP\Server e registrar classes *Tool / *Prompt.

Helper — arrays e CSV

• arrayOrderBy: ordena por chave (usort); chaves ausentes tratadas como null.
• arrayOrderByUseUASort: mesma lógica preservando as chaves do array (uasort).
• myFGetsCsv / ns_fgetcsv: leitura linha a linha com suporte RFC 4180 — campos entre aspas podem conter quebras de linha literais; linhas extras são lidas até o fechamento do enclosure.
• LoadCSVToArray: detecta delimitador (,, ;, tab), converte XLSX e UTF-8, usa myFGetsCsv; opção firstLineToKeys para associativos.

Exemplo:

use NsUtil\Helper;
use NsUtil\LoadCSVToArray;

$rows = (new LoadCSVToArray('/path/data.csv', true))->run();

Helper::arrayOrderByUseUASort($rows, 'name', 'ASC');

Qualidade

• Suite ampla de testes (units, sessão, Swoole)
• PHPStan no pipeline de qualidade
• Suporte dual FPM e Swoole via abstrações da lib (Redis, conexões, Request, corrotinas)

Manutenção de releases (cherry-pick)

Para levar um commit da linha principal para uma branch de manutenção (ex.: 1.101.x):

git checkout maintenance/1.101
git pull
git cherry-pick <HASH_DO_COMMIT>
# Em caso de conflito: resolver, git add ., git cherry-pick --continue
git push
git tag 1.101.N
git push --tags

Cada projeto fixa a linha desejada no composer.json (1.101.x vs 1.102.x, etc.).

Licença

Apache-2.0 — ver composer.json.