Como trabalhar com JSON em PHP

JSON é um dos formatos de serialização de dados mais comumente usados. Ele cresceu de suas origens no JavaScript (JSON significa JavaScript Object Notation) para se tornar o formato de escolha para muitas APIs da web e sistemas de configuração.

PHP vem com suporte JSON embutido. Historicamente, os recursos eram fornecidos como uma extensão separada. O lançamento do PHP 8.0 em 2020 converteu o JSON em uma extensão permanentemente ativa que não pode ser removida.

Leitura de dados JSON

Para analisar dados JSON, use a função json_decode (). Sua assinatura completa é a seguinte:

json_decode & # 40; string $ json, bool | null $ associative = null, int $ depth = 512, int $ flags = 0 & # 41 ;: mixed;

A invocação mais simples é passar uma string JSON sem outros argumentos. Iremos trabalhar com {"foo": "bar"} que decodifica para uma instância da stdClass genérica do PHP. Nosso novo objeto terá uma propriedade foo com o valor de bar.

Se você preferir receber um array associativo, passe true para o parâmetro $ associative de json_decode (). O exemplo acima seria então decodificado para ["foo" = > "bar"].

O parâmetro $ depth permite que você controle o nível máximo de aninhamento para analisar. Você obterá nulo se o JSON se aninhar mais profundamente do que o nível definido – nenhuma tentativa será feita para analisar os dados.

O parâmetro $ flags aceita uma máscara de bits de sinalizadores opcionais que alteram o comportamento de análise. Eles são descritos em detalhes no manual do PHP e permitem definir como tipos de dados específicos devem ser tratados.

Tratamento de erros de análise

Por padrão, json_decode () retornará nulo quando for transmitida uma string JSON inválida. Isso apresenta um problema porque um nulo isolado é uma string JSON válida. Você não tem como saber se o valor de retorno nulo se deve ao JSON que contém nulo ou porque o JSON foi malformado e não pôde ser analisado.

O PHP 7.3 finalmente resolveu este problema antigo adicionando o sinalizador JSON_THROW_ON_ERROR. Passe esta constante para o parâmetro $ flags de json_decode () para fazer o PHP lançar uma exceção quando um JSON inválido for encontrado:

json_decode & # 40; " ['json malformado ", verdadeiro, 512, JSON_THROW_ON_ERROR & # 41 ;;

Habilitar esse comportamento é geralmente desejável, mas torna a invocação um tanto difícil. Você pode usar os argumentos nomeados do PHP 8 para simplificar um pouco as coisas, pois você não precisará passar valores explícitos para os parâmetros opcionais:

json_decode & # 40; json: " ['json malformado & quot ;, sinalizadores: JSON_THROW_ON_ERROR & # 41 ;;

Os dois exemplos mostrados acima são equivalentes um ao outro. A única diferença é que a última sintaxe requer PHP 8.

Serializando dados para JSON

Você pode serializar valores PHP em strings JSON usando a função json_encode (). Sua assinatura é a seguinte:

json_encode & # 40; mixed $ value, int $ flags = 0, int $ depth = 512 & # 41 ;: string | false;

PHP aceita qualquer valor como $ value, exceto para recursos. Os tipos de dados são manipulados automaticamente para garantir que tenham um mapeamento apropriado no JSON gerado. Objetos PHP e matrizes associativas se tornarão objetos JSON contendo todos os pares de propriedade / valor-chave enumeráveis ​​do valor de entrada. Os tipos escalares de PHP são mapeados diretamente para JSON sem transformação.

Como sua contraparte de decodificação, json_encode () aceita $ flags e $ depth parâmetros. No entanto, tome cuidado com o pedido – em uma peculiaridade da biblioteca padrão do PHP, a posição desses dois parâmetros opcionais é trocada em comparação com json_decode ().

Muitos mais sinalizadores são suportados ao codificar dados. Aqui estão algumas que você deve estar ciente:

• JSON_FORCE_OBJECT – Converta matrizes numéricas de PHP em objetos JSON em vez de matrizes. Isso lida com o caso em que uma variável contém uma matriz associativa que pode estar vazia. Quando a matriz está vazia ([]), uma matriz JSON é criada; quando ele não está vazio (["foo" = > "bar"]), um objeto é emitido. Habilitar este sinalizador garante que um objeto seja sempre usado no JSON codificado.
• JSON_PRETTY_PRINT – A saída JSON do PHP normalmente é minimizada, o que é ideal ao enviá-la pela rede como parte de uma solicitação HTTP. Definir este sinalizador adicionará novos caracteres de linha e recuo automático à string JSON, tornando-o mais adequado para arquivos de configuração e outros cenários onde humanos irão ler a saída.
• JSON_PRESERVE_ZERO_FRACTION – Força o PHP a codificar floats exatamente como 0.0, em vez de cortar a fração para escrever 0 no JSON (que pode ser interpretado incorretamente como um inteiro).
• JSON_NUMERIC_CHECK – Converte automaticamente strings numéricas em números na saída JSON, em vez de preservá-los como strings. Com isso habilitado, um valor PHP "234.5" será emitido como 234.5 no JSON.
• JSON_PARTIAL_OUTPUT_ON_ERROR – Tente continuar a escrever mesmo depois de encontrar um erro de codificação. O PHP tentará substituir valores inválidos para produzir alguma saída, mesmo que não esteja completo.

Você pode obter a lista completa de sinalizadores na documentação do PHP. O restante são opções principalmente específicas para personalizar a codificação usada em cenários específicos.

Trazendo JSON para a camada de domínio do seu aplicativo

Back-ends complexos da web são mais propensos a usar os recursos JSON do PHP no contexto de emissão de respostas HTTP. Isso provavelmente significa que você codificará instâncias de classes de camada de domínio, como BlogPost.

Chamar json_encode () com uma instância de uma classe resulta em uma string JSON contendo um único objeto. O PHP enumera as propriedades públicas da classe e as adiciona como pares de chave / valor ao objeto codificado em JSON.

class BlogPost & # 123; protected int $ Id = 1; public string $ Title = " Exemplo & quot ;; & # 125;   // produz '{" Título & quot ;: " Exemplo "}' $ json = json_encode & # 40; new BlogPost & # 40; & # 41; & # 41 ;;

O PHP não pode acessar automaticamente propriedades protegidas ou privadas. Essa implementação padrão é, portanto, insuficiente para todas as classes, exceto as mais simples. Em vez disso, suas classes podem implementar a interface JsonSerializable. Isso permite que você defina como as instâncias serão transformadas em JSON.

JsonSerializable define um único método, jsonSerialize (), que o PHP chamará sempre que uma instância precisar ser serializada para JSON:

a classe BlogPost implementa JsonSerializable & # 123; protected int $ Id = 1; public string $ Title = " Exemplo & quot ;;   publicfunction jsonSerialize & # 40; & # 41; & # 123; return & # 91; " Id " = > $ this- > Id, " Title " = > $ this- > Title & # 93 ;; & # 125; & # 125;   // produz '{" Id & quot ;: 1, " Título & quot ;: " Exemplo "}' $ json = json_encode & # 40; new BlogPost & # 40; & # 41; & # 41 ;;

A implementação de JsonSerializable permite que você controle o processo de serialização. Suas instâncias podem escolher o que expor, o que pode incluir propriedades protegidas, valores calculados dinamicamente e dados retornados de chamadas de método.

Você nem mesmo precisa retornar uma matriz. A assinatura do método jsonSerializable especifica um tipo de retorno misto, portanto, você pode fornecer qualquer valor que o PHP possa serializar para JSON. Você pode retornar outro objeto para que o PHP o serialize recursivamente.