Download the PHP package alberto-leon-crespo/rest-entity-manager without Composer

Rest Entity Manager

Un gestor de entidades rest orientado al mapeo de datos con webservices. El principal problema que te encuentras cuando usas librerias orientadas a crear un WebService es que todas están planteadas para flujos estandar en los que conectas directamente con tu BBDD. Muchas APIS modernas basadas en la web, funcionan de intermediarias con otras APIS corporativas y no corporativas. Asi surgio "Rest Entity Manager".

Funcionamiento basico de la libreria

Esta libreria consta de dos serializadores estandar. El primero gestiona la transformación de datos entre las entidades y los diferentes servicios rest. El segundo serializador se usa para codificar y decodificar los contenidos que envian y reciben los clientes y asi popular las entidades de tu API.

Internamente el gestor de entidades lee la configuración de las diferentes conexiones y realiza las peticiones a los diferentes webservices.

Servicios

• alc_rest_entity_manager.handler: Es el gestor de entidades rest. Se encarga de leer la configuración de las diferentes conexiones y cargarla en el el cliente rest.
• alc_rest_entity_manager.jms_event_subscriber: Se encarga de leer la configuracion de las entidades y configurar el mapeo hacia los diferentes WS rest.
• alc_rest_entity_manager.serializer: Es el serializador encargado de mapear la información que envian y reciben los clientes en las diferentes entidades de la API.
• alc_rest_entity_manager.logger: Servicio encargado de monitorizar y escribir los logs de las peticiones rest del manager.
• alc_rest_entity_manager.metadata_class_reader: Se encarga de leer la metainformación de las clases necesaria pra realizar los mapeos.
• alc_rest_entity_manager.parameters_procesor: Se encarga de procesar los parametros de filtrado segun la configuración definida en la conexion rest.
• alc_rest_request_parameters_name_override: Sobreescribe los parametros de la URL en el servicio "request" respetando la notacion de puntos. Ej: "poliza.id"

Consideraciones previas

Este es un bundle pensado para funcionar junto con "FOSRestBundle", pero tambien se puede usar sin el.

Instalación

Paso 1: Descargar el bundle

Abre la consola de comandos, entra en el directorio de tu proyecto y ejecuta el siguiente comando para descargar la ultima version estable de este bundle.

$ composer require alberto-leon-crespo/rest-entity-manager

Paso 2: Activar el bundle

Activa el bundle añadiendo la siguiente linea al fichero app/AppKernel.php

Configuracion

Para poder usar las entidadedes orientadas a rest es necesario configurar previamente una conexion rest.

Si quieres usar el serializador junto con FOSRestBundle es necesario que sobreescribas el serializador estandar con la siguiente configuración.

Anotaciones de configuración para las entidades.

• ALC\RestEntityManager\Annotations\Resource:

  Indica el recurso rest al que accedera la entidad. En este caso "users"

• ALC\RestEntityManager\Annotations\Repository:

  Indica el repositorio asociado a la entidad.

• ALC\RestEntityManager\Annotations\Id:

  Indica que la propiedad precedida por el comentario se trata del identificador unico del recurso.

• ALC\RestEntityManager\Annotations\Field:

  • target: El campo de destino del servicio rest.

  • type: Tipo de dato del campo.

    • Tipos soportados:

      Los tipos soportados son los mismos que acepta JMSSerializer.

• ALC\RestEntityManager\Annotations\Headers:

  Permite especificar un array de cabeceras http y los valores que se aplicaran a las solicitudes rest de la entidad.

Acciones generales del manager rest

Buscar por id

Equivalente a GET /users/:id

• id: identificador del recurso que se desea consultar.
• format: formato de salida de la información.
  • json
  • xml
  • object
• type: tipo de dato de salida si se indico en format object.

Recuperar todos los registros de un listado

Equivalente a GET /users

• format: formato de salida de la información.
  • json
  • xml
  • object
• type: tipo de dato de salida si se indico en format object.

Recuperar un listado filtrado

Equivalente a GET /users?nombre=Alberto

• filters: filtros a aplicar al listado.
• format: formato de salida de la información.
  • json
  • xml
  • object
• type: tipo de dato de salida si se indico en format object.

Recuperar el primer registro de un listado filtrado

Equivalente a GET /users?nombre=Alberto

• filters: filtros a aplicar al listado.
• format: formato de salida de la información.
  • json
  • xml
  • object
• type: tipo de dato de salida si se indico en format object.

Guardar los cambios

Equivalente a POST /users o PUT /users

Si el objeto de entidad tiene un valor asociado en el campo marcado como id, realizara un PUT, en caso contrario realizara un POST

• object: instancia de la entidad que se quiere persistir.
• format: formato de salida de la información.
  • json
  • xml
  • object
• type: tipo de dato de salida si se indico en format object.

Comprobar si existe un registro, si existe lo actualiza, en caso contrario lo crea.

Equivalente a POST /users o PUT /users

Si el objeto de entidad tiene un valor asociado en el campo marcado como id y ademas ese id existe, realizara un PUT, en caso contrario realizara un POST

• object: instancia de la entidad que se quiere persistir.
• format: formato de salida de la información.
  • json
  • xml
  • object
• type: tipo de dato de salida si se indico en format object.

Obtener la información de una entidad con los valores actualizados del webservice

• object: instancia de la entidad que se quiere refrescar.
• format: formato de salida de la información.
  • json
  • xml
  • object
• type: tipo de dato de salida si se indico en format object.

Acciones personalizadas del manager rest

Cuando por diferentes circustancias cualquiera de estas acciones estandar no funcional para tu caso de uso, puedes realizar una llamada totalmente personalizada por medio de un repositorio o realizando la acción directamente en el controlador como si se tratara de un cliente rest normal.

Con un repositorio

Es importante definir la anotacion "Repository" en la entidad rest.

Opciones avanzadas de filtrado

En ocasiones, los parametros que pasamos a la URL no son parametros de filtrado (ordenacion, paginado, etc..).

Para ello solo hay que indicar que parametros seran ignorados del filtrado y cual es su equivalencia en el WS de destino.

Equivalencia directa

En este caso la equivalencia con el WS de destino es directa entre el campo de origen y de destino

De esta manera si la URL introducida en tu WS es {{URL_BASE}}/usuarios?page=1&limit=5 se solicitaria de la siguiente manera al WS de destino {{URL_BASE}}/users?_page=1&_limit=5

Equivalencia indirecta

Puedes encontrar algunos casos en los que la equivalencia con un parametro especial de destino, no es directa, es decir, un parametro puede equivaler a dos como en el siguiente ejemplo:

En estos casos puedes crear un interceptor de parametros de la siguiente manera:

Para darlo de alta solo tienes que dar de alta la siguiente configuración en la sección "parameters_map":

Interceptores de eventos

Si fuera necesario interceptar un evento de la petición para injectar el token de una api en las cabeceras o alguna otra acción similar, solo tienes que crear un interceptor de solicitudes de la siguiente manera:

Una vez creado el interceptor, debes de darlo de alta con la siguiente configuración:

Debes de indicar que evento quieres interceptar y la clase y el metodo que interceptaran la solicitud.

Los eventos soportados que se pueden interceptar son los mismos que acepta Guzzle Http Client.

Ejemplos

Para ver mas ejemplos puedes consultar el bundle de ejemplo ALC\WebServiceBundle