Package: Zebra_cURL

Class: Zebra_cURL

source file: /Zebra_cURL.php

Class Overview


Zebra_cURL, a high performance PHP cURL library

Zebra_cURL is a high performance PHP library acting as a wrapper to PHP's libcurl library, which not only allows the running of multiple requests at once asynchronously, in parallel, but also as soon as one thread finishes it can be processed right away without having to wait for the other threads in the queue to finish.

Also, each time a request is completed another one is added to the queue, thus keeping a constant number of threads running at all times and eliminating wasted CPU cycles from busy waiting. This result is a faster and more efficient way of processing large quantities of cURL requests (like fetching thousands of RSS feeds at once), drastically reducing processing time.

This script supports GET and POST request, basic downloads, downloads from FTP servers, HTTP Authentication, and requests through proxy servers.

For maximum efficiency downloads are streamed (bytes downloaded are directly written to disk) removing the unnecessary strain from the server of having to read files into memory first, and then writing them to disk.

Zebra_cURL requires the PHP cURL extension to be enabled.

The code is heavily commented and generates no warnings/errors/notices when PHP's error reporting level is set to E_ALL.

Visit http://stefangabos.ro/php-libraries/zebra-curl/ for more information.

For more resources visit http://stefangabos.ro/

Author(s):

Version:

  • 1.3.3 (last revision: February 11, 2016)

Copyright:

  • (c) 2013 - 2016 Stefan Gabos

Class properties

integer $pause_interval

The number of seconds to wait between processing batches of requests.

If the value of this property is greater than 0, the library will process as many requests as defined by the threads property, and then wait for pause_interval seconds before processing the next batch of requests.

Default is 0 (the library will keep as many parallel threads as defined by threads running at all times, until there are no more requests to process).

Tags:
since: 1.3.0
access: public
Top

integer $threads

The number of parallel, asynchronous, requests to be processed by the library, at all times.

  1. // process 30 simultaneous requests, at all times
  2. $curl->threads 30;

Note that, unless pause_interval is set to a value greater than 0, the library will process a constant number of requests, at all times; it's doing this by processing a new request as soon as another one finishes, instead of waiting for each batch to finish, and so on, until there are no more requests to process, and thus greatly decreasing execution time.

If pause_interval is set to a value greater than 0, the library will process as many requests as set by the threads property and then will wait for pause_interval seconds before processing the next batch of requests.

Default is 10.

Tags:
access: public
Top

Class methods

constructor __construct()

void __construct ( [ boolean $htmlentities = true] )

Constructor of the class.

Below is the list of default options set by the library when instantiated:

  • CURLINFO_HEADER_OUT - TRUE; get the last request header; if set to FALSE the "last_request" entry of the "headers" attribute of the object given as argument to the callback function, will be an empty string;
  • CURLOPT_AUTOREFERER - TRUE; automatically set the Referer: field in requests where it follows a Location: redirect;
  • CURLOPT_COOKIEFILE - empty string; no cookies are loaded, but cookie handling is still enabled
  • CURLOPT_CONNECTTIMEOUT - 10; the number of seconds to wait while trying to connect. use 0 to wait indefinitely;
  • CURLOPT_ENCODING - gzip,deflate; the contents of the "Accept-Encoding:" header; it enables decoding of the response
  • CURLOPT_FOLLOWLOCATION - TRUE; automatically follow any Location: header that the server sends as part of the HTTP header (note this is recursive, PHP will follow as many Location: headers as specified by the value of CURLOPT_MAXREDIRS - see below);
  • CURLOPT_HEADER - TRUE; get the response header(s); if set to FALSE the "responses" entry of the "headers" attribute of the object given as argument to the callback function, will be an empty string;
  • CURLOPT_MAXREDIRS - 50; the maximum amount of HTTP redirections to follow; used together with CURLOPT_FOLLOWLOCATION;
  • CURLOPT_RETURNTRANSFER - TRUE; return the transfer's body as a string instead of outputting it directly; if set to FALSE the "body" attribute of the object given as argument to a callback function will be an empty string;
  • CURLOPT_SSL_VERIFYHOST - 2; check the existence of a common name in the SSL peer certificate (for when connecting to HTTPS), and that it matches with the provided hostname; see also the ssl method;
  • CURLOPT_SSL_VERIFYPEER - FALSE; stop cURL from verifying the peer's certificate (which would most likely cause the request to fail). see also the ssl method;
  • CURLOPT_TIMEOUT - 10; the maximum number of seconds to allow cURL functions to execute;
  • CURLOPT_USERAGENT - A (slightly) random user agent (Internet Explorer 9 or 10, on Windows Vista, 7 or 8, with other extra strings). Some web services will not respond unless a valid user-agent string is provided
Parameters:
boolean $htmlentities Instructs the script whether the response body returned by the get and post methods should be run through PHP's htmlentities function.
Top

method cache()

void cache ( string $path , [ integer $lifetime = 3600] , [ boolean $compress = true] , [ octal $chmod = 0755] )

Use this method to enable caching of requests.

Note that only the actual request is cached and not associated downloads, if any!

