ApiProblem

ApiProblem

Esta biblioteca proporciona una implementación sencilla y directa de los detalles del problema del IETF para las API HTTP, RFC 9457.

RFC 9457 es una especificación simple para formatear respuestas de error de API RESTful en la web. Esta biblioteca proporciona una forma sencilla y cómoda de interactuar con esa especificación. Admite la generación y análisis de mensajes RFC 9457, tanto en variantes JSON como XML.

Generando respuestas

¿Qué es eso que dices? ¿Alguien envió a su API una solicitud incorrecta? ¡Diles que es un 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.

O, mejor aún, puede subclasificar ApiProblem para un tipo de problema específico (ya que se supone que el tipo y el título van juntos y son relativamente fijos), luego simplemente complete sus propios datos específicos del error. ¡Es como extender una excepción!

Si está utilizando una biblioteca o marco que desea realizar su propia serialización JSON, también es totalmente compatible. ApiProblem implementa JsonSerializable , por lo que puedes pasarlo directamente a json_encode() como si fuera una matriz desnuda.

 $ response = new MyFrameworksJsonResponse ( $ problem );

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

Envío de respuestas

Probablemente estés usando PSR-7 para tus respuestas. Es por eso que esta biblioteca incluye una utilidad para convertir su objeto ApiProblem en un objeto ResponseInterface PSR-7, utilizando una fábrica PSR-17 de su elección. Así:

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

Eso devuelve un objeto de respuesta completamente funcional y marcado, listo para enviar al cliente.

Recibir respuestas

¿Está enviando mensajes a una API que responde con errores de problema de API? ¡Ningún problema! Puedes manejar fácilmente esa respuesta de esta manera:

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.

(¡También funciona para fromXml()!)

Instalación

Instale ApiProblem como cualquier otro paquete de Composer:

 composer require crell/api-problem

Consulte la documentación de Composer para obtener más detalles.

Seguridad

Si descubre algún problema relacionado con la seguridad, utilice el formulario de informes de seguridad de GitHub en lugar de la cola de problemas.

Créditos

• [Larry Garfield][enlace-autor]
• [Todos los contribuyentes][enlace-colaboradores]

Licencia

Esta biblioteca se publica bajo la licencia MIT. En resumen, "deje intacta la declaración de derechos de autor; de lo contrario, diviértase". Consulte LICENCIA para obtener más información.

Contribuyendo

¡Se aceptan solicitudes de extracción! El objetivo es la total conformidad con las especificaciones del IETF.