Tutoriais

jsonW no PHP: como ler num site com FFI

O SDK de PHP do jsonW usa FFI e as classes Leitor e Escritor do namespace JsonW. Veja o exemplo oficial, a ordem de busca da biblioteca e a gravação.

Por Equipe Wortic 7 min de leitura

Em PHP, o SDK do jsonW fica em sdk/php, no arquivo jsonw.php, e chama a biblioteca libjsonw pelo FFI do PHP. O arquivo define as classes Leitor e Escritor do namespace JsonW. Para ler, crie o Leitor com o caminho do arquivo, indexe o campo e chame chave. O llms.txt do repositório fala em PHP 8.4 ou mais novo.

Antes do código, vale situar o formato. Segundo a página oficial do jsonW, ele reúne três formas sem perda (linha, coluna e texto), 19 recursos e está na versão 1.4.1. Para um site em PHP, a vantagem é ler só as colunas e linhas pedidas, sem carregar o arquivo inteiro na memória.

O que é o FFI e por que o SDK usa?

O FFI é o recurso do PHP que permite chamar uma biblioteca em C sem escrever uma extensão em C. O README dos SDKs lista o SDK PHP como uma chamada por FFI. Isso exige que o FFI esteja disponível no seu PHP, então confira a configuração do ambiente antes de implantar.

Como a libjsonw é uma biblioteca em C, o SDK a carrega em tempo de execução, e não na hora de instalar o site. Isso deixa o código PHP simples, mas coloca a responsabilidade de achar a biblioteca no ambiente de execução.

Como rodar o exemplo de leitura?

O exemplo oficial, em sdk/php/exemplo.php, recebe o arquivo, o campo e o valor, e imprime as linhas que batem. O cabeçalho mostra o comando:

php exemplo.php dados.jsw id 2

A parte central do exemplo, sem a checagem inicial do campo, usa o require do SDK e depois as chamadas da classe Leitor:

require __DIR__ . '/jsonw.php';
if ($modo !== '--varrer') $a->indexar($campo);
foreach ($a->chave($campo, json_decode($texto, true)) as $i) echo $a->json($i)

O valor vem da linha de comando e passa por json_decode, como no SDK de Python. Assim, um número sai como número e um texto precisa vir como texto JSON. O exemplo indexa o campo pelo nome, e a opção --varrer, quando presente, pula a indexação.

Como gravar sem deixar o arquivo pela metade?

Pelo README dos SDKs, o Escritor cria o arquivo com criar, recebe linhas com gravar e publica no fechar. Só fechar publica, e a regra vale para todas as linguagens. Quem sai por erro no meio da gravação deve chamar abandonar, que fecha sem publicar e deixa o destino como estava.

No caso de um site, isso significa que uma exportação interrompida não substitui o arquivo que já estava no lugar. O destino continua com a versão anterior, e a nova só aparece quando a gravação termina e o fechamento acontece.

Como usar Composer, Laravel e WordPress?

O repositório traz o arquivo sdk/php/composer.json, para instalar o SDK com o Composer. Há também um plugin para WordPress dentro de sdk/php/wordpress. O llms.txt do repositório cita Composer, Laravel e WordPress como ambientes do SDK PHP, e isso vale como indicação, não como garantia de cada versão.

Antes de instalar em produção, confira a versão publicada. O llms.txt ainda cita a 1.3.14, e a página oficial traz a 1.4.1. Se o plugin do WordPress trouxer uma cópia antiga da biblioteca, o site vai usar a cópia antiga, então compare as versões.

Por que indexar antes de buscar?

Sem índice, a busca varre o arquivo. O README principal mede isso com 1 milhão de linhas: 142,8 ms de mediana varrendo, contra 0,196 ms com o índice, que leva 193 ms para ser montado. Em PHP, a chamada indexar fica no leitor, e o exemplo do SDK só a faz quando a opção --varrer não aparece.

Que tipos o jsonW guarda?

