f3 wcurl
Huge rewrite, small fixes.
| mestre | desenvolvedor |
|---|---|
Um plugin Fat Free Framework: ponte entre seu código e a API REST externa. F3-wcurl atua como uma camada de abstração lógica para cURL, que lida com autenticação e cache de resposta de sucesso.
O plugin Web integrado F3 é excelente e fácil de lidar com solicitações HTTP individuais. F3-wcurl cria a implementação de toda a API remota dentro do seu código.
Com o tempo, tive a necessidade de construir rapidamente ferramentas e scripts que tivessem uma tarefa essencial, mas repetitiva: lidar com solicitações cURL, configurações, objetos, respostas etc. e depurar os mesmos problemas de por que algo não está funcionando, escrito meses atrás .
Mesmo que você tenha grande controle e acesso às opções cURL, F3-wcurl não o força a fazer isso. Permite focar na solicitação em si, no que ela muda e recebe em troca. Como um plugin para o ecossistema F3, ele naturalmente possui algumas dependências interessantes - Prefab , Cache e Web (não para solicitações cURL em si).
A classe F3 é construída a partir de um conjunto associativo de configurações relevantes. A matriz pode ser passada diretamente de qualquer código ou de um arquivo INI (importado para F3 antes de construir F3-wcurl) e armazenado na seção F3.
F3-wcurl usa Prefab e Cache do F3, que permite que o mesmo objeto wcurl seja chamado em qualquer lugar do código e resposta rápida.
Por padrão, F3-wcurl procurará a chave wcurl no hive F3, mas o INI pode manter configurações de maneira conveniente para várias implementações diferentes da API REST.
$ wcurl = wcurl:: instance ([ $ iniName = ' wcurl ' | $ optionsArray ]);Esta estrutura de array bastante simples define o funcionamento interno do wcurl:
| nome | tipo | padrão | descrição |
|---|---|---|---|
| raiz | corda | nulo | Raiz remota da API, que é usada para criar o URI da solicitação. |
| cb_login | corda | nulo | Defina a função de retorno de chamada do seu código, que pode realizar autenticação, que deve ser um retorno de chamada válido para call_user_func() |
| TTL | inteiro | 60 | Segundos, quanto tempo armazenar em cache as respostas GET |
| cabeçalhos | variedade | [ ] | Matriz válida de strings cURL ["Cabeçalho: valor", "Outro cabeçalho: Valor"] |
| agente de usuário | corda | Versão F3-wcurl | String do agente do usuário |
| autenticação básica | corda | nulo | Envie cabeçalhos de autenticação básica, use no formato username:password |
| queryToken | corda | nulo | Anexe cada solicitação com token de URL |
| codificarJSON | booleano | verdadeiro | Weather serializa o corpo do POST como JSON, definir false enviará o corpo como formulário HTML normal |
| enrolado | variedade | [ ] | Configurações de cURL RAW Matriz de configurações de cURL RAW para controle total, com key => val onde key pode ser constante ou qualquer nome de string dela |
| descansa | variedade | [ ] | key => val para auxiliares de construção de URL (consulte a seção Exemplos) |
Para definir qualquer opção da tabela acima, passe key => val array com uma ou mais opções.
$ wcurl -> setOptions (
[
' useragent ' = > ' F3-wcurl API integration ' ,
' encodeJSON ' = > false ,
' ttl ' = > 300 ,
// etc
]
);Somente as opções que você passar serão atualizadas, todo o resto permanecerá no estado anterior/padrão.
Para limpar uma ou mais opções, passe o nome ou a lista de chaves que você deseja redefinir para os padrões:
$ wcurl -> clearOptions ([ ' useragent ' , ' ttl ' /*, ... etc */ ]);Para obter uma gama completa de opções que representam o estado atual da classe wcurl:
$ wcurl -> clearOptions ();A matriz multidimensional retornada deve ser compatível para criar exatamente a mesma classe daquela extraída.
Retornará estatísticas de quantas solicitações foram executadas desde a criação da classe, quais/quantas respostas HTTP foram recebidas e quantas foram atendidas pelo cache.
$ wcurl -> getStats ();As funções atualmente suportadas são GET, POST, PUT, PATCH e DELETE. Embora irei adicionar mais à medida que me deparo com a necessidade de implementá-los.
$ response = $ wcurl -> get ( string $ url [, array $ fill = null [, array $ options = null ]] );Eu memorizo argumentos como este.
OVNI:
$ response = $ wcurl ->post( string $ url , array $ body = null [, array $ fill = null [, array $ options = null ]] );UFBO - URL, Preenchimento, Corpo, Opções
$ response = $ wcurl ->put( string $ url , array $ body = null [, array $ fill = null [, array $ options = null ]] );UFBO - URL, Preenchimento, Corpo, Opções
$ response = $ wcurl ->patch( string $ url , array $ body = null [, array $ fill = null [, array $ options = null ]] );UFBO - URL, Preenchimento, Corpo, Opções
$ response = $ wcurl ->delete( string $ url , array $ body = null [, array $ fill = null [, array $ options = null ]] );UFBO - URL, Preenchimento, Corpo, Opções
A tabela de descansos serve a dois propósitos igualmente importantes:
Ao construir longos caminhos de URL remotos, é mais fácil lembrá-los por meio de palavras-chave curtas, especialmente se forem chamados de vários lugares. Como allmembers em vez de /lists/members/all/pages . Às vezes, eles também contêm parâmetros exclusivos, que precisam ser preenchidos a cada solicitação. Este conceito é uma das principais razões da existência deste plugin.
Continue lendo.
A melhor maneira é armazenar caminhos remotos na configuração .ini . Variáveis de URL para preenchimento são agrupadas em dois % em ambos os lados.
TODO: Torne este caractere de quebra configurável.
[wcurl.rests]
allmembers =/lists/members/all/pages
withVariable =/lists/members/%%memberID%%/pages ou passe key => value instantaneamente - ela será mesclada com a configuração anterior
$ wcurl -> setOptions (
' rests ' => [
' allmembers ' => ' /lists/members/all/pages ' ,
' withVariable ' => ' /lists/members/%%memberID%%/pages ' ,
' updateEmail ' => ' /lists/members/%%memberID%%/update '
]
);Para usar a rota nomeada, passe seu nome em vez do caminho completo
$ response = $ wcurl -> get ( ' allmembers ' ); Isso será resolvido para /lists/members/all/pages
$ response = $ wcurl -> get ( ' withVariable ' , array ( ' memberID ' => ' abc123ID ' ) ); Isso será resolvido para /lists/members/abc123ID/pages
Ou na solicitação POST sabemos que devemos passar os seguintes parâmetros UFBO
$ wcurl -> post ( ' updateEmail ' , // path shorthand to resolve name
[ ' memberID ' => ' abc123ID ' ], // fill this in the path
[ ' email ' => ' [email protected] ' ] // body to send
); Se você colocar todas as configurações em seu arquivo ini principal, a classe poderá ser inicializada apenas no primeiro uso necessário. Ou seja, quando seu código decide enviar get(). Nesse momento, se a classe não estiver cadastrada no Prefab, ela será construída a partir da configuração INI exatamente conforme necessário.
Para obter a lista completa de opções, consulte a tabela Options Array, alguns pergaminhos acima.
[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 ' ); Se alguma solicitação resultar em código HTTP 401 ou 403, wcurl chama a função de retorno de chamada de Login e repete a solicitação original. Se novamente houver erro, ele retornará ao resultado original da função. wcurl armazena cookies em um arquivo temporário exclusivo para a raiz da API. Este arquivo cookie está incluído em todas as solicitações.
O retorno de chamada deve retornar verdadeiro, se o login for bem-sucedido, caso contrário, não será possível repetir automaticamente a solicitação após o sucesso da autenticação.
N!B! Se o login não funcionar, mas ainda return true , pode causar request->login->request->login... loop infinitivo
Exemplo de função de login
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 " ]);
} Ao chamar wcurl::instance() ele é retornado como uma classe singleton, portanto, em qualquer lugar do código, o mesmo objeto é usado. Para forçar uma nova instância da classe, use algo como
$ apiTwo = new wcurl ([ $ iniName | $ optionsArray ]); E então $apiTwo pode ser armazenado na seção F3.
Há muito o que melhorar, mas atualmente estarei fazendo os recursos que preciso. Se algo não for possível para o seu caso de uso, envie um problema ou até mesmo um PR. Obrigado aos desenvolvedores da F3 por esta estrutura maravilhosa. Se você está procurando algo como F3-wcurl, mas não usa, pense duas vezes - Por que você ainda não está usando F3?