Caching is disabled by default!

  1. // the callback function to be executed for each and every
  2. // request, as soon as a request finishes
  3. // the callback function receives as argument an object with 4 properties
  4. // (info, header, body and response)
  5. function mycallback($result{
  6.  
  7.     // everything went well at cURL level
  8.     if ($result->response[1== CURLE_OK{
  9.  
  10.         // if server responded with code 200 (meaning that everything went well)
  11.         // see http://httpstatus.es/ for a list of possible response codes
  12.         if ($result->info['http_code'== 200{
  13.  
  14.             // see all the returned data
  15.             print_r('<pre>');
  16.             print_r($result);
  17.  
  18.         // show the server's response code
  19.         else die('Server responded with code ' $result->info['http_code']);
  20.  
  21.     // something went wrong
  22.     // ($result still contains all data that could be gathered)
  23.     else die('cURL responded with: ' $result->response[0]);
  24.  
  25. }
  26.  
  27. // include the Zebra_cURL library
  28. require 'path/to/Zebra_cURL';
  29.  
  30. // instantiate the Zebra_cURL object
  31. $curl new Zebra_cURL();
  32.  
  33. // cache results in the "cache" folder and for 86400 seconds (24 hours)
  34. $curl->cache('cache'86400);
  35.  
  36. // let's fetch the RSS feeds of some popular tech-related websites
  37. // execute the "mycallback" function for each request, as soon as it finishes
  38. $curl->get(array(
  39.     'http://feeds.feedburner.com/alistapart/main',
  40.     'http://feeds.feedburner.com/TechCrunch',
  41.     'http://feeds.mashable.com/mashable',
  42. )'mycallback')
Tags:
access: public
Parameters:
string $path

Path where cache files to be stored.

Setting this to FALSE will disable caching.

If set to a non-existing path, the library will try to create the folder and will trigger an error if, for whatever reasons, it is unable to do so. If the folder can be created, its permissions will be set to the value of $chmod

integer $lifetime

(Optional) The number of seconds after which cache will be considered expired.

Default is 3600 (one hour).

boolean $compress

(Optional) If set to TRUE, cache files will be gzcompress-ed so that they occupy less disk space.

Default is TRUE.

octal $chmod

(Optional) The file system permissions to be set for newly created cache files.

I suggest using the value "0755" (without the quotes) but, if you know what you are doing, here is how you can calculate the permission levels:

  • 400 Owner Read
  • 200 Owner Write
  • 100 Owner Execute
  • 40 Group Read
  • 20 Group Write
  • 10 Group Execute
  • 4 Global Read
  • 2 Global Write
  • 1 Global Execute

Default is "0755" (without the quotes).

Top

method cookies()

void cookies ( string $path )

Sets the path and name of the file to save to / retrieve cookies from. All cookie data will be stored in this file on a per-domain basis. Important when cookies need to stored/restored to maintain status/session of requests made to the same domains.

This method will automatically set the CURLOPT_COOKIEJAR and CURLOPT_COOKIEFILE options.

Tags:
access: public
Parameters:
string $path

The path to a file to save to / retrieve cookies from.

If file does not exist the library will attempt to create it, and if it is unable to create it will trigger an error.

Top

method delete()

void delete ( mixed $urls , [ mixed $callback = ''] )

Performs an HTTP DELETE request to one or more URLs with the POST data as specified by the $urls argument, and executes the callback function specified by the $callback argument for each and every request, as soon as a request finishes.

This method will automatically set the following options:

  • CURLINFO_HEADER_OUT - TRUE
  • CURLOPT_CUSTOMREQUEST - "DELETE"
  • CURLOPT_HEADER - TRUE
  • CURLOPT_NOBODY - FALSE
  • CURLOPT_POST - FALSE
  • CURLOPT_POSTFIELDS - the POST data

...and will unset the following options:

  • CURLOPT_BINARYTRANSFER
  • CURLOPT_HTTPGET - TRUE
  • CURLOPT_FILE

Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every request, as soon as a request finishes. The number of parallel requests to be constantly processed, at all times, can be set through the threads property. See also the pause_interval property.

Note that requests may not finish in the same order as initiated!

  1. // the callback function to be executed for each and every
  2. // request, as soon as a request finishes
  3. // the callback function receives as argument an object with 4 properties
  4. // (info, header, body and response)
  5. function mycallback($result{
  6.  
  7.     // everything went well at cURL level
  8.     if ($result->response[1== CURLE_OK{
  9.  
  10.         // if server responded with code 200 (meaning that everything went well)
  11.         // see http://httpstatus.es/ for a list of possible response codes
  12.         if ($result->info['http_code'== 200{
  13.  
  14.             // see all the returned data
  15.             print_r('<pre>');
  16.             print_r($result);
  17.  
  18.         // show the server's response code
  19.         else die('Server responded with code ' $result->info['http_code']);
  20.  
  21.     // something went wrong
  22.     // ($result still contains all data that could be gathered)
  23.     else die('cURL responded with: ' $result->response[0]);
  24.  
  25. }
  26.  
  27. // include the Zebra_cURL library
  28. require 'path/to/Zebra_cURL';
  29.  
  30. // instantiate the Zebra_cURL object
  31. $curl new Zebra_cURL();
  32.  
  33. // do a PUT and execute the "mycallback" function for each
  34. // request, as soon as it finishes
  35. $curl->delete(array(
  36.     'http://www.somewebsite.com'  =>  array(
  37.         'data_1'  =>  'value 1',
  38.         'data_2'  =>  'value 2',
  39.     ),
  40. )'mycallback');
Tags:
since: 1.3.3
access: public
Parameters:
mixed $urls

An associative array in the form of url => delete-data, where "delete-data" is an associative array in the form of name => value.

"delete-data" can also be an arbitrary string - useful if you want to send raw data (like a JSON)

The Content-Type header will be set to multipart/form-data.

mixed $callback

(Optional) Callback function to be called as soon as a request finishes.

May be given as a string representing a name of an existing function, as an anonymous function created on the fly via create_function or via a closure.

The callback function receives as first argument an object with 4 properties as described below, while any further arguments passed to the delete method will be passed as extra arguments to the callback function:

  • info - an associative array containing information about the request that just finished, as returned by PHP's curl_getinfo() function;

  • headers - an associative array with 2 items:
- last_request an array with a single entry containing the request headers generated by the last request; so, remember, if there are redirects involved, there will be more requests made, but only information from the last one will be available; if explicitly disabled via the option method by setting CURLINFO_HEADER_OUT to 0 or FALSE, this will be an empty string;

- responses an array with one or more entries (if there are redirects involved) with the response headers of all the requests made; if explicitly disabled via the option method by setting CURLOPT_HEADER to 0 or FALSE, this will be an empty string;

Unless disabled, each entry in the headers' array is an associative array in the form of property => value

  • body - the response of the request (the content of the page at the URL).

Unless disabled via the constructor, all applicable characters will be converted to HTML entities via PHP's htmlentities function, so remember to use PHP's html_entity_decode function to do reverse this, if it's the case;

If "body" is explicitly disabled via the option method by setting CURLOPT_NOBODY to 0 or FALSE, this will be an empty string;

  • response - the response given by the cURL library as an array with 2 entries: the first entry is the textual representation of the result's code, while second is the result's code itself; if the request was successful, these values will be array(CURLE_OK, 0); consult this list to see the possible values of this property;
If the callback function returns FALSE while cache is enabled, the library will not cache the respective request, making it easy to retry failed requests without having to clear all cache.

Top

method download()

void download ( mixed $urls , string $path , [ mixed $callback = ''] )

Downloads one or more files from one or more URLs specified by the $urls argument, saves the downloaded files (with their original name) to the path specified by the $path argument, and executes the callback function specified by the $callback argument for each and every request, as soon as a request finishes.

Downloads are streamed (bytes downloaded are directly written to disk) removing the unnecessary strain from your server of reading files into memory first, and then writing them to disk.

This method will automatically set the following options:

  • CURLINFO_HEADER_OUT - TRUE
  • CURLOPT_BINARYTRANSFER - TRUE
  • CURLOPT_HEADER - TRUE
  • CURLOPT_FILE

...and will unset the following options:

  • CURLOPT_CUSTOMREQUEST
  • CURLOPT_HTTPGET
  • CURLOPT_NOBODY
  • CURLOPT_POST
  • CURLOPT_POSTFIELDS

Files are downloaded preserving their original names, so you may want to check that if you are downloading more files having the same name!

Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every request, as soon as a request finishes. The number of parallel requests to be constantly processed, at all times, can be set through the threads property. See also the pause_interval property.

Note that requests may not finish in the same order as initiated!

  1. // the callback function to be executed for each and every
  2. // request, as soon as a request finishes
  3. // the callback function receives as argument an object with 4 properties
  4. // (info, header, body and response)
  5. function mycallback($result{
  6.  
  7.     // everything went well at cURL level
  8.     if ($result->response[1== CURLE_OK{
  9.  
  10.         // if server responded with code 200 (meaning that everything went well)
  11.         // see http://httpstatus.es/ for a list of possible response codes
  12.         if ($result->info['http_code'== 200{
  13.  
  14.             // see all the returned data
  15.             print_r('<pre>');
  16.             print_r($result);
  17.  
  18.         // show the server's response code
  19.         else die('Server responded with code ' $result->info['http_code']);
  20.  
  21.     // something went wrong
  22.     // ($result still contains all data that could be gathered)
  23.     else die('cURL responded with: ' $result->response[0]);
  24.  
  25. }
  26.  
  27. // include the Zebra_cURL library
  28. require 'path/to/Zebra_cURL';
  29.  
  30. // instantiate the Zebra_cURL object
  31. $curl new Zebra_cURL();
  32.  
  33. // download 2 images from 2 different websites, and
  34. // execute the "mycallback" function for each request, as soon as it finishes
  35. $curl->download(array(
  36.     'http://www.somewebsite.com/images/alpha.jpg',
  37.     'http://www.otherwebsite.com/images/omega.jpg',
  38. )'destination/path/''mycallback');
Tags:
access: public
Parameters:
mixed $urls A single URL or an array of URLs to process.
string $path

The path to where to save the file(s) to.

If path is not pointing to a directory or is not writable, the library will trigger an error.

mixed $callback

(Optional) Callback function to be called as soon as a request finishes.

May be given as a string representing a name of an existing function, as an anonymous function created on the fly via create_function or via a closure.

The callback function receives as first argument an object with 4 properties as described below, while any further arguments passed to the download method will be passed as extra arguments to the callback function:

  • info - an associative array containing information about the request that just finished, as returned by PHP's curl_getinfo function; there's also an extra entry called original_url because, as curl_getinfo() only returns information about the last request, the original URL may be lost otherwise.
  • headers - an associative array with 2 items:
- last_request an array with a single entry containing the request headers generated by the last request; so, remember, if there are redirects involved, there will be more requests made, but only information from the last one will be available; if explicitly disabled via the option method by setting CURLINFO_HEADER_OUT to 0 or FALSE, this will be an empty string;

- responses an empty string as it is not available for this method;

Unless disabled, each entry in the headers' array is an associative array in the form of property => value

  • body - an empty string as it is not available for this method;
  • response - the response given by the cURL library as an array with 2 entries: the first entry is the textual representation of the result's code, while second is the result's code itself; if the request was successful, these values will be array(CURLE_OK, 0); consult this list to see the possible values of this property;
If the callback function returns FALSE while cache is enabled, the library will not cache the respective request, making it easy to retry failed requests without having to clear all cache.

Top

method ftp_download()

void ftp_download ( mixed $urls , string $path , [ string $username = ''] , [ string $password = ''] , [ mixed $callback = ''] )

Works exactly like the download method only that downloads are made from an FTP server.

Downloads from an FTP server to which the connection is made using the given $username and $password arguments, one or more files specified by the $urls argument, saves the downloaded files (with their original name) to the path specified by the $path argument, and executes the callback function specified by the $callback argument for each and every request, as soon as a request finishes.

Downloads are streamed (bytes downloaded are directly written to disk) removing the unnecessary strain from your server of reading files into memory first, and then writing them to disk.

This method will automatically set the following options:

  • CURLINFO_HEADER_OUT - TRUE
  • CURLOPT_BINARYTRANSFER - TRUE
  • CURLOPT_HEADER - TRUE
  • CURLOPT_FILE

...and will unset the following options:

  • CURLOPT_CUSTOMREQUEST
  • CURLOPT_HTTPGET
  • CURLOPT_NOBODY
  • CURLOPT_POST
  • CURLOPT_POSTFIELDS

Files are downloaded preserving their name so you may want to check that, if you are downloading more files having the same name (either from the same, or from different servers)!

Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every request, as soon as a request finishes. The number of parallel requests to be constantly processed, at all times, can be set through the threads property. See also the pause_interval property.

Note that requests may not finish in the same order as initiated!

  1. // the callback function to be executed for each and every
  2. // request, as soon as a request finishes
  3. // the callback function receives as argument an object with 4 properties
  4. // (info, header, body and response)
  5. function mycallback($result{
  6.  
  7.     // everything went well at cURL level
  8.     if ($result->response[1== CURLE_OK{
  9.  
  10.         // if server responded with code 200 (meaning that everything went well)
  11.         // see http://httpstatus.es/ for a list of possible response codes
  12.         if ($result->info['http_code'== 200{
  13.  
  14.             // see all the returned data
  15.             print_r('<pre>');
  16.             print_r($result);
  17.  
  18.         // show the server's response code
  19.         else die('Server responded with code ' $result->info['http_code']);
  20.  
  21.     // something went wrong
  22.     // ($result still contains all data that could be gathered)
  23.     else die('cURL responded with: ' $result->response[0]);
  24.  
  25. }
  26.  
  27. // include the Zebra_cURL library
  28. require 'path/to/Zebra_cURL';
  29.  
  30. // instantiate the Zebra_cURL object
  31. $curl new Zebra_cURL();
  32.  
  33. // connect to the FTP server using the given credential, download a file to a given location and
  34. // execute the "mycallback" function for each request, as soon as it finishes
  35. $curl->ftp_download('ftp://somefile.ext''destination/path''username''password''mycallback');
Tags:
access: public
Parameters:
mixed $urls A single URL or an array of URLs to process.
string $path

The path to where to save the file(s) to.

If path is not pointing to a directory or is not writable, the library will trigger an error.

string $username (Optional) The username to be used to connect to the FTP server (if required).
string $password (Optional) The password to be used to connect to the FTP server (if required).
mixed $callback

(Optional) Callback function to be called as soon as a request finishes.

May be given as a string representing a name of an existing function, as an anonymous function created on the fly via create_function or via a closure.

The callback function receives as first argument an object with 4 properties as described below, while any further arguments passed to the ftp_download method will be passed as extra arguments to the callback function:

  • info - an associative array containing information about the request that just finished, as returned by PHP's curl_getinfo function;
  • headers - an associative array with 2 items:
- last_request an array with a single entry containing the request headers generated by the last request; so, remember, if there are redirects involved, there will be more requests made, but only information from the last one will be available; if explicitly disabled via the option method by setting CURLINFO_HEADER_OUT to 0 or FALSE, this will be an empty string;

- responses an empty string as it is not available for this method;

Unless disabled, each entry in the headers' array is an associative array in the form of property => value

  • body - an empty string as it is not available for this method;
  • response - the response given by the cURL library as an array with 2 entries: the first entry is the textual representation of the result's code, while second is the result's code itself; if the request was successful, these values will be array(CURLE_OK, 0); consult this list to see the possible values of this property;
If the callback function returns FALSE while cache is enabled, the library will not cache the respective request, making it easy to retry failed requests without having to clear all cache.

Top

method get()

void get ( mixed $urls , [ mixed $callback = ''] )

Performs an HTTP GET request to one or more URLs specified by the $urls argument and executes the callback function specified by the $callback argument for each and every request, as soon as a request finishes.

This method will automatically set the following options:

  • CURLINFO_HEADER_OUT - TRUE
  • CURLOPT_HEADER - TRUE
  • CURLOPT_HTTPGET - TRUE
  • CURLOPT_NOBODY - FALSE

...and will unset the following options:

  • CURLOPT_BINARYTRANSFER
  • CURLOPT_CUSTOMREQUEST
  • CURLOPT_FILE
  • CURLOPT_POST
  • CURLOPT_POSTFIELDS

Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every request, as soon as a request finishes. The number of parallel requests to be constantly processed, at all times, can be set through the threads property. See also the pause_interval property.

Note that requests may not finish in the same order as initiated!

  1. // the callback function to be executed for each and every
  2. // request, as soon as a request finishes
  3. // the callback function receives as argument an object with 4 properties
  4. // (info, header, body and response)
  5. function mycallback($result{
  6.  
  7.     // everything went well at cURL level
  8.     if ($result->response[1== CURLE_OK{
  9.  
  10.         // if server responded with code 200 (meaning that everything went well)
  11.         // see http://httpstatus.es/ for a list of possible response codes
  12.         if ($result->info['http_code'== 200{
  13.  
  14.             // see all the returned data
  15.             print_r('<pre>');
  16.             print_r($result);
  17.  
  18.         // show the server's response code
  19.         else die('Server responded with code ' $result->info['http_code']);
  20.  
  21.     // something went wrong
  22.     // ($result still contains all data that could be gathered)
  23.     else die('cURL responded with: ' $result->response[0]);
  24.  
  25. }
  26.  
  27. // include the Zebra_cURL library
  28. require 'path/to/Zebra_cURL';
  29.  
  30. // instantiate the Zebra_cURL object
  31. $curl new Zebra_cURL();
  32.  
  33. // cache results in the "cache" folder and for 3600 seconds (one hour)
  34. $curl->cache('cache'3600);
  35.  
  36. // let's fetch the RSS feeds of some popular websites
  37. // execute the "mycallback" function for each request, as soon as it finishes
  38. $curl->get(array(
  39.     'http://feeds.feedburner.com/alistapart/main',
  40.     'http://feeds.feedburner.com/TechCrunch',
  41.     'http://feeds.mashable.com/mashable',
  42. )'mycallback')
Tags:
access: public
Parameters:
mixed $urls A single URL or an array of URLs to process.
mixed $callback

(Optional) Callback function to be called as soon as a request finishes.

May be given as a string representing a name of an existing function, as an anonymous function created on the fly via create_function or via a closure.

The callback function receives as first argument an object with 4 properties as described below, while any further arguments passed to the get method will be passed as extra arguments to the callback function:

  • info - an associative array containing information about the request that just finished, as returned by PHP's curl_getinfo function;

  • headers - an associative array with 2 items:
- last_request an array with a single entry containing the request headers generated by the last request; so, remember, if there are redirects involved, there will be more requests made, but only information from the last one will be available;

- responses an array with one or more entries (if there are redirects involved) with the response headers of all the requests made;

Each entry in the headers' array is an associative array in the form of property => value

  • body - the response of the request (the content of the page at the URL).

Unless disabled via the constructor, all applicable characters will be converted to HTML entities via PHP's htmlentities function, so remember to use PHP's html_entity_decode function to do reverse this, if it's the case;

  • response - the response given by the cURL library as an array with 2 entries: the first entry is the textual representation of the result's code, while second is the result's code itself; if the request was successful, these values will be array(CURLE_OK, 0); consult this list to see the possible values of this property;
If the callback function returns FALSE while cache is enabled, the library will not cache the respective request, making it easy to retry failed requests without having to clear all cache.

Top

method header()

void header ( mixed $urls , [ mixed $callback = ''] )

Works exactly like the get method, the only difference being that this method will only return the headers, without body.

This method will automatically set the following options:

  • CURLINFO_HEADER_OUT - TRUE
  • CURLOPT_HEADER - TRUE
  • CURLOPT_HTTPGET - TRUE
  • CURLOPT_NOBODY - TRUE

...and will unset the following options:

  • CURLOPT_BINARYTRANSFER
  • CURLOPT_CUSTOMREQUEST
  • CURLOPT_FILE
  • CURLOPT_POST
  • CURLOPT_POSTFIELDS

Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every request, as soon as a request finishes. The number of parallel requests to be constantly processed, at all times, can be set through the threads property. See also the pause_interval property.

Note that requests may not finish in the same order as initiated!

  1. // the callback function to be executed for each and every
  2. // request, as soon as a request finishes
  3. // the callback function receives as argument an object with 4 properties
  4. // (info, header, body and response)
  5. function mycallback($result{
  6.  
  7.     // everything went well at cURL level
  8.     if ($result->response[1== CURLE_OK{
  9.  
  10.         // if server responded with code 200 (meaning that everything went well)
  11.         // see http://httpstatus.es/ for a list of possible response codes
  12.         if ($result->info['http_code'== 200{
  13.  
  14.             // see all the returned data
  15.             print_r('<pre>');
  16.             print_r($result);
  17.  
  18.         // show the server's response code
  19.         else die('Server responded with code ' $result->info['http_code']);
  20.  
  21.     // something went wrong
  22.     // ($result still contains all data that could be gathered)
  23.     else die('cURL responded with: ' $result->response[0]);
  24.  
  25. }
  26.  
  27. // include the Zebra_cURL library
  28. require 'path/to/Zebra_cURL';
  29.  
  30. // instantiate the Zebra_cURL object
  31. $curl new Zebra_cURL();
  32.  
  33. // process given URLs execute the "mycallback" function for each
  34. // request, as soon as it finishes
  35. $curl->header('http://www.somewebsite.com''mycallback');
Tags:
access: public
Parameters:
mixed $urls A single URL or an array of URLs to process.
mixed $callback

(Optional) Callback function to be called as soon as a request finishes.

May be given as a string representing a name of an existing function, as an anonymous function created on the fly via create_function or via a closure.

The callback function receives as first argument an object with 4 properties as described below, while any further arguments passed to the header method will be passed as extra arguments to the callback function:

  • info - an associative array containing information about the request that just finished, as returned by PHP's curl_getinfo function;

  • headers - an associative array with 2 items:
- last_request an array with a single entry containing the request headers generated by the last request; so, remember, if there are redirects involved, there will be more requests made, but only information from the last one will be available;

- responses an array with one or more entries (if there are redirects involved) with the response headers of all the requests made;

Each entry in the headers' array is an associative array in the form of property => value

  • body - an empty string as it is not available for this method;
  • response - the response given by the cURL library as an array with 2 entries: the first entry is the textual representation of the result's code, while second is the result's code itself; if the request was successful, these values will be array(CURLE_OK, 0); consult this list to see the possible values of this property;
If the callback function returns FALSE while cache is enabled, the library will not cache the respective request, making it easy to retry failed requests without having to clear all cache.

Top

method http_authentication()

void http_authentication ( [ string $username = ''] , [ string $password = ''] , [ string $type = CURLAUTH_ANY] )

Use this method to make requests to pages that require prior HTTP authentication.

  1. // the callback function to be executed for each and every
  2. // request, as soon as a request finishes
  3. // the callback function receives as argument an object with 4 properties
  4. // (info, header, body and response)
  5. function mycallback($result{
  6.  
  7.     // everything went well at cURL level
  8.     if ($result->response[1== CURLE_OK{
  9.  
  10.         // if server responded with code 200 (meaning that everything went well)
  11.         // see http://httpstatus.es/ for a list of possible response codes
  12.         if ($result->info['http_code'== 200{
  13.  
  14.             // see all the returned data
  15.             print_r('<pre>');
  16.             print_r($result);
  17.  
  18.         // show the server's response code
  19.         else die('Server responded with code ' $result->info['http_code']);
  20.  
  21.     // something went wrong
  22.     // ($result still contains all data that could be gathered)
  23.     else die('cURL responded with: ' $result->response[0]);
  24.  
  25. }
  26.  
  27. // include the Zebra_cURL library
  28. require 'path/to/Zebra_cURL';
  29.  
  30. // instantiate the Zebra_cURL object
  31. $curl new Zebra_cURL();
  32.  
  33. // prepare user name and password
  34. $curl->http_authentication('username''password');
  35.  
  36. // get content from a page that requires prior HTTP authentication
  37. $curl->get('http://www.some-page-requiring-prior-http-authentication.com''mycallback');

If you have to unset previously set values use

Tags:
access: public
Parameters:
string $username User name to be used for authentication.
string $password Password to be used for authentication.
string $type

(Optional) The HTTP authentication method(s) to use. The options are:

  • CURLAUTH_BASIC
  • CURLAUTH_DIGEST
  • CURLAUTH_GSSNEGOTIATE
  • CURLAUTH_NTLM
  • CURLAUTH_ANY
  • CURLAUTH_ANYSAFE

The bitwise | (or) operator can be used to combine more than one method. If this is done, cURL will poll the server to see what methods it supports and pick the best one.

CURLAUTH_ANY is an alias for CURLAUTH_BASIC | CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM.

CURLAUTH_ANYSAFE is an alias for CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM.

Default is CURLAUTH_ANY.

Top

method option()

void option ( mixed $option , [ mixed $value = ''] )

Allows you to set one or more cURL options.

  1. // include the Zebra_cURL library
  2. require 'path/to/Zebra_cURL';
  3.  
  4. // instantiate the Zebra_cURL object
  5. $curl new Zebra_cURL();
  6.  
  7. // setting a single option
  8. $curl->option(CURLOPT_CONNECTTIMEOUT10);
  9.  
  10. // setting multiple options at once
  11. $curl->option(array(
  12.     CURLOPT_TIMEOUT         =>  10,
  13.     CURLOPT_CONNECTTIMEOUT  =>  10,
  14. ));
  15.  
  16. // make a request here...
Tags:
access: public
Parameters:
mixed $option

A single option for which to set a value, or an associative array in the form of option => value (in case of an array, the $value argument will be disregarded).

Setting a value to null will "unset" that option.

mixed $value

(Optional) If the $option argument is not an array, then this argument represents the value to be set for the respective option. If the $option argument is an array, then the value of this argument will be ignored.

Setting a value to null will "unset" that option.

Top

method post()

void post ( mixed $urls , [ mixed $callback = ''] )

Performs an HTTP POST request to one or more URLs with the POST data as specified by the $urls argument, and executes the callback function specified by the $callback argument for each and every request, as soon as a request finishes.

This method will automatically set the following options:

  • CURLINFO_HEADER_OUT - TRUE
  • CURLOPT_HEADER - TRUE
  • CURLOPT_NOBODY - FALSE
  • CURLOPT_POST - TRUE
  • CURLOPT_POSTFIELDS - the POST data

...and will unset the following options:

  • CURLOPT_BINARYTRANSFER
  • CURLOPT_CUSTOMREQUEST
  • CURLOPT_HTTPGET - TRUE
  • CURLOPT_FILE

Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every request, as soon as a request finishes. The number of parallel requests to be constantly processed, at all times, can be set through the threads property. See also the pause_interval property.

Note that requests may not finish in the same order as initiated!

  1. // the callback function to be executed for each and every
  2. // request, as soon as a request finishes
  3. // the callback function receives as argument an object with 4 properties
  4. // (info, header, body and response)
  5. function mycallback($result{
  6.  
  7.     // everything went well at cURL level
  8.     if ($result->response[1== CURLE_OK{
  9.  
  10.         // if server responded with code 200 (meaning that everything went well)
  11.         // see http://httpstatus.es/ for a list of possible response codes
  12.         if ($result->info['http_code'== 200{
  13.  
  14.             // see all the returned data
  15.             print_r('<pre>');
  16.             print_r($result);
  17.  
  18.         // show the server's response code
  19.         else die('Server responded with code ' $result->info['http_code']);
  20.  
  21.     // something went wrong
  22.     // ($result still contains all data that could be gathered)
  23.     else die('cURL responded with: ' $result->response[0]);
  24.  
  25. }
  26.  
  27. // include the Zebra_cURL library
  28. require 'path/to/Zebra_cURL';
  29.  
  30. // instantiate the Zebra_cURL object
  31. $curl new Zebra_cURL();
  32.  
  33. // do a POST and execute the "mycallback" function for each
  34. // request, as soon as it finishes
  35. $curl->post(array(
  36.     'http://www.somewebsite.com'  =>  array(
  37.         'data_1'  =>  'value 1',
  38.         'data_2'  =>  'value 2',
  39.     ),
  40. )'mycallback');
  41.  
  42. // note that we're also uploading a file this time
  43. // and note that we're prefixing the file name with @
  44. $curl->post(array(
  45.     'http://www.somewebsite.com'  =>  array(
  46.         'data_1'  =>  'value 1',
  47.         'data_2'  =>  'value 2',
  48.         'data_3'  =>  '@absolute/path/to/file.ext',
  49. )'mycallback');
Tags:
access: public
Parameters:
mixed $urls

An associative array in the form of url => post-data, where "post-data" is an associative array in the form of name => value.

"post-data" can also be an arbitrary string - useful if you want to send raw data (like a JSON)

To post a file, prepend the filename with @ and use the full path. The file type can be explicitly specified by following the filename with the type in the format ';type=mimetype'. You should always specify the mime type as most of the times cURL will send the wrong mime type...

The Content-Type header will be set to multipart/form-data.

mixed $callback

(Optional) Callback function to be called as soon as a request finishes.

May be given as a string representing a name of an existing function, as an anonymous function created on the fly via create_function or via a closure.

The callback function receives as first argument an object with 4 properties as described below, while any further arguments passed to the post method will be passed as extra arguments to the callback function:

  • info - an associative array containing information about the request that just finished, as returned by PHP's curl_getinfo function;

  • headers - an associative array with 2 items:
- last_request an array with a single entry containing the request headers generated by the last request; so, remember, if there are redirects involved, there will be more requests made, but only information from the last one will be available; if explicitly disabled via the option method by setting CURLINFO_HEADER_OUT to 0 or FALSE, this will be an empty string;

- responses an array with one or more entries (if there are redirects involved) with the response headers of all the requests made; if explicitly disabled via the option method by setting CURLOPT_HEADER to 0 or FALSE, this will be an empty string;

Unless disabled, each entry in the headers' array is an associative array in the form of property => value

  • body - the response of the request (the content of the page at the URL).

Unless disabled via the constructor, all applicable characters will be converted to HTML entities via PHP's htmlentities function, so remember to use PHP's html_entity_decode function to do reverse this, if it's the case;

If "body" is explicitly disabled via the option method by setting CURLOPT_NOBODY to 0 or FALSE, this will be an empty string;

  • response - the response given by the cURL library as an array with 2 entries: the first entry is the textual representation of the result's code, while second is the result's code itself; if the request was successful, these values will be array(CURLE_OK, 0); consult this list to see the possible values of this property;
If the callback function returns FALSE while cache is enabled, the library will not cache the respective request, making it easy to retry failed requests without having to clear all cache.

Top

method proxy()

void proxy ( string $proxy , [ string $port = 80] , [ string $username = ''] , [ string $password = ''] )

Instruct the library to tunnel all requests through a proxy server.

  1. // the callback function to be executed for each and every
  2. // request, as soon as a request finishes
  3. function mycallback($result{
  4.  
  5.     // everything went well at cURL level
  6.     if ($result->response[1== CURLE_OK{
  7.  
  8.         // if server responded with code 200 (meaning that everything went well)
  9.         // see http://httpstatus.es/ for a list of possible response codes
  10.         if ($result->info['http_code'== 200{
  11.  
  12.             // see all the returned data
  13.             print_r('<pre>');
  14.             print_r($result);
  15.  
  16.         // show the server's response code
  17.         else die('Server responded with code ' $result->info['http_code']);
  18.  
  19.     // something went wrong
  20.     // ($result still contains all data that could be gathered)
  21.     else die('cURL responded with: ' $result->response[0]);
  22.  
  23. }
  24.  
  25. // include the Zebra_cURL library
  26. require 'path/to/Zebra_cURL';
  27.  
  28. // instantiate the class
  29. $curl new Zebra_cURL();
  30.  
  31. // connect to a proxy server
  32. // (that's a random one i got from http://www.hidemyass.com/proxy-list/)
  33. $curl->proxy('187.63.32.250''3128');
  34.  
  35. // fetch a page
  36. $curl->get('http://www.somewebsite.com/''mycallback');
Tags:
access: public
Parameters:
string $proxy

The HTTP proxy to tunnel requests through.

Can be an URL or an IP address.

This option can also be set using the option method and setting CURLOPT_PROXY option to the desired value.

Setting this argument to FALSE will "unset" all the proxy-related options.

string $port

(Optional) The port number of the proxy to connect to.

Default is 80.

This option can also be set using the option method and setting CURLOPT_PROXYPORT option to the desired value.

string $username

(Optional) The username to be used for the connection to the proxy (if required by the proxy)

Default is "" (an empty string)

The username and the password can also be set using the option method and setting CURLOPT_PROXYUSERPWD option to the desired value formatted like [username]:[password]. .

string $password

(Optional) The password to be used for the connection to the proxy (if required by the proxy)

Default is "" (an empty string)

The username and the password can also be set using the option method and setting CURLOPT_PROXYUSERPWD option to the desired value formatted like [username]:[password]. .

Top

method put()

void put ( mixed $urls , [ mixed $callback = ''] )

Performs an HTTP PUT request to one or more URLs with the POST data as specified by the $urls argument, and executes the callback function specified by the $callback argument for each and every request, as soon as a request finishes.

This method will automatically set the following options:

  • CURLINFO_HEADER_OUT - TRUE
  • CURLOPT_CUSTOMREQUEST - "PUT"
  • CURLOPT_HEADER - TRUE
  • CURLOPT_NOBODY - FALSE
  • CURLOPT_POST - FALSE
  • CURLOPT_POSTFIELDS - the POST data

...and will unset the following options:

  • CURLOPT_BINARYTRANSFER
  • CURLOPT_HTTPGET - TRUE
  • CURLOPT_FILE

Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every request, as soon as a request finishes. The number of parallel requests to be constantly processed, at all times, can be set through the threads property. See also the pause_interval property.

Note that requests may not finish in the same order as initiated!

  1. // the callback function to be executed for each and every
  2. // request, as soon as a request finishes
  3. // the callback function receives as argument an object with 4 properties
  4. // (info, header, body and response)
  5. function mycallback($result{
  6.  
  7.     // everything went well at cURL level
  8.     if ($result->response[1== CURLE_OK{
  9.  
  10.         // if server responded with code 200 (meaning that everything went well)
  11.         // see http://httpstatus.es/ for a list of possible response codes
  12.         if ($result->info['http_code'== 200{
  13.  
  14.             // see all the returned data
  15.             print_r('<pre>');
  16.             print_r($result);
  17.  
  18.         // show the server's response code
  19.         else die('Server responded with code ' $result->info['http_code']);
  20.  
  21.     // something went wrong
  22.     // ($result still contains all data that could be gathered)
  23.     else die('cURL responded with: ' $result->response[0]);
  24.  
  25. }
  26.  
  27. // include the Zebra_cURL library
  28. require 'path/to/Zebra_cURL';
  29.  
  30. // instantiate the Zebra_cURL object
  31. $curl new Zebra_cURL();
  32.  
  33. // do a PUT and execute the "mycallback" function for each
  34. // request, as soon as it finishes
  35. $curl->put(array(
  36.     'http://www.somewebsite.com'  =>  array(
  37.         'data_1'  =>  'value 1',
  38.         'data_2'  =>  'value 2',
  39.     ),
  40. )'mycallback');
Tags:
since: 1.3.3
access: public
Parameters:
mixed $urls

An associative array in the form of url => put-data, where "put-data" is an associative array in the form of name => value.

"put-data" can also be an arbitrary string - useful if you want to send raw data (like a JSON)

To put a file, prepend the filename with @ and use the full path. The file type can be explicitly specified by following the filename with the type in the format ';type=mimetype'. You should always specify the mime type as most of the times cURL will send the wrong mime type...

The Content-Type header will be set to multipart/form-data.

mixed $callback

(Optional) Callback function to be called as soon as a request finishes.

May be given as a string representing a name of an existing function, as an anonymous function created on the fly via create_function or via a closure.

The callback function receives as first argument an object with 4 properties as described below, while any further arguments passed to the put method will be passed as extra arguments to the callback function:

  • info - an associative array containing information about the request that just finished, as returned by PHP's curl_getinfo function;

  • headers - an associative array with 2 items:
- last_request an array with a single entry containing the request headers generated by the last request; so, remember, if there are redirects involved, there will be more requests made, but only information from the last one will be available; if explicitly disabled via the option method by setting CURLINFO_HEADER_OUT to 0 or FALSE, this will be an empty string;

- responses an array with one or more entries (if there are redirects involved) with the response headers of all the requests made; if explicitly disabled via the option method by setting CURLOPT_HEADER to 0 or FALSE, this will be an empty string;

Unless disabled, each entry in the headers' array is an associative array in the form of property => value

  • body - the response of the request (the content of the page at the URL).

Unless disabled via the constructor, all applicable characters will be converted to HTML entities via PHP's htmlentities function, so remember to use PHP's html_entity_decode function to do reverse this, if it's the case;

If "body" is explicitly disabled via the option method by setting CURLOPT_NOBODY to 0 or FALSE, this will be an empty string;

  • response - the response given by the cURL library as an array with 2 entries: the first entry is the textual representation of the result's code, while second is the result's code itself; if the request was successful, these values will be array(CURLE_OK, 0); consult this list to see the possible values of this property;
If the callback function returns FALSE while cache is enabled, the library will not cache the respective request, making it easy to retry failed requests without having to clear all cache.

Top

method queue()

void queue ( )

Instructs the library to queue requests rather than processing them right away. Useful for grouping different types of requests and treat them as a single request.

Until start method is called, all calls to delete, download, ftp_download, get, header, post and put methods will queue up rather than being executed right away. Once the start method is called, all queued requests will be processed while values of threads and pause_interval properties will still apply.

  1. // the callback function to be executed for each and every
  2. // request, as soon as a request finishes
  3. // the callback function receives as argument an object with 4 properties
  4. // (info, header, body and response)
  5. function mycallback($result{
  6.  
  7.     // everything went well at cURL level
  8.     if ($result->response[1== CURLE_OK{
  9.  
  10.         // if server responded with code 200 (meaning that everything went well)
  11.         // see http://httpstatus.es/ for a list of possible response codes
  12.         if ($result->info['http_code'== 200{
  13.  
  14.             // see all the returned data
  15.             print_r('<pre>');
  16.             print_r($result);
  17.  
  18.         // show the server's response code
  19.         else die('Server responded with code ' $result->info['http_code']);
  20.  
  21.     // something went wrong
  22.     // ($result still contains all data that could be gathered)
  23.     else die('cURL responded with: ' $result->response[0]);
  24.  
  25. }
  26.  
  27. // include the Zebra_cURL library
  28. require 'path/to/Zebra_cURL';
  29.  
  30. // instantiate the Zebra_cURL object
  31. $curl new Zebra_cURL();
  32.  
  33. // queue requests - useful for grouping different types of requests
  34. // in this example, when the "start" method is called, we'll execute
  35. // the "get" and the "post" requests simultaneously as if it was a
  36. // single request
  37. $curl->queue();
  38.  
  39. // do a POST and execute the "mycallback" function for each
  40. // request, as soon as it finishes
  41. $curl->post(array(
  42.     'http://www.somewebsite.com'  =>  array(
  43.         'data_1'  =>  'value 1',
  44.         'data_2'  =>  'value 2',
  45.     ),
  46. )'mycallback');
  47.  
  48. // let's fetch the RSS feeds of some popular websites
  49. // execute the "mycallback" function for each request, as soon as it finishes
  50. $curl->get(array(
  51.     'http://feeds.feedburner.com/alistapart/main',
  52.     'http://feeds.feedburner.com/TechCrunch',
  53.     'http://feeds.mashable.com/mashable',
  54. )'mycallback')
  55.  
  56. // execute queued requests
  57. $curl->start();
Tags:
since: 1.3.0
access: public
Top

method scrap()

mixed scrap ( string $url , [ boolean $body_only = false] )

A shorthand for making a single get request without the need of a callback function

  1. // include the Zebra_cURL library
  2. require 'path/to/Zebra_cURL';
  3.  
  4. // instantiate the class
  5. $curl new Zebra_cURL();
  6.  
  7. // get page's content only
  8. $content $curl->get('https://www.somewebsite.com/'true);
  9.  
  10. // print that to screen
  11. echo $content;
  12.  
  13. // get everything we can about the page
  14. $content $curl->get('https://www.somewebsite.com/');
  15.  
  16. // print that to screen
  17. print_r('<pre>');
  18. print_r($content);
Tags:
return: Returns the scrapped page's content, when $body_only is set to TRUE, or an object with properties as described for the $callback argument of the get method.
since: 1.3.3
Parameters:
string $url An URL to fetch
boolean $body_only

(Optional) When set to TRUE, will instruct the method to return only the page's content, without info, headers, responses, etc.

When set to FALSE, will instruct the method to return everything it can about the scrapped page, as an object with properties as described for the $callback argument of the get method.

Default is FALSE.

Top

method ssl()

void ssl ( [ boolean $verify_peer = true] , [ integer $verify_host = 2] , [ mixed $file = false] , [ mixed $path = false] )

Requests made to HTTPS servers sometimes require additional configuration, depending on the server. Most of the times the defaults set by the library will get you through, but if defaults are not working, you can set specific options using this method.

  1. // include the Zebra_cURL library
  2. require 'path/to/Zebra_cURL';
  3.  
  4. // instantiate the class
  5. $curl new Zebra_cURL();
  6.  
  7. // instruct the library to verify peer's SSL certificate
  8. // (ignored if request is not made through HTTPS)
  9. $curl->ssl(true);
  10.  
  11. // fetch a page
  12. $curl->get('https://www.somewebsite.com/'create_function('$result''print_r("<pre>"); print_r($result);'));
Tags:
access: public
Parameters:
boolean $verify_peer

(Optional) Should the peer's certificate be verified by cURL?

Default is TRUE.

This option can also be set using the option method and setting CURLOPT_SSL_VERIFYPEER option to the desired value.

integer $verify_host

(Optional) Specifies whether or not to check the existence of a common name in the SSL peer certificate and that it matches with the provided hostname.

  • 1 to check the existence of a common name in the SSL peer certificate;
  • 2 to check the existence of a common name and also verify that it matches the hostname provided; in production environments the value of this option should be kept at 2;

Default is 2

Support for value 1 removed in cURL 7.28.1

This option can also be set using the option method and setting CURLOPT_SSL_VERIFYHOST option to the desired value.

mixed $file

(Optional) An absolute path to a file holding one or more certificates to verify the peer with. This only makes sense if CURLOPT_SSL_VERIFYPEER is set to TRUE.

Default is FALSE.

This option can also be set using the option method and setting CURLOPT_CAINFO option to the desired value.

mixed $path

(Optional) An absolute path to a directory that holds multiple CA certificates. This only makes sense if CURLOPT_SSL_VERIFYPEER is set to TRUE.

Default is FALSE.

This option can also be set using the option method and setting CURLOPT_CAPATH option to the desired value.

Top

method start()

void start ( )

Executes queued requests.

See queue method for more information.

Tags:
since: 1.3.0
access: public
Top