O JSON tem poucos tipos, e o jsonW acrescenta outros que fazem diferença em sistemas de venda e cadastro. O README principal lista decimal exato, que nunca passa por ponto flutuante, dinheiro com a moeda ISO 4217 em cada valor, medida convertida na gravação, código guardado byte a byte e tempo em microssegundos UTC. Segundo a página oficial, dinheiro, medida, decimal exato e código já vêm no formato, conferidos ao gravar.

Para PHP, há um ponto prático: o leitor aceita tanto 1.234,56 quanto 1,234.56, sem depender do locale do processo. Isso evita um erro comum com números escritos no padrão brasileiro.

Quais mensagens e códigos de saída o exemplo usa?

O exemplo em PHP não tem uma mensagem de uso como o de C. Ele confere se o campo existe na lista de campos e, se não existe, escreve campo, o nome e não existe na saída de erro, saindo com código 1. Esse é o único erro que o próprio exemplo trata. Para os demais, como um arquivo que não abre, o README dos SDKs não lista a mensagem exata de cada linguagem, então teste o caminho de erro no seu ambiente antes de publicar.

Quando usar o SDK de PHP e quando não usar?

Use o SDK quando a aplicação em PHP precisa ler colunas e linhas de um arquivo jsonW e o FFI está disponível no servidor. Para guardar, analisar dados em lote e alimentar sistemas de IA, o README principal diz que o jsonW pode substituir o JSON, mas nas respostas HTTP você pode manter JSON, porque todo documento JSON válido é jsonW-texto válido. Não use o SDK só para entregar um JSON que já existe. O formato traz ganho quando há busca, tipos de negócio ou conferência de integridade, e isso precisa existir no seu caso.

Quais limites considerar em PHP?

  • Versão do PHP: o llms.txt fala em PHP 8.4 ou mais novo, enquanto o README dos SDKs fala em PHP 8. Teste na versão que você vai implantar.
  • FFI: o recurso precisa estar habilitado no PHP do servidor.
  • Biblioteca: a ordem de busca é JSONW_LIB, o diretório do SDK, o diretório sdk e o diretório bin da plataforma.

Para usar o formato com APIs da Wortic, a página para desenvolvedores traz as APIs abertas de CNPJ e CEP, com a documentação. O conector para Claude e ChatGPT está em Use a Wortic dentro do Claude e do ChatGPT, e os planos estão em wortic.com.br/planos. O código público do jsonW está em github.com/developer-wortic/jsonw.

A Wortic, empresa brasileira, criou e mantém o jsonW. A licença é a Sustainable Use, do modelo fair-code, que permite usar o formato dentro dos seus produtos, sem permitir a revenda do jsonW como serviço.

Perguntas frequentes

O que é o SDK em PHP 8.4+?

É o arquivo sdk/php/jsonw.php, que usa FFI para chamar a libjsonw e define as classes Leitor e Escritor do namespace JsonW. O llms.txt do repositório fala em PHP 8.4 ou mais novo. O SDK serve a Composer, Laravel e WordPress.

Como usar o SDK em PHP 8.4+ na prática?

Instale o SDK com o Composer ou copie o arquivo jsonw.php para o projeto. Crie o Leitor com o caminho do arquivo, indexe o campo com indexar e busque com chave. Para cada linha, use json. O exemplo oficial roda com php exemplo.php dados.jsw id 2.

Quais são os limites do SDK em PHP 8.4+?

O FFI precisa estar habilitado no PHP, e a biblioteca precisa ser encontrada na ordem de busca do SDK. O llms.txt cita a 1.3.14 e a página oficial informa a 1.4.1, então confira a versão antes de implantar.

Fontes

Conheça: jsonW em PHP 8.

Quer isso funcionando na sua empresa?

Um consultor da Wortic olha o seu caso e mostra o caminho, sem compromisso.

Falar com um consultor

Equipe editorial

Equipe editorial da Wortic especializada em automacao, IA, ERP, CRM e crescimento operacional.

  • Automacao com IA
  • Gestao empresarial
  • CRM
  • ERP
  • Marketing digital

Isso funcionando no seu negócio.

Um consultor mostra o sistema do seu ramo, com a IA dentro.