Rasgo de respuesta API

Gran parte del desarrollo PHP moderno requiere la creación de API, ya sea simplemente para proporcionar datos para un entorno con mucho javascript. aplicación de una sola página o como un producto independiente. Higgs proporciona un rasgo de respuesta API que puede ser Se utiliza con cualquier controlador para simplificar los tipos de respuesta comunes, sin necesidad de recordar qué código de estado HTTP. se debe devolver para qué tipos de respuesta.

Uso de ejemplo 

El siguiente ejemplo muestra un patrón de uso común dentro de sus controladores.

<?php

namespace App\Controllers;

use Higgs\API\ResponseTrait;
use Higgs\Controller;

class Users extends Controller
{
    use ResponseTrait;

    public function createUser()
    {
        $model = new UserModel();
        $user  = $model->save($this->request->getPost());

        // Respond with 201 status code
        return $this->respondCreated();
    }
}

En este ejemplo, se devuelve un código de estado HTTP de 201, con el mensaje de estado genérico «Creado». Métodos existen para los casos de uso más comunes:

<?php

// Generic response method
$this->respond($data, 200);

// Generic failure response
$this->fail($errors, 400);

// Item created response
$this->respondCreated($data);

// Item successfully deleted
$this->respondDeleted($data);

// Command executed by no response required
$this->respondNoContent($message);

// Client isn't authorized
$this->failUnauthorized($description);

// Forbidden action
$this->failForbidden($description);

// Resource Not Found
$this->failNotFound($description);

// Data did not validate
$this->failValidationError($description);

// Resource already exists
$this->failResourceExists($description);

// Resource previously deleted
$this->failResourceGone($description);

// Client made too many requests
$this->failTooManyRequests($description);

Manejo de tipos de respuesta 

Cuando pasa sus datos en cualquiera de estos métodos, ellos determinarán el tipo de datos para formatear los resultados según los siguientes criterios:

Si los datos son una cadena, se tratarán como HTML para enviarlos al cliente.
Si los datos son una matriz, se formatearán de acuerdo con el valor $this->format del controlador. Si eso está vacío, Intentará negociar el tipo de contenido con lo que el cliente solicitó, por defecto en JSON. si no se ha especificado nada más dentro de Config/Format.php, la propiedad $supportedResponseFormats.

Para definir el formateador que se utiliza, edite Config/Format.php. $supportedResponseFormats contiene una lista de tipos de mime para los que su aplicación puede formatear automáticamente la respuesta. Por defecto, el sistema sabe cómo formatee las respuestas XML y JSON:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Format extends BaseConfig
{
    public $supportedResponseFormats = [
        'application/json',
        'application/xml',
    ];

    // ...
}

Esta es la matriz que se utiliza durante Negociación de contenido para determinar cuál tipo de respuesta a devolver. Si no se encuentran coincidencias entre lo que el cliente solicitó y lo que usted apoya, la primera El formato en esta matriz es lo que se devolverá.

A continuación, debe definir la clase que se utiliza para formatear la matriz de datos. Esta debe ser una clase totalmente calificada. nombre, y la clase debe implementar Higgs\Format\FormatterInterface. Los formateadores salen de la caja que admite JSON y XML:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Format extends BaseConfig
{
    public $formatters = [
        'application/json' => \Higgs\Format\JSONFormatter::class,
        'application/xml'  => \Higgs\Format\XMLFormatter::class,
    ];

    // ...
}

Por lo tanto, si su solicitud solicita datos con formato JSON en un encabezado Aceptar, la matriz de datos que pasa cualquiera de los Los métodos respond* o fail* serán formateados por la clase Higgs\Format\JSONFormatter. La resultante Los datos JSON se enviarán de vuelta al cliente.

Referencia de clase 

setResponseFormat($format)

Parámetros:

$format (string) – El tipo de respuesta a devolver, ya sea json o xml

Esto define el formato que se utilizará al formatear matrices en las respuestas. Si proporciona un valor «nulo» para $formato, se determinará automáticamente mediante la negociación de contenido.

<?php

return $this->setResponseFormat('json')->respond(['error' => false]);

respond($data[, $statusCode = 200[, $message = '']])

Parámetros:

$data (mixed) – Los datos a devolver al cliente. Ya sea cadena o matriz.
$statusCode (int) – el código de estado HTTP que se devolverá. El valor predeterminado es 200
$message (string) – un mensaje personalizado de «motivo» para devolver.

Este es el método utilizado por todos los demás métodos de este rasgo para devolver una respuesta al cliente.

El elemento $data puede ser una cadena o una matriz. De forma predeterminada, se devolverá una cadena como HTML, mientras que una matriz se ejecutará a través de json_encode y se devolverá como JSON, a menos que Negociación de contenido determina que debe devolverse en un formato diferente.

Si se pasa una cadena $message, se usará en lugar de los códigos de motivo estándar de la IANA para el estado de respuesta. Sin embargo, no todos los clientes respetarán los códigos personalizados y utilizarán los estándares de la IANA. que coincidan con el código de estado.

Nota

Since it sets the status code and body on the active Response instance, this should always ser el método final en la ejecución del script.

fail($messages[, int $status = 400[, string $code = null[, string $message = '']]])

Parámetros:

$messages (mixed) – una cadena o conjunto de cadenas que contienen mensajes de error encontrados.
$status (int) – el código de estado HTTP que se devolverá. El valor predeterminado es 400.
$code (string) – un código de error personalizado, específico de API.
$message (string) – un mensaje personalizado de «motivo» para devolver.

Devuelve:

una respuesta de varias partes en el formato preferido del cliente.

Es el método genérico utilizado para representar una respuesta fallida y lo utilizan todos los demás métodos «fallidos».

El elemento $messages puede ser una cadena o una matriz de cadenas.

El parámetro $status es el código de estado HTTP que debe devolverse.

Dado que muchas API funcionan mejor utilizando códigos de error personalizados, se puede pasar un código de error personalizado en el tercer parámetro. Si no hay ningún valor presente, será lo mismo que $status.

Si se pasa una cadena $message, se usará en lugar de los códigos de motivo estándar de la IANA para el estado de respuesta. Sin embargo, no todos los clientes respetarán los códigos personalizados y utilizarán los estándares de la IANA. que coincidan con el código de estado.

La respuesta es una matriz con dos elementos: error y mensajes. El elemento error contiene el estado código del error. El elemento messages contiene una serie de mensajes de error. Se vería algo como:

<?php

$response = [
    'status'   => 400,
    'code'     => '321a',
    'messages' => [
        'Error message 1',
        'Error message 2',
    ],
];

respondCreated($data = null[, string $message = ''])

Parámetros:

$data (mixed) – Los datos a devolver al cliente. Ya sea cadena o matriz.
$message (string) – un mensaje personalizado de «motivo» para devolver.

Devuelve:

El valor del método send() del objeto Respuesta.

Establece el código de estado apropiado que se usará cuando se crea un nuevo recurso, generalmente 201:

<?php

$user = $userModel->insert($data);

return $this->respondCreated($user);

respondDeleted($data = null[, string $message = ''])

Parámetros:

$data (mixed) – Los datos a devolver al cliente. Ya sea cadena o matriz.
$message (string) – un mensaje personalizado de «motivo» para devolver.

Devuelve:

El valor del método send() del objeto Respuesta.

Establece el código de estado apropiado que se usará cuando se eliminó un nuevo recurso como resultado de esta llamada API, generalmente 200.

<?php

$user = $userModel->delete($id);

return $this->respondDeleted(['id' => $id]);

respondNoContent(string $message = 'No Content')

Parámetros:

$message (string) – un mensaje personalizado de «motivo» para devolver.

Devuelve:

El valor del método send() del objeto Respuesta.

Establece el código de estado apropiado para usar cuando el servidor ejecutó exitosamente un comando pero no hay ningún respuesta significativa para enviar al cliente, normalmente 204.

<?php

sleep(1);

return $this->respondNoContent();

failUnauthorized(string $description = 'Unauthorized'[, string $code = null[, string $message = '']])

Parámetros:

$descripción (string) – el mensaje de error que se mostrará al usuario.
$code (string) – un código de error personalizado, específico de API.
$message (string) – un mensaje personalizado de «motivo» para devolver.

Devuelve:

El valor del método send() del objeto Respuesta.

Establece el código de estado apropiado para usar cuando el usuario no ha sido autorizado, o tiene autorización incorrecta. El código de estado es 401.

<?php

return $this->failUnauthorized('Invalid Auth token');

