ApiProblem

ApiProblem

Esta biblioteca fornece uma implementação simples e direta dos Detalhes do Problema IETF para APIs HTTP, RFC 9457.

RFC 9457 é uma especificação simples para formatar respostas de erro de APIs RESTful na web. Esta biblioteca fornece uma maneira simples e conveniente de interagir com essa especificação. Ele suporta a geração e análise de mensagens RFC 9457, nas variantes JSON e XML.

Gerando respostas

O que é isso que você diz? Alguém enviou uma solicitação incorreta à sua API? Diga a eles que é um problema!

ApiProblem ; $problem = new ApiProblem ("You do not have enough credit.", "http://example.com/probs/out-of-credit"); // Defined properties in the API have their own setter methods. $problem ->setDetail("Your current balance is 30, but that costs 50.") ->setInstance("http://example.net/account/12345/msgs/abc"); // But you can also support any arbitrary extended properties! $problem['balance'] = 30; $problem['accounts'] = [ "http://example.net/account/12345", "http://example.net/account/67890" ]; $json_string = $problem->asJson(); // Now send that JSON string as a response along with the appropriate HTTP error // code and content type which is available via ApiProblem ::CONTENT_TYPE_JSON. // Also check out asXml() and ApiProblem ::CONTENT_TYPE_XML for the angle-bracket fans in the room.">

 use Crell  ApiProblem  ApiProblem ;

$ problem = new ApiProblem ( " You do not have enough credit. " , " http://example.com/probs/out-of-credit " );
// Defined properties in the API have their own setter methods.
$ problem
  -> setDetail ( " Your current balance is 30, but that costs 50. " )
  -> setInstance ( " http://example.net/account/12345/msgs/abc " );
// But you can also support any arbitrary extended properties!
$ problem [ ' balance ' ] = 30 ;
$ problem [ ' accounts ' ] = [
  " http://example.net/account/12345 " ,
  " http://example.net/account/67890 "
];

$ json_string = $ problem -> asJson ();

// Now send that JSON string as a response along with the appropriate HTTP error
// code and content type which is available via ApiProblem ::CONTENT_TYPE_JSON.
// Also check out asXml() and ApiProblem ::CONTENT_TYPE_XML for the angle-bracket fans in the room.

Ou, melhor ainda, você pode criar uma subclasse ApiProblem para um tipo de problema específico (já que o tipo e o título devem andar juntos e ser relativamente fixos) e, em seguida, preencher seus próprios dados específicos de erro. Assim como estender uma exceção!

Se você estiver usando uma biblioteca ou estrutura que deseja fazer sua própria serialização JSON, isso também terá suporte total. ApiProblem implementa JsonSerializable , então você pode passá-lo diretamente para json_encode() como se fosse um array simples.

 $ response = new MyFrameworksJsonResponse ( $ problem );

// Or do it yourself
$ body = json_encode ( $ problem );

Enviando respostas

Você provavelmente está usando o PSR-7 para suas respostas. É por isso que esta biblioteca inclui um utilitário para converter seu objeto ApiProblem em um objeto ResponseInterface PSR-7, usando uma fábrica PSR-17 de sua escolha. Assim:

ApiProblemHttpConverter; $factory = getResponseFactoryFromSomewhere(); // The second parameter says whether to pretty-print the output. $converter = new HttpConverter($factory, true); $response = $converter->toJsonResponse($problem); // or $response = $converter->toXmlResponse($problem);">

 use Crell  ApiProblem  HttpConverter ;

$ factory = getResponseFactoryFromSomewhere ();

// The second parameter says whether to pretty-print the output.
$ converter = new HttpConverter ( $ factory , true );

$ response = $ converter -> toJsonResponse ( $ problem );
// or
$ response = $ converter -> toXmlResponse ( $ problem );

Isso retorna um objeto Response totalmente funcional e marcado, pronto para ser enviado de volta ao cliente.

Recebendo respostas

Você está enviando mensagens para uma API que está respondendo com erros de problema de API? Sem problemas! Você pode facilmente lidar com essa resposta assim:

ApiProblem ; $problem = ApiProblem ::fromJson($some_json_string); $title = $problem->getTitle(); $type = $problem->getType(); // Great, now we know what went wrong, so we can figure out what to do about it.">

 use Crell  ApiProblem  ApiProblem ;

$ problem = ApiProblem :: fromJson ( $ some_json_string );
$ title = $ problem -> getTitle ();
$ type = $ problem -> getType ();
// Great, now we know what went wrong, so we can figure out what to do about it.

(Funciona também para fromXml()!)

Instalação

Instale ApiProblem como qualquer outro pacote do Composer:

 composer require crell/api-problem

Veja a documentação do Composer para mais detalhes.

Segurança

Se você descobrir algum problema relacionado à segurança, use o formulário de relatório de segurança do GitHub em vez da fila de problemas.

Créditos

• [Larry Garfield][autor do link]
• [Todos os contribuidores][contribuidores do link]

Licença

Esta biblioteca é lançada sob a licença do MIT. Resumindo, “deixe a declaração de direitos autorais intacta, caso contrário divirta-se”. Consulte LICENÇA para obter mais informações.

Contribuindo

Solicitações pull aceitas! O objetivo é a conformidade total com as especificações IETF.