The projects from me that depended on this have either become obsolete or found other forms and shapes i.e. as Lambda functions.
Thanks F3 developers for the framework, it was fun time learning it and building automation stuff that was running for years without need to touch. I will archive this repo once the last project running will be taken offline. Please feel free to fork.
master | dev |
---|---|
A Fat Free Framework plugin: Bridge between your code and external REST API. F3-wcurl acts as a logical abstraction layer for cURL, which handles authentication and sucess response caching.
F3 built-in Web
plugin is great and easy to handle individual HTTP requests. F3-wcurl builds implementation of the whole remote API inside your code.
Over the time I've had need to quickly build tools and scripts that had one essential, but repetetive task with them: to handle cURL requests, settings, objects, responses etc. In the end, I kept copying the same functions, modifying them and debbuging the same issues why something isn't working written months ago.
Even though you have great control over and access to cURL options, F3-wcurl does not force you to do so. It lets focus on the request itself, what does it change and receive in return. As a plugin for F3 ecosystem, it naturally got few cool dependencies - Prefab
, Cache
and Web
(not for cURL requests themselves).
F3 class is built from associative array of relevant settings. Array can be passed from either code directly, or either from INI file (imported to F3 before building F3-wcurl) and stored in the F3 hive.
F3-wcurl uses F3's Prefab and Cache, which allows same wcurl object to be called anywhere from the code and quick response turnover.
On default, F3-wcurl will search for wcurl
key in F3 hive, but INI can conviniently hold settings for multiple different REST API implementations.
$wcurl = \wcurl::instance([$iniName = 'wcurl' | $optionsArray]);
This fairly simple array structure defines inner workings of wcurl:
name | type | default | description |
---|---|---|---|
root | string | null | Remote API root, which is used to build request URI. |
cb_login | string | null | Set callback function from your code, which can perform authentication, which should be valid callback for call_user_func() |
ttl | integer | 60 | Seconds, how long to cache GET responses |
headers | array | [ ] | cURL valid array of strings ["Header: value", "Another-Header: Value"] |
useragent | string | F3-wcurl version | Useragent string |
basicauth | string | null | Send Basic Auth headers, use in format username:password |
queryToken | string | null | Append each request with URL token |
encodeJSON | boolean | true | Weather serialize POST body as JSON, setting false will send body as regular HTML form |
curlopt | array | [ ] | RAW cURL settings RAW cURL settings array for outright control, with key => val where key can be either constant or either string name of it |
rests | array | [ ] | key => val table for URL building helpers (see Examples section) |
To set any option from table above, pass key => val
array with one or more options.
$wcurl->setOptions(
[
'useragent' = > 'F3-wcurl API integration',
'encodeJSON' = > false,
'ttl' = > 300,
// etc
]
);
Only options you pass will be updated, everything else will stay in previous/default state.
To clear one or more options, pass name or array list of keys you wish to reset to defaults:
$wcurl->clearOptions([ 'useragent', 'ttl' /*, ... etc */ ]);
To get full array of options that represents current state of wcurl class:
$wcurl->clearOptions();
Returned multi-dimension array should be compatible to create exactly the same class as the one extracted from.
Will return statistics how many requests are executed since class is created, what/how many http responses received and how many served from cache.
$wcurl->getStats();
Currently supported functions are GET, POST, PUT, PATCH and DELETE. Though will be adding more as I come over the need to implement them.
$response = $wcurl->get( string $url [, array $fill = null [, array $options = null ]] );
I memorize arguments like this.
UFO:
- Url - Properly would be called the PATH of the URL, or identefier from rests table (see below).
- Fill - Array of values to fill in the rests path
- Options - Force any option for this request exclusively
$response = $wcurl->post( string $url, array $body = null [, array $fill = null [, array $options = null ]] );
UFBO - Url, Fill, Body, Options
$response = $wcurl->put( string $url, array $body = null [, array $fill = null [, array $options = null ]] );
UFBO - Url, Fill, Body, Options
$response = $wcurl->patch( string $url, array $body = null [, array $fill = null [, array $options = null ]] );
UFBO - Url, Fill, Body, Options
$response = $wcurl->delete( string $url, array $body = null [, array $fill = null [, array $options = null ]] );
UFBO - Url, Fill, Body, Options
Rests table serves two equally important purposes:
- To shorthand API paths avoiding typos of long strings
- To fill in parts of those strings to build dynamic API call paths
When constructing long remote URL paths, it's easier to remember them by short keywords, especially if they are called from multiple places. Like allmembers
instead of /lists/members/all/pages
. Sometimes these contain also unique parameters, which needs to be filled in per each request. This concept is one of main reasons why this plugin exists.
Keep on reading.
The best ways is to store remote paths in the .ini
configuration. URL variables for fill are wrapped in two %
from both sides.
TODO: Make this wrap character configurable.
[wcurl.rests]
allmembers=/lists/members/all/pages
withVariable=/lists/members/%%memberID%%/pages
or pass simple key => value
array on the fly - it will be merged over with previous configuration
$wcurl->setOptions(
'rests' => [
'allmembers' => '/lists/members/all/pages',
'withVariable' => '/lists/members/%%memberID%%/pages',
'updateEmail' => '/lists/members/%%memberID%%/update'
]
);
To use named route, pass it's name instead of full path
$response = $wcurl->get( 'allmembers' );
This will resolve to /lists/members/all/pages
$response = $wcurl->get( 'withVariable', array('memberID' => 'abc123ID') );
This will resolve to /lists/members/abc123ID/pages
Or in the POST request we know that have to pass following UFBO parameters
$wcurl->post('updateEmail', // path shorthand to resolve name
[ 'memberID' =>'abc123ID' ], // fill this in the path
[ 'email'=>'andzs@pilskalns.lv' ] // body to send
);
If you put all configuration in your main ini
file, class can be initialized only on first required use of it. I.e. when your code decides to send get(). At that moment, if class is not registered in Prefab, it will be built from INI config exactly as needed.
For full list of options refer to Options Array table few scrolls above.
[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' );
If any request results in HTTP 401 or 403 code, wcurl
calls Login callback function and then repeats original request. If again there is error, it is returned to original function result. wcurl
stores cookies in temporary file unique to API root. This cookie file is included in every request.
Callback must return true, if login success, otherwise it would fail to auto-repeat request after auth success.
N!B! If login doesn't works, but still return true
, it can cause request->login->request->login...
infinitive loop
Login function example
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"]);
}
When calling \wcurl::instance()
it is returned like singleton class, thus in any place in code, same object is used. To force fresh instance from class, use something like
$apiTwo = new wcurl([$iniName | $optionsArray]);
And then $apiTwo
can be stored in F3 hive.
There's a lot to improve, but currently will be making features I need. If something not possible for your use case, submit an issue or even PR. Thanks to F3 developers for this wonderful framework. If you are looking for something as F3-wcurl, but don't use it, then think twice - Why you are not using F3 yet?