failForbidden(string $description = 'Forbidden'[, string $code=null[, string $message = '']])

Parámetros:

$descripción (string) – el mensaje de error que se mostrará al usuario.
$code (string) – un código de error personalizado, específico de API.
$message (string) – un mensaje personalizado de «motivo» para devolver.

Devuelve:

El valor del método send() del objeto Respuesta.

A diferencia de failUnauthorized(), este método debe usarse cuando el punto final de API solicitado nunca está permitido. No autorizado implica que se anima al cliente a intentarlo nuevamente con credenciales diferentes. Medios prohibidos el cliente no debe volver a intentarlo porque no ayudará. El código de estado es 403.

<?php

return $this->failForbidden('Invalid API endpoint.');

failNotFound(string $description = 'Not Found'[, string $code=null[, string $message = '']])

Parámetros:

$descripción (string) – el mensaje de error que se mostrará al usuario.
$code (string) – un código de error personalizado, específico de API.
$message (string) – un mensaje personalizado de «motivo» para devolver.

Devuelve:

El valor del método send() del objeto Respuesta.

Establece el código de estado apropiado para usar cuando no se puede encontrar el recurso solicitado. El código de estado es 404.

<?php

return $this->failNotFound('User 13 cannot be found.');

failValidationErrors($errors[, string $code=null[, string $message = '']])

Parámetros:

$errors (Mixed) – el mensaje de error o conjunto de mensajes que se mostrarán al usuario.
$code (string) – un código de error personalizado, específico de API.
$message (string) – un mensaje personalizado de «motivo» para devolver.

Devuelve:

El valor del método send() del objeto Respuesta.

Establece el código de estado apropiado para usar cuando los datos que envió el cliente no pasaron las reglas de validación. El código de estado suele ser 400.

<?php

return $this->failValidationErrors($validation->getErrors());

failResourceExists(string $description = 'Conflict'[, string $code=null[, string $message = '']])

Parámetros:

$descripción (string) – el mensaje de error que se mostrará al usuario.
$code (string) – un código de error personalizado, específico de API.
$message (string) – un mensaje personalizado de «motivo» para devolver.

Devuelve:

El valor del método send() del objeto Respuesta.

Establece el código de estado apropiado para usar cuando el recurso que el cliente intenta crear ya existe. El código de estado suele ser 409.

<?php

return $this->failResourceExists('A user already exists with that email.');

failResourceGone(string $description = 'Gone'[, string $code=null[, string $message = '']])

Parámetros:

$descripción (string) – el mensaje de error que se mostrará al usuario.
$code (string) – un código de error personalizado, específico de API.
$message (string) – un mensaje personalizado de «motivo» para devolver.

Devuelve:

El valor del método send() del objeto Respuesta.

Establece el código de estado apropiado para usar cuando el recurso solicitado se eliminó previamente y ya no está disponible. El código de estado suele ser 410.

<?php

return $this->failResourceGone('That user has been previously deleted.');

failTooManyRequests(string $description = 'Too Many Requests'[, string $code=null[, string $message = '']])

Parámetros:

$descripción (string) – el mensaje de error que se mostrará al usuario.
$code (string) – un código de error personalizado, específico de API.
$message (string) – un mensaje personalizado de «motivo» para devolver.

Devuelve:

El valor del método send() del objeto Respuesta.

Establece el código de estado apropiado para usar cuando el cliente ha llamado a un punto final de API demasiadas veces. Esto podría deberse a algún tipo de limitación o limitación de velocidad. El código de estado suele ser 400.

<?php

return $this->failTooManyRequests('You must wait 15 seconds before making another request.');

failServerError(string $description = 'Internal Server Error'[, string $code = null[, string $message = '']])

Parámetros:

$descripción (string) – el mensaje de error que se mostrará al usuario.
$code (string) – un código de error personalizado, específico de API.
$message (string) – un mensaje personalizado de «motivo» para devolver.

Devuelve:

El valor del método send() del objeto Respuesta.

Establece el código de estado apropiado para usar cuando hay un error del servidor.

<?php

return $this->failServerError('Server error.');

Rasgo de respuesta API

Uso de ejemplo

Manejo de tipos de respuesta

Referencia de clase

Uso de ejemplo 

Manejo de tipos de respuesta 

Referencia de clase 