f3 wcurl
Huge rewrite, small fixes.
| maître | développeur |
|---|---|
Un plugin Fat Free Framework : pont entre votre code et l'API REST externe. F3-wcurl agit comme une couche d'abstraction logique pour cURL, qui gère l'authentification et la mise en cache des réponses réussies.
Le plugin Web intégré F3 est génial et facile à gérer les requêtes HTTP individuelles. F3-wcurl construit l'implémentation de l'intégralité de l'API distante dans votre code.
Au fil du temps, j'ai eu besoin de créer rapidement des outils et des scripts qui avaient une tâche essentielle mais répétitive : gérer les requêtes cURL, les paramètres, les objets, les réponses, etc. Au final, j'ai continué à copier les mêmes fonctions, en les modifiant. et déboguer les mêmes problèmes écrits il y a des mois pour expliquer pourquoi quelque chose ne fonctionne pas .
Même si vous disposez d'un grand contrôle et d'un accès aux options cURL, F3-wcurl ne vous oblige pas à le faire. Cela permet de se concentrer sur la demande elle-même, ce qu'elle change et ce qu'elle reçoit en retour. En tant que plugin pour l'écosystème F3, il comporte naturellement quelques dépendances intéressantes - Prefab , Cache et Web (pas pour les requêtes cURL elles-mêmes).
La classe F3 est construite à partir d’un tableau associatif de paramètres pertinents. Le tableau peut être transmis directement à partir du code ou à partir du fichier INI (importé dans F3 avant la construction de F3-wcurl) et stocké dans la ruche F3.
F3-wcurl utilise le préfabriqué et le cache de F3, ce qui permet d'appeler le même objet wcurl n'importe où à partir du code et d'une réponse rapide.
Par défaut, F3-wcurl recherchera la clé wcurl dans la ruche F3, mais INI peut facilement conserver les paramètres de plusieurs implémentations d'API REST différentes.
$ wcurl = wcurl:: instance ([ $ iniName = ' wcurl ' | $ optionsArray ]);Cette structure de tableau assez simple définit le fonctionnement interne de wcurl :
| nom | taper | défaut | description |
|---|---|---|---|
| racine | chaîne | nul | Racine de l'API distante, utilisée pour créer l'URI de la demande. |
| connexion_cb | chaîne | nul | Définissez la fonction de rappel à partir de votre code, qui peut effectuer une authentification, qui devrait être un rappel valide pour call_user_func() |
| ttl | entier | 60 | Secondes, combien de temps mettre en cache les réponses GET |
| en-têtes | tableau | [ ] | Tableau de chaînes valide cURL ["En-tête : valeur", "Another-Header : Valeur"] |
| agent utilisateur | chaîne | Version F3-wcurl | Chaîne d'agent utilisateur |
| baseauth | chaîne | nul | Envoyer les en-têtes Basic Auth, à utiliser au format username:password |
| jeton de requête | chaîne | nul | Ajouter chaque demande avec un jeton d'URL |
| encoderJSON | booléen | vrai | Météo sérialise le corps POST en JSON, la définition de false enverra le corps sous forme de formulaire HTML normal |
| courbure | tableau | [ ] | Paramètres RAW cURL Tableau de paramètres RAW cURL pour un contrôle pur et simple, avec key => val où key peut être soit une constante, soit un nom de chaîne. |
| repose | tableau | [ ] | key => val pour les aides à la création d'URL (voir la section Exemples) |
Pour définir n’importe quelle option du tableau ci-dessus, passez key => val array avec une ou plusieurs options.
$ wcurl -> setOptions (
[
' useragent ' = > ' F3-wcurl API integration ' ,
' encodeJSON ' = > false ,
' ttl ' = > 300 ,
// etc
]
);Seules les options que vous transmettez seront mises à jour, tout le reste restera dans l’état précédent/par défaut.
Pour effacer une ou plusieurs options, transmettez le nom ou la liste du tableau des clés que vous souhaitez réinitialiser aux valeurs par défaut :
$ wcurl -> clearOptions ([ ' useragent ' , ' ttl ' /*, ... etc */ ]);Pour obtenir la gamme complète d’options représentant l’état actuel de la classe wcurl :
$ wcurl -> clearOptions ();Le tableau multidimensionnel renvoyé doit être compatible pour créer exactement la même classe que celle extraite.
Renvoie des statistiques sur le nombre de requêtes exécutées depuis la création de la classe, le nombre de réponses http reçues et le nombre de réponses servies à partir du cache.
$ wcurl -> getStats ();Les fonctions actuellement prises en charge sont GET, POST, PUT, PATCH et DELETE. Cependant, j'en ajouterai d'autres au fur et à mesure que je comprendrai la nécessité de les mettre en œuvre.
$ response = $ wcurl -> get ( string $ url [, array $ fill = null [, array $ options = null ]] );Je mémorise des arguments comme celui-ci.
OVNI:
$ response = $ wcurl ->post( string $ url , array $ body = null [, array $ fill = null [, array $ options = null ]] );UFBO - Url, Remplissage, Corps, Options
$ response = $ wcurl ->put( string $ url , array $ body = null [, array $ fill = null [, array $ options = null ]] );UFBO - Url, Remplissage, Corps, Options
$ response = $ wcurl ->patch( string $ url , array $ body = null [, array $ fill = null [, array $ options = null ]] );UFBO - Url, Remplissage, Corps, Options
$ response = $ wcurl ->delete( string $ url , array $ body = null [, array $ fill = null [, array $ options = null ]] );UFBO - Url, Remplissage, Corps, Options
La table des repos répond à deux objectifs tout aussi importants :
Lors de la construction de longs chemins d'URL distants, il est plus facile de les mémoriser à l'aide de mots-clés courts, surtout s'ils sont appelés depuis plusieurs endroits. Comme allmembers au lieu de /lists/members/all/pages . Parfois, ceux-ci contiennent également des paramètres uniques, qui doivent être renseignés à chaque demande. Ce concept est l’une des principales raisons pour lesquelles ce plugin existe.
Continuez à lire.
La meilleure méthode consiste à stocker les chemins distants dans la configuration .ini . Les variables d'URL à remplir sont entourées de deux % des deux côtés.
À FAIRE : Rendre ce caractère de retour à la ligne configurable.
[wcurl.rests]
allmembers =/lists/members/all/pages
withVariable =/lists/members/%%memberID%%/pages ou passez key => value à la volée - il sera fusionné avec la configuration précédente
$ wcurl -> setOptions (
' rests ' => [
' allmembers ' => ' /lists/members/all/pages ' ,
' withVariable ' => ' /lists/members/%%memberID%%/pages ' ,
' updateEmail ' => ' /lists/members/%%memberID%%/update '
]
);Pour utiliser une route nommée, transmettez son nom au lieu du chemin complet
$ response = $ wcurl -> get ( ' allmembers ' ); Cela sera résolu en /lists/members/all/pages
$ response = $ wcurl -> get ( ' withVariable ' , array ( ' memberID ' => ' abc123ID ' ) ); Cela sera résolu en /lists/members/abc123ID/pages
Ou dans la requête POST, nous savons qu'il faut transmettre les paramètres UFBO suivants
$ wcurl -> post ( ' updateEmail ' , // path shorthand to resolve name
[ ' memberID ' => ' abc123ID ' ], // fill this in the path
[ ' email ' => ' [email protected] ' ] // body to send
); Si vous placez toute la configuration dans votre fichier ini principal, la classe ne peut être initialisée que lors de la première utilisation requise. C'est à dire lorsque votre code décide d'envoyer get(). À ce moment-là, si la classe n'est pas enregistrée dans Prefab, elle sera construite à partir de la configuration INI exactement selon les besoins.
Pour la liste complète des options, reportez-vous au tableau Options Array, quelques parchemins ci-dessus.
[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 une requête aboutit à un code HTTP 401 ou 403, wcurl appelle la fonction de rappel de connexion, puis répète la requête d'origine. S'il y a à nouveau une erreur, le résultat de la fonction d'origine est renvoyé. wcurl stocke les cookies dans un fichier temporaire unique à la racine de l'API. Ce fichier cookie est inclus dans chaque demande.
Le rappel doit renvoyer vrai si la connexion réussit, sinon la répétition automatique de la demande après le succès de l'authentification échouera.
N.B! Si la connexion ne fonctionne pas, mais return true , cela peut provoquer une boucle infinitive request->login->request->login...
Exemple de fonction de connexion
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 " ]);
} Lors de l'appel de wcurl::instance() il est renvoyé comme une classe singleton, donc à n'importe quel endroit du code, le même objet est utilisé. Pour forcer une nouvelle instance de la classe, utilisez quelque chose comme
$ apiTwo = new wcurl ([ $ iniName | $ optionsArray ]); Et puis $apiTwo peut être stocké dans la ruche F3.
Il y a beaucoup à améliorer, mais je vais actuellement créer les fonctionnalités dont j'ai besoin. Si quelque chose n'est pas possible pour votre cas d'utilisation, soumettez un problème ou même un PR. Merci aux développeurs F3 pour ce merveilleux framework. Si vous recherchez quelque chose comme F3-wcurl, mais ne l'utilisez pas, réfléchissez-y à deux fois. Pourquoi n'utilisez-vous pas encore F3 ?
