ApiProblem

ApiProblem

Cette bibliothèque fournit une implémentation simple et directe des détails du problème IETF pour les API HTTP, RFC 9457.

La RFC 9457 est une spécification simple pour le formatage des réponses d'erreur des API RESTful sur le Web. Cette bibliothèque fournit un moyen simple et pratique d'interagir avec cette spécification. Il prend en charge la génération et l'analyse des messages RFC 9457, dans les variantes JSON et XML.

Générer des réponses

Qu'est-ce que tu dis ? Quelqu'un a envoyé une mauvaise requête à votre API ? Dites-leur que c'est un problème !

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, mieux encore, vous pouvez sous-classer ApiProblem pour un type de problème spécifique (puisque le type et le titre sont censés aller de pair et être relativement fixes), puis remplir simplement vos propres données spécifiques à l'erreur. Tout comme étendre une exception !

Si vous utilisez une bibliothèque ou un framework qui souhaite effectuer sa propre sérialisation JSON, celle-ci est également entièrement prise en charge. ApiProblem implémente JsonSerializable , vous pouvez donc le transmettre directement à json_encode() comme s'il s'agissait d'un tableau nu.

 $ response = new MyFrameworksJsonResponse ( $ problem );

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

Envoi de réponses

Vous utilisez probablement PSR-7 pour vos réponses. C'est pourquoi cette bibliothèque inclut un utilitaire pour convertir votre objet ApiProblem en un objet ResponseInterface PSR-7, en utilisant une usine PSR-17 de votre choix. Comme ça :

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 );

Cela renvoie un objet Response entièrement fonctionnel et marqué, prêt à être renvoyé au client.

Recevoir des réponses

Envoyez-vous des messages à une API qui répond avec des erreurs API-Problem ? Aucun problème! Vous pouvez facilement gérer cette réponse comme ceci :

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.

(Cela fonctionne aussi pour fromXml() !)

Installation

Installez ApiProblem comme n'importe quel autre package Composer :

 composer require crell/api-problem

Consultez la documentation de Composer pour plus de détails.

Sécurité

Si vous découvrez des problèmes liés à la sécurité, veuillez utiliser le formulaire de rapport de sécurité GitHub plutôt que la file d'attente des problèmes.

Crédits

• [Larry Garfield][lien-auteur]
• [Tous les contributeurs][lien-contributeurs]

Licence

Cette bibliothèque est publiée sous licence MIT. En bref, "laissez la déclaration de droit d'auteur intacte, sinon amusez-vous". Voir LICENCE pour plus d’informations.

Contribuer

Demandes de tirage acceptées ! L'objectif est une conformité totale avec la spécification IETF.