Generic, light-weight, low-functionality wrapper around PHP's cURL library
This Requests library should be good enough for most requests, as long as you
aren't doing anything special or crazy. If you outgrow it, then you should either
(1) use Guzzle, or (2) write your own requests library that has better coverage.
Granted, this should handle MOST use cases. I don't know if it handles file uploads.
Theoretically, it does, but I wouldn't bank on it, and, if it doesn't, I will not
expand the functionality to cover file uploads.
With this, you can easily make GET or POST requests. Set extra headers. Easily set
a user-agent. Set parameters. And cache the data for later retrieval.
public
|
#
__construct( string $url, array $options = array( 'cache' => true, 'cache_ttl' => 600, 'cache_bin' => true ) )
Creates a request object
Currently, all the options apply to caching. So the three that are understood are:
1. cache,
2. cache_life, and
3. cache_bin.
cache is a boolean that can turn on/off caching. It is recommended that you turn it on.
cache_life is how long the cache will live. In other words, no attempts to get new data
will be made until the data saved is older than the cache life (in seconds). It defaults to
3600 (one hour).
cache_bin is the sub-directory in the workflow's cache folder where the results are saved.
If cache_bin is set to false while caching is turned on, then all the results will be saved
directly into the workflow's cache directory.
Cache files are saved as md5 hashes of the request object. So, if you change anything about the
request, then it will be considered a new cache file. Data is saved to the cache only if
we receive an HTTP response code less than 400.
My advice is not to touch these options and let the cache work with its default behavior.
A further note on cache_bin: the 'cache_bin' option, if true, will create a cache_bin
that is a directory in the cache directory named after the hostname. So if the url is
http://api.github.com/api.... then the cache_bin will be api.github.com, and all
cached data will be saved in that directory. Otherwise, if you pass a string, then that will
become the directory it will be saved under.
Parameters
- $url
- the URL to request
- $options
- [description]
|
private
|
#
set_caches( array $options )
Sets the cache options
Parameters
- $options
- an array of cache options
|
public
string|array
|
#
execute( boolean $code = false )
Executes the cURL request
Executes the cURL request
If you set $code to true, then this function will return an associative array as:
<pre>[ <span class="php-quote">'code'</span> => <span class="php-keyword2">HTTP_RESPONSE_CODE</span>, <span class="php-quote">'data'</span> => RESPONSE_DATA
];</pre>
If you get cached data, then the code will be "faked" as a 302, which is appropriate.
If there is an error, then the code will be 0. So, if you manage to get expired cache
data, then the code will be 0 and there will be data. If there is no expired cache data,
then you will receive an array of [ 0, false ].
This method does not cache data unless the response code is less than 400. If you need
better data integrity than that, use Guzzle or write your own request library. Or improve
this one by putting in a pull request on the Github repo.
Parameters
- $code
- whether or not to return an HTTP response code
Returns
string|array
the response data, or an array with the code
|
private
|
#
build_post_fields( )
Builds the post fields array
Builds the post fields array
Since
1.0.0
|
private
|
#
build_get_fields( )
Builds the post fields array
Builds the post fields array
Since
1.0.0
|
private
|
#
build_fields( )
Builds the fields out of parameters array
Builds the fields out of parameters array
Since
1.0.0
|
public
|
#
set_auth( string $username, string $password )
Sets basic authorization for a cURL request
Sets basic authorization for a cURL request
If you need more advanced authorization methods, and if you cannot make them happen with
headers, then use a different library. I recommend Guzzle.
Parameters
- $username
- a username
- $password
- a password
Since
1.0.0
|
public
|
#
set_url( string $url )
Sets the URL for the cURL request
Sets the URL for the cURL request
Parameters
Throws
Since
1.0.0
Todo
Add in custom exception
|
public
|
#
set_user_agent( string $agent )
Sets the user agent for the cURL request
Sets the user agent for the cURL request
Parameters
Since
1.0.0
|
public
|
#
use_post( )
Sets the request to use POST rather than GET
Sets the request to use POST rather than GET
Since
1.0.0
|
public
|
#
add_parameter( string $key, string $value )
Adds a parameter to the parameters array
Adds a parameter to the parameters array
Parameters
- $key
- the name of the parameter
- $value
- the value of the parameter
Since
1.0.0
|
public
|
#
add_parameters( array $params )
Adds parameters to the request
Adds parameters to the request
Parameters
- $params
- an array of parameters
Throws
Since
1.0.0
|
private
string|boolean
|
#
get_cached_data( $ignore_life = false )
Gets cached data
This method first checks if the cache file exists. If $ignore_life is true,
then it will return the data without checking the life. Otherwise, we'll check
to make sure that the $cache_life is set. Next, we check the age of the cache.
If any of these fail, then we return false, which indicates we should get new
data. Otherwise, we retrieve the cache.
Returns
string|boolean
the data saved in the cache or false
Since
1.0.0
|
private
string|boolean
|
#
get_cached_data_anyway( )
Retrieves cached data regardless of cache life
Retrieves cached data regardless of cache life
Returns
string|boolean
returns the cached data or false if none exists
Since
1.0.0
|
private
|
#
save_cache_data( string $data )
Saves data to a cache file
Saves data to a cache file
Parameters
- $data
- the data to save to the cache
Since
1.0.0
|
private
string
|
#
get_cache_key( )
Creates a cache key based on the request object
Creates a cache key based on the request object
Returns
string
a cache key
Since
1.0.0
|
private
string
|
#
get_cache_file( )
Returns the file cache
Returns
string
the full path to the cache file
Since
1.0.0
|
private
string
|
#
get_cache_dir( )
Returns the directory for the cache
Returns the directory for the cache
Returns
string
full path to cache directory
Since
1.0.0
|
private
boolean
|
#
create_cache_dir( )
Creates a cache directory if it does not exist
Creates a cache directory if it does not exist
Returns
boolean
success or failure if directory has been made
Throws
Since
1.0.0
|
private
integer
|
#
get_cache_age( )
Gets the age of a cache file
Gets the age of a cache file
Returns
integer
the age of a file in seconds
Since
1.0.0
|
public
null
|
#
clear_cache( string|boolean $bin = false )
Clears a cache bin
Call the file with no arguments if you aren't using a cache bin; however, this
will choke on sub-directories.
Parameters
- $bin
- the name of the cache bin (or a URL if you're setting them automatically)
Returns
null
Throws
Used by
|
private
|
#
clear_directory( string $dir )
Clears all the files out of a directory
Clears all the files out of a directory
Parameters
- $dir
- a path to a directory
Throws
Since
1.0.0
|