nextstage-brasil/ns-util

Metodos e classes de utilidades diversas

2.20.1 2026-06-02 18:52 UTC

Requires

• php: ^8.1
• firebase/php-jwt: >=7.0.2 <8.0
• laravel/serializable-closure: ^1.3 || ^2
• league/flysystem: ^3.0
• league/flysystem-aws-s3-v3: ^3.0
• nelexa/zip: ^3.3 || ^4.0
• phpmailer/phpmailer: ^6.9
• predis/predis: ^2.3
• sendgrid/sendgrid: ^7 || ^8
• smottt/wideimage: ^1.1

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpunit/phpunit: ^10 || ^11

Apache-2.0

• Nextstage

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

Caminho	Conteúdo
src/	Código da biblioteca
src/MCP/	Servidor e cliente MCP (ver src/MCP/README.md)
tests/Units/	Testes unitários
tests/Session/	Testes de sessão (Redis, Swoole, FPM)
tests/Swoole/	Testes específicos Swoole
tests/docs/queue-testing-guide.md	Guia de testes de fila
phpunit.xml	Configuração PHPUnit
phpstan.neon	Configuração PHPStan
AGENTS.md	Orientações para agentes/IA no repositório

Módulos principais

Módulo	Descrição
Helper (NsUtil\Helper)	Utilitários estáticos (traits: string, array, arquivo, compatibilidade)
Api / Request	REST, rate limit, entrada unificada FPM/Swoole
MCP	JSON-RPC 2.0 via Server, Tool, Prompt, Client — documentação
Cache	CacheFactory — drivers Redis, SQLite, PostgreSQL
Queue	Handlers PostgreSQL, CLI queue:*
Redis	Cliente com retry (usar só NsUtil\Services\Redis)
Connection	ConnectionFactory (pool, Swoole) e PostgreSQL/SQLite
Storage	Flysystem (local, S3, Samba, GCP, FileHaus)
Session	Gerenciamento FPM/Swoole — src/Sessions/README.md
DTOs	AbstractDTO + FactoryTrait
LoadCSVToArray / PgLoadCSV	Importação CSV/XLSX e carga em PostgreSQL
Crypto, Date, Log, Validate, Template, Minify	Utilitários diversos

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.