Download the PHP package powersystem/cakeapigateway without Composer
On this page you can find all versions of the php package powersystem/cakeapigateway. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download powersystem/cakeapigateway
More information about powersystem/cakeapigateway
Files in powersystem/cakeapigateway
Package cakeapigateway
Short Description ApiGatewaySDK plugin for CakePHP
License MIT
Informations about the package cakeapigateway
ApiGatewaySDK plugin para CakePHP
Este plugin contiene utilidades para crear y deployar más fácilmente aplicaciones para AWS ApiGateway.
Changelog
Fecha: 2022-08-31
- Cambios codigo deprecado para CakePHP 3.8. actualización a 4.3.
Fecha: 2019-04-15
- Agregada opción al ApiRequestComponent para habilitar la personalización de los Content-Types permitidos
Fecha: 2018-10-10
- Reescrito todo el README para denotar los cambios más recientes
- El plugin ya no es compatible con las versiones viejas (anteriores a tag v0.1.0)
Documentación
Funcionalidades
- Incluye el componente
ApiRequestComponent
para tus API Controllers, con las siguientes funcionalidades:- asegura que las requests esten formateadas correctamente en JSON
- verifica que la request provenga del ApiGateway configurado
- habilita CORS para el APIGateway
- formatea las variables de paginación correctamente si se usa el PagintorComponent en el controller para servir los datos
- agrega los Link Headers (https://tools.ietf.org/html/rfc5988) en case de que la response tenga paginación
- Incluye el trait
FlattenedFieldsTrait
para las modelos usados en las API que facilita la creación de métodos y acciones compatibles con el API.- Éste Trait simplifica el mapeo entre las tablas locales y la definición de la API.
- Esto permite separar completamente la definición del API de la estructura interna de las tablas
- También se encarga de formatear los errores de validación para que coincidan con la estructura definida para la API.
- Incluye la excepción
UnprocessableEntityException
, una excepción para manejar los errores de formato y validación de datos recibidos en la API. - Incluye el exception renderer
ApiExceptionRenderer
para poder procesar las excepciones que dispare la API de manera correcta
Instalación
Para obtener el plugin con composer se requiere agregar a composer.json
lo siguiente:
- Al objeto
"require"
, agregar el plugin:"PowerSystem/cake-apigateway": "dev-master"
- Al arreglo de
"repositories"
agregar el objeto: - correr
composer update
NOTA: asegurarse de tener los permisos de acceso/deploy correctos en el repositorio.
Una vez instalado el plugin en el repositorio se puede:
- agregar a los controllers de su API el component:
$this->loadComponent('PowerSystem/ApiGatewaySDK.ApiRequest');
- agregar a las tablas que lo requieran el trait de FlattenedFields:
use PowerSystem\ApiGatewaySDK\Traits\FlattenedFieldsTrait;
- configurar la aplicación para que use el exception renderer en
app.php
setteandoError.exceptionRenderer' a
PowerSystem\ApiGatewaySDK\Error\ApiExceptionRenderer`
Estructura
PowerSystem\ApiGatewaySDK\Controller\Component\ApiRequestComponent
- public $_apiRoute = null
- Variable interna usada para la generación de los headers Link. Para más información vea
getLinkHeaders
- Variable interna usada para la generación de los headers Link. Para más información vea
- public beforeFilter(Event $event)
- En este callback, el componente se encarga de:
- comprobar que el header
X-Amzn-Apigateway-Api-Id
está presente y coincide con la configuración - asegurarse que el header
Content-Type
seaapplication/json
para las requests de tipo PUT, POST y PATCH - asegurarse que el header
Accept
seaapplication/json
- comprobar que el header
- En este callback, el componente se encarga de:
- public beforeRender(Event $event)
- En este callback, el componente se encarga de:
- Configurar la Response con los headers necesarios para CORS
- Settear las variables del Paginator, si es que fue usado, en el array
paging
de la Response. - Settear los headers
Link
para la paginación, de existir. - Asegurarse que todas las viewVars estén serializadas.
- También se ocupa de limpiar el viewVar
_apiRoute
antes de serializar la respuesta.
- En este callback, el componente se encarga de:
PowerSystem\ApiGatewaySDK\Error\UnprocessableEntityException
- public __construct($message = null, $code = 422)
- Esta excepción se usa para mostrar los errores de validación en la requests de la API.
- utiliza el error code 422, que equivale la la HTTP Exception
422 Unprocessable Entity
- permite settear los errores de validación dentro del $message, pasandolo como array:
PowerSystem\ApiGatewaySDK\Error\ApiExceptionRenderer
-
public UnprocessableEntity($exception)
- Este exception renderer agrega soporte para las excepciones de tipo
UnprocessableEntityException
- Se encarga de settear las variables correspondientes en la Response
- En caso de haber errores de validación, los settea en la variable 'errors' del objeto de respuesta:
- Este exception renderer agrega soporte para las excepciones de tipo
- protected formatErrors($entity_errors)
- este método es usado para formatear los errores de validación en un formato de API más generico y menos Cake-like
- Por cada campo hay un arreglo que contiene los errores. Cada error consiste de un arreglo con su
code
y sumessage
. Convirtiéndo los errores de validación de Cake al estándar de API:
PowerSystem\ApiGatewaySDK\Traits\FlattenedFieldsTrait
-
public flattenedFieldsMaps()
- Devuelve un array con los mapas de campos para los metodos que usan este Trait. Es importante sobreescribir este método en la tabla para que devuelva los mapas necesarios para satisfacer la estructura del API:
- Para poder usar
getFlattenedEntity
ysetFlattenedEntity
, el array debe definir los mapas: 'get' y 'set', respectivamente. -
Los mapas se definen como arrays asociativos (
clave => valor
) donde la clave corresponde al nombre del campo resultante, y el valor corresponde al nombre del campo en los datos ingresados. Por ejemplo: - Vea
mapFlattenedFields
para más información
- protected getFlattenedFieldsMap($map_name, $flip = false)
- Este método se usa internamente para obtener los mapas desde
flattenedFieldsMaps
. - También permite invertir el mapa de ser necesario.
- Este método se usa internamente para obtener los mapas desde
-
protected mapFlattenedFields($entity, $map, $callback)
- Este método procesa una entidad o arreglo
$entity
con el mapa $map, pasando cada entrada individualmente a $callback para ser procesado. -
La forma más común de usar esto es con
Hash::get
, por ejemplo: -
Al usar
Hash::get
se nos permite definir campos en un mapa con notación de punto, por ejemplo: - Otra cualidad del método
mapFlattenedFields
es que permite mapear los campos de las entidades asociadas, por ejemplo, este mapa es para una entidad que está asociada conBankAccounts
mediantehasMany
y quiere exponerlas en el aliascuentas
:
- Este método procesa una entidad o arreglo
-
protected getFlattenedEntity($where = [], $contain = [])
- Este método es un wrapper básico que demuestra el uso de los mapas para una entidad singular.
- Úselo para casos simples o como guía para crear sus propios métodos complejos.
- Él método usa el mapa
get
definido enflattenedFieldsMaps
- El método está definido como protected porque se espera que lo uses en tus métodos en lugar de llamarlo directamente del controller.
- Los parámetros son transparentes y equivalentes a los usados para crear queries en CakePHP 3.
- El parámetro
$where
define las condiciones de búsqueda de la query, y será pasado al find sin modificaciones. - El parámetro
$contain
define las asociaciones de la query. - Un ejemplo de uso básico sería:
- protected setFlattenedEntity(Callable $method, $error_map = null)
- A diferencia de
getFlattenedEntity
, este método no es un wrapper de guardado básico, si no que está hecho para que lo uses en combinación con tus propios métodos de guardado. - Esto se debe a que usualmente, la simplificación de datos en la definición de la API lleva a que el proceso de guardado sea más complejo, y muy variado como para ser facilmente encapsulado en éste plugin.
- Esta flexibilidad permite por ejemplo guardar información en varias tablas a la vez usando un solo API endpoint, encerrando todas las operaciones en una transaction dentro de setFlattenedEntity.
- Este método ejecuta el Callable $method proporcionado dentro de un try/catch que se encarga de que los errores de validación o guardado conserven el mismo formato de mapeado.
- Es importante que el Callable use
saveOrFail
en lugar desave
, ya que el catch se basa en la excepcion de guardado emitida por el saveOrFail para formatear correctamente los errores de validación. - Al momento de mapear los errores de validación, el método utilizará el mapa proporcionado en $error_map, o de lo contrario dará vuelta el mapa 'set'.
- Un ejemplo de una implementación típica es:
- A diferencia de
Variables de configuracion
Las variables de configuración se guardan en el arreglo de configuración de la aplicación al igual que el resto de las configuraciones (config/app.php
por defecto).
Las configuraciones disponibles son: