f3 wcurl
Huge rewrite, small fixes.
| maestro | desarrollador |
|---|---|
Un complemento de Fat Free Framework: puente entre su código y la API REST externa. F3-wcurl actúa como una capa de abstracción lógica para cURL, que maneja la autenticación y el almacenamiento en caché de respuestas exitosas.
El complemento Web integrado de F3 es excelente y fácil de manejar solicitudes HTTP individuales. F3-wcurl crea la implementación de toda la API remota dentro de su código.
Con el tiempo, tuve la necesidad de crear rápidamente herramientas y scripts que tuvieran una tarea esencial pero repetitiva: manejar solicitudes de cURL, configuraciones, objetos, respuestas, etc. Al final, seguí copiando las mismas funciones, modificándolas. y depurar los mismos problemas por los que algo no funciona, escrito hace meses .
Aunque tienes un gran control y acceso a las opciones de cURL, F3-wcurl no te obliga a hacerlo. Centrémonos en la solicitud en sí, en lo que cambia y recibe a cambio. Como complemento para el ecosistema F3, naturalmente tiene algunas dependencias interesantes: Prefab , Cache y Web (no para las solicitudes cURL en sí).
La clase F3 se construye a partir de una matriz asociativa de configuraciones relevantes. La matriz se puede pasar directamente desde el código o desde un archivo INI (importado a F3 antes de crear F3-wcurl) y almacenarlo en la colmena F3.
F3-wcurl utiliza Prefab y Cache de F3, lo que permite llamar al mismo objeto wcurl desde cualquier lugar del código y una respuesta rápida.
De forma predeterminada, F3-wcurl buscará la clave wcurl en la colmena F3, pero INI puede mantener convenientemente configuraciones para múltiples implementaciones de API REST diferentes.
$ wcurl = wcurl:: instance ([ $ iniName = ' wcurl ' | $ optionsArray ]);Esta estructura de matriz bastante simple define el funcionamiento interno de wcurl:
| nombre | tipo | por defecto | descripción |
|---|---|---|---|
| raíz | cadena | nulo | Raíz de API remota, que se utiliza para crear el URI de solicitud. |
| cb_login | cadena | nulo | Establezca la función de devolución de llamada desde su código, que puede realizar la autenticación, que debería ser una devolución de llamada válida para call_user_func() |
| ttl | entero | 60 | Segundos, cuánto tiempo se almacenan en caché las respuestas GET |
| encabezados | formación | [ ] | cURL matriz válida de cadenas ["Encabezado: valor", "Otro encabezado: valor"] |
| agente de usuario | cadena | Versión F3-wcurl | Cadena de agente de usuario |
| autenticación básica | cadena | nulo | Envíe encabezados de autenticación básica, utilícelos en formato username:password |
| token de consulta | cadena | nulo | Adjunte cada solicitud con un token de URL |
| codificarJSON | booleano | verdadero | El tiempo serializa el cuerpo de la POST como JSON, al establecer false se enviará el cuerpo como un formulario HTML normal. |
| rizo | formación | [ ] | Configuración de rizo RAW Matriz de configuración de rizo RAW para un control total, con key => val donde la clave puede ser una constante o un nombre de cadena |
| descansa | formación | [ ] | key => val para ayudantes de creación de URL (consulte la sección de Ejemplos) |
Para configurar cualquier opción de la tabla anterior, pase key => val array con una o más opciones.
$ wcurl -> setOptions (
[
' useragent ' = > ' F3-wcurl API integration ' ,
' encodeJSON ' = > false ,
' ttl ' = > 300 ,
// etc
]
);Solo se actualizarán las opciones que usted pase, todo lo demás permanecerá en el estado anterior/predeterminado.
Para borrar una o más opciones, pase el nombre o la lista de claves que desea restablecer a los valores predeterminados:
$ wcurl -> clearOptions ([ ' useragent ' , ' ttl ' /*, ... etc */ ]);Para obtener una gama completa de opciones que representan el estado actual de la clase wcurl:
$ wcurl -> clearOptions ();La matriz multidimensional devuelta debe ser compatible para crear exactamente la misma clase que la extraída.
Devolverá estadísticas sobre cuántas solicitudes se ejecutan desde que se creó la clase, qué/cuántas respuestas http se recibieron y cuántas se entregaron desde la memoria caché.
$ wcurl -> getStats ();Las funciones actualmente admitidas son GET, POST, PUT, PATCH y DELETE. Aunque agregaré más a medida que descubra la necesidad de implementarlos.
$ response = $ wcurl -> get ( string $ url [, array $ fill = null [, array $ options = null ]] );Memorizo argumentos como este.
OVNI:
$ response = $ wcurl ->post( string $ url , array $ body = null [, array $ fill = null [, array $ options = null ]] );UFBO: URL, relleno, cuerpo, opciones
$ response = $ wcurl ->put( string $ url , array $ body = null [, array $ fill = null [, array $ options = null ]] );UFBO: URL, relleno, cuerpo, opciones
$ response = $ wcurl ->patch( string $ url , array $ body = null [, array $ fill = null [, array $ options = null ]] );UFBO: URL, relleno, cuerpo, opciones
$ response = $ wcurl ->delete( string $ url , array $ body = null [, array $ fill = null [, array $ options = null ]] );UFBO: URL, relleno, cuerpo, opciones
La tabla de descansos tiene dos propósitos igualmente importantes:
Al construir rutas URL remotas largas, es más fácil recordarlas mediante palabras clave cortas, especialmente si se llaman desde varios lugares. Como allmembers en lugar de /lists/members/all/pages . A veces, estos también contienen parámetros únicos, que deben completarse en cada solicitud. Este concepto es una de las razones principales por las que existe este complemento.
Sigue leyendo.
La mejor manera es almacenar rutas remotas en la configuración .ini . Las variables de URL para el relleno están envueltas en dos % de ambos lados.
TODO: Haga que este carácter envolvente sea configurable.
[wcurl.rests]
allmembers =/lists/members/all/pages
withVariable =/lists/members/%%memberID%%/pages o pase key => value sobre la marcha; se fusionará con la configuración anterior
$ wcurl -> setOptions (
' rests ' => [
' allmembers ' => ' /lists/members/all/pages ' ,
' withVariable ' => ' /lists/members/%%memberID%%/pages ' ,
' updateEmail ' => ' /lists/members/%%memberID%%/update '
]
);Para usar una ruta con nombre, pase su nombre en lugar de la ruta completa
$ response = $ wcurl -> get ( ' allmembers ' ); Esto se resolverá en /lists/members/all/pages
$ response = $ wcurl -> get ( ' withVariable ' , array ( ' memberID ' => ' abc123ID ' ) ); Esto se resolverá en /lists/members/abc123ID/pages
O en la solicitud POST sabemos que tiene que pasar siguiendo los parámetros de UFBO
$ wcurl -> post ( ' updateEmail ' , // path shorthand to resolve name
[ ' memberID ' => ' abc123ID ' ], // fill this in the path
[ ' email ' => ' [email protected] ' ] // body to send
); Si coloca toda la configuración en su archivo ini principal, la clase se puede inicializar solo en el primer uso requerido. Es decir, cuando su código decide enviar get(). En ese momento, si la clase no está registrada en Prefab, se creará desde la configuración INI exactamente según sea necesario.
Para obtener una lista completa de opciones, consulte la tabla Matriz de opciones que se encuentra arriba.
[wcurl]
root =http://mysite.api/v1
ttl =3600
cb_login =yourClass::cb_do_login
useragent = Zeus was here
headers = " Header: value " , " Another-Header: Value "
[wcurl.rests]
allmembers =/lists/members/all/pages
withVariable =/lists/members/%%memberID%%/pages
; Using with multiple API's
[apitwo]
root =http://yoursite.io/v2
ttl =60
useragent = Big Falcon Rocket
[apitwo.rests]
getUsers =/lists/members/all/pages
getOneUser =/lists/members/%%memberID%%/pages $ wcurl -> setLogin ( callback ' yourClass::cb_do_login ' ); Si alguna solicitud da como resultado un código HTTP 401 o 403, wcurl llama a la función de devolución de llamada de inicio de sesión y luego repite la solicitud original. Si nuevamente hay un error, se devuelve al resultado de la función original. wcurl almacena cookies en un archivo temporal exclusivo de la raíz API. Este archivo cookie se incluye en cada solicitud.
La devolución de llamada debe devolver verdadero, si el inicio de sesión se realizó correctamente; de lo contrario, no se podrá repetir automáticamente la solicitud después de la autenticación exitosa.
¡NÓTESE BIEN! Si el inicio de sesión no funciona, pero aún así return true , puede causar un bucle infinitivo request->login->request->login...
Ejemplo de función de inicio de sesión
static function cb_do_login (){
$ wcurl = wcurl:: instance ();
$ login = $ wcurl -> post ( " /login " , array (
' login ' => ' my_user ' ,
' password ' => ' covfefe ' )
);
if ( $ login [ ' status ' ][ ' http_code ' ]== 200 ){
return true ;
}
// or
$ wcurl -> setOptions ( [ ' basicauth ' => " $ user : $ password " ]);
} Al llamar a wcurl::instance() se devuelve como una clase singleton, por lo tanto, en cualquier lugar del código, se utiliza el mismo objeto. Para forzar una nueva instancia de la clase, use algo como
$ apiTwo = new wcurl ([ $ iniName | $ optionsArray ]); Y luego $apiTwo se puede almacenar en la colmena F3.
Hay mucho que mejorar, pero actualmente estaré creando las funciones que necesito. Si algo no es posible para su caso de uso, envíe un problema o incluso una PR. Gracias a los desarrolladores de F3 por este maravilloso marco. Si está buscando algo como F3-wcurl, pero no lo usa, piénselo dos veces: ¿por qué no está usando F3 todavía?
