/Zebra_cURL.php

Large files files are truncated, but you can click here to view the full file

<?php

/**
 *  Zebra_cURL, a high performance PHP cURL library
 *
 *  Zebra_cURL is a high performance PHP library acting as a wrapper to PHP's {@link http://www.php.net/manual/en/book.curl.php 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 {@link http://www.php.net/manual/en/curl.installation.php 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
 *  {@link http://www.php.net/manual/en/function.error-reporting.php E_ALL}.
 *
 *  Visit {@link http://stefangabos.ro/php-libraries/zebra-curl/} for more information.
 *
 *  For more resources visit {@link http://stefangabos.ro/}
 *
 *  @author     Stefan Gabos <contact@stefangabos.ro>
 *  @version    1.1.0 (last revision: March 22, 2014)
 *  @copyright  (c) 2014 Stefan Gabos
 *  @license    http://www.gnu.org/licenses/lgpl-3.0.txt GNU LESSER GENERAL PUBLIC LICENSE
 *  @package    Zebra_cURL
 */

class Zebra_cURL {

    /**
     *  The number of parallel, asynchronous, requests to be processed by the library at once.
     *
     *  <code>
     *  // allow execution of 30 simultaneous threads
     *  $curl->threads = 30;
     *  </code>
     *
     *  Note that the library will keep this number of parallel threads running at all times (unless, of course, there
     *  are less remaining URLs to process); it's doing this by starting a new thread as soon as another one finishes,
     *  instead of waiting for each batch to finish, and so on, until there are no more URLs to process, and thus
     *  greatly decreasing execution time.
     *
     *  Default is 10.
     *
     *  @var integer
     */
    public $threads;

    /**
     * Default value is TRUE, can be changed by giving the constructor parameter value false.
     *
     * Used by the {@link _process()} method to determine if we run response body through PHP's htmlentities function.
     *
     * @access private
     *
     */
    private $_htmlentities;

    /**
     *  An associative array linked with all the resources, used to store original URL and file pointer resources, used
     *  for streaming downloads.
     *
     *  @var array
     *
     *  @access private
     */
    private $_info;

    /**
     *  Used by the {@link _process()} method to keep track of URLs that need to be processed.
     *
     *  @access private
     */
    private $_queue;

    /**
     *  The cURL multi handle
     *
     *  @var resource
     *
     *  @access private
     */
    private $_multi_handle;

    /**
     *  Possible values of the "result" attribute in the object passed to the callback function.
     *
     *  @var array
     *
     *  @access private
     */
    private $_response_messages = array(
        0   =>  'CURLE_OK',
        1   =>  'CURLE_UNSUPPORTED_PROTOCOL',
        2   =>  'CURLE_FAILED_INIT',
        3   =>  'CURLE_URL_MALFORMAT',
        4   =>  'CURLE_URL_MALFORMAT_USER',
        5   =>  'CURLE_COULDNT_RESOLVE_PROXY',
        6   =>  'CURLE_COULDNT_RESOLVE_HOST',
        7   =>  'CURLE_COULDNT_CONNECT',
        8   =>  'CURLE_FTP_WEIRD_SERVER_REPLY',
        9   =>  'CURLE_REMOTE_ACCESS_DENIED',
        11  =>  'CURLE_FTP_WEIRD_PASS_REPLY',
        13  =>  'CURLE_FTP_WEIRD_PASV_REPLY',
        14  =>  'CURLE_FTP_WEIRD_227_FORMAT',
        15  =>  'CURLE_FTP_CANT_GET_HOST',
        17  =>  'CURLE_FTP_COULDNT_SET_TYPE',
        18  =>  'CURLE_PARTIAL_FILE',
        19  =>  'CURLE_FTP_COULDNT_RETR_FILE',
        21  =>  'CURLE_QUOTE_ERROR',
        22  =>  'CURLE_HTTP_RETURNED_ERROR',
        23  =>  'CURLE_WRITE_ERROR',
        25  =>  'CURLE_UPLOAD_FAILED',
        26  =>  'CURLE_READ_ERROR',
        27  =>  'CURLE_OUT_OF_MEMORY',
        28  =>  'CURLE_OPERATION_TIMEDOUT',
        30  =>  'CURLE_FTP_PORT_FAILED',
        31  =>  'CURLE_FTP_COULDNT_USE_REST',
        33  =>  'CURLE_RANGE_ERROR',
        34  =>  'CURLE_HTTP_POST_ERROR',
        35  =>  'CURLE_SSL_CONNECT_ERROR',
        36  =>  'CURLE_BAD_DOWNLOAD_RESUME',
        37  =>  'CURLE_FILE_COULDNT_READ_FILE',
        38  =>  'CURLE_LDAP_CANNOT_BIND',
        39  =>  'CURLE_LDAP_SEARCH_FAILED',
        41  =>  'CURLE_FUNCTION_NOT_FOUND',
        42  =>  'CURLE_ABORTED_BY_CALLBACK',
        43  =>  'CURLE_BAD_FUNCTION_ARGUMENT',
        45  =>  'CURLE_INTERFACE_FAILED',
        47  =>  'CURLE_TOO_MANY_REDIRECTS',
        48  =>  'CURLE_UNKNOWN_TELNET_OPTION',
        49  =>  'CURLE_TELNET_OPTION_SYNTAX',
        51  =>  'CURLE_PEER_FAILED_VERIFICATION',
        52  =>  'CURLE_GOT_NOTHING',
        53  =>  'CURLE_SSL_ENGINE_NOTFOUND',
        54  =>  'CURLE_SSL_ENGINE_SETFAILED',
        55  =>  'CURLE_SEND_ERROR',
        56  =>  'CURLE_RECV_ERROR',
        58  =>  'CURLE_SSL_CERTPROBLEM',
        59  =>  'CURLE_SSL_CIPHER',
        60  =>  'CURLE_SSL_CACERT',
        61  =>  'CURLE_BAD_CONTENT_ENCODING',
        62  =>  'CURLE_LDAP_INVALID_URL',
        63  =>  'CURLE_FILESIZE_EXCEEDED',
        64  =>  'CURLE_USE_SSL_FAILED',
        65  =>  'CURLE_SEND_FAIL_REWIND',
        66  =>  'CURLE_SSL_ENGINE_INITFAILED',
        67  =>  'CURLE_LOGIN_DENIED',
        68  =>  'CURLE_TFTP_NOTFOUND',
        69  =>  'CURLE_TFTP_PERM',
        70  =>  'CURLE_REMOTE_DISK_FULL',
        71  =>  'CURLE_TFTP_ILLEGAL',
        72  =>  'CURLE_TFTP_UNKNOWNID',
        73  =>  'CURLE_REMOTE_FILE_EXISTS',
        74  =>  'CURLE_TFTP_NOSUCHUSER',
        75  =>  'CURLE_CONV_FAILED',
        76  =>  'CURLE_CONV_REQD',
        77  =>  'CURLE_SSL_CACERT_BADFILE',
        78  =>  'CURLE_REMOTE_FILE_NOT_FOUND',
        79  =>  'CURLE_SSH',
        80  =>  'CURLE_SSL_SHUTDOWN_FAILED',
        81  =>  'CURLE_AGAIN',
        82  =>  'CURLE_SSL_CRL_BADFILE',
        83  =>  'CURLE_SSL_ISSUER_ERROR',
        84  =>  'CURLE_FTP_PRET_FAILED',
        84  =>  'CURLE_FTP_PRET_FAILED',
        85  =>  'CURLE_RTSP_CSEQ_ERROR',
        86  =>  'CURLE_RTSP_SESSION_ERROR',
        87  =>  'CURLE_FTP_BAD_FILE_LIST',
        88  =>  'CURLE_CHUNK_FAILED',
    );

    /**
     *  Constructor of the class.
     *
     *  Below is the list of default options set for each request, unless these options are specifically changed by one
     *  of the methods or via the {@link option()} method:
     *
     *  -   <b>CURLINFO_HEADER_OUT</b>      -   <b>TRUE</b>; 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; <i>you should leave this
     *                                          unaltered!</i>;
     *
     *  -   <b>CURLOPT_AUTOREFERER</b>      -   <b>TRUE</b>; automatically set the <i>Referer:</i> field in requests
     *                                          where it follows a <i>Location:</i> redirect;
     *
     *  -   <b>CURLOPT_COOKIEFILE</b>       -   <b>empty string</b>; no cookies are loaded, but cookie handling is still
     *                                          enabled
     *
     *  -   <b>CURLOPT_CONNECTTIMEOUT</b>   -   <b>10</b>; the number of seconds to wait while trying to connect. use 0
     *                                          to wait indefinitely;
     *
     *  -   <b>CURLOPT_FOLLOWLOCATION</b>   -   <b>TRUE</b>; automatically follow any <i>Location:</i> header that the
     *                                          server sends as part of the HTTP header (note this is recursive, PHP will
     *                                          follow as many <i>Location:</i> headers as specified by the value of
     *                                          CURLOPT_MAXREDIRS - see below);
     *
     *  -   <b>CURLOPT_HEADER</b>           -   <b>TRUE</b>; 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; <i>you should leave this
     *                                          unaltered!</i>;
     *
     *  -   <b>CURLOPT_MAXREDIRS</b>        -   <b>50</b>; the maximum amount of HTTP redirections to follow; used
     *                                          together with CURLOPT_FOLLOWLOCATION;
     *
     *  -   <b>CURLOPT_RETURNTRANSFER</b>   -   <b>TRUE</b>; 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; <b>this will
     *                                          always be TRUE and cannot be changed!</b>;
     *
     *  -   <b>CURLOPT_SSL_VERIFYHOST</b>   -   <b>2</b>; 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 {@link ssl()};
     *
     *  -   <b>CURLOPT_SSL_VERIFYPEER</b>   -   <b>FALSE</b>; stop cURL from verifying the peer's certificate (which
     *                                          would most likely cause the request to fail). see also {@link ssl()};
     *
     *  -   <b>CURLOPT_TIMEOUT</b>          -   <b>10</b>; the maximum number of seconds to allow cURL functions to
     *                                          execute;
     *
     *  -   <b>CURLOPT_USERAGENT</b>        -   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
     *
     *  @param  boolean $htmlentities           Instructs the script whether the response body returned by the {@link get()}
     *                                          and {@link post()} methods should be run through PHP's
     *                                          {@link http://php.net/manual/en/function.htmlentities.php htmlentities()}
     *                                          function.
     *
     *  @return void
     */
    function __construct($htmlentities = true)
    {

        // if the cURL extension is not available, trigger an error and stop execution
        if (!extension_loaded('curl')) trigger_error('php_curl extension is not loaded!', E_USER_ERROR);

        // set defaults for accessing HTTPS servers
        $this->ssl();

        // initialize some internal variables
        $this->_multi_handle = false;
        $this->_info = array();

        // caching is disabled by default
        $this->cache(false);

        // the default number of parallel, asynchronous, requests to be processed by the library at once.
        $this->threads = 10;

        // by default, run htmlentities() on the response body
        $this->_htmlentities = $htmlentities;

    }

    /**
     *  Use this method to enable caching for {@link get() get} and {@link header() header} requests.
     *
     *  <i>Caching is only used for {@link get() get} and {@link header() header} requests, and will be ignored for other
     *  request types even if it is enabled!</i>
     *
     *  <i>Caching is disabled by default!</i>
     *
     *  <code>
     *  // the callback function to be executed for each and every
     *  // request, as soon as a request finishes
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  function mycallback($result) {
     *
     *      // everything went well
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // see all the returned data
     *          print_r('<pre>');
     *          print_r($result);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else die('An error occurred: ' . $result->response[1]);
     *
     *  }
     *
     *  // include the Zebra_cURL library
     *  require 'path/to/Zebra_cURL';
     *
     *  // instantiate the Zebra_cURL object
     *  $curl = new Zebra_cURL();
     *
     *  // cache results in the "cache" folder and for 86400 seconds (24 hours)
     *  $curl->cache('cache', 86400);
     *
     *  // let's fetch the RSS feeds of some popular websites
     *  // execute the "mycallback" function for each request, as soon as it finishes
     *  $curl->get(array(
     *      'http://feeds.feedburner.com/alistapart/main',
     *      'http://feeds.feedburner.com/TechCrunch',
     *      'http://feeds.mashable.com/mashable',
     *  ), 'mycallback')
     *  </code>
     *
     *  @param  string      $path       The path where the cache files to be stored.
     *
     *                                  Setting this to FALSE will disable caching.
     *
     *                                  <i>Unless set to FALSE this must point to a writable directory or an error will
     *                                  be triggered!</i>
     *
     *  @param  integer     $lifetime   (Optional) The number of seconds after which cache will be considered as expired.
     *
     *                                  Default is 3600.
     *
     *  @param  boolean     $compress   (Optional) If set to TRUE, cache files will be
     *                                  {@link http://php.net/manual/ro/function.gzcompress.php gzcompress}-ed  so that
     *                                  they occupy less disk space.
     *
     *                                  Default is TRUE.
     *
     *  @param  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).
     *
     *  @return null
     */
    public function cache($path, $lifetime = 3600, $compress = true, $chmod = 0755)
    {

        // if we have to enable caching
        if ($path != false)

            // store cache-related properties
            $this->cache = array(
                'path'      =>  $path,
                'lifetime'  =>  $lifetime,
                'chmod'     =>  $chmod,
                'compress'  =>  $compress,
            );

        // if we have to disable caching, disable it
        else $this->cache = false;

    }

    /**
     *  Sets the path and name of the file to save to / retrieve cookies from, for each accessed URL. (cookie name/data
     *  will be stored in this file on a per-domain basis). Important when cookies need to stored/restored to maintain
     *  status/session of the request(s) made to the same domain(s).
     *
     *  This method will automatically set the <b>CURLOPT_COOKIEJAR</b> and <b>CURLOPT_COOKIEFILE</b> options.
     *
     *  @param  string      $path   The path to a file to save to / retrieve cookies from, for each accessed URL.
     *
     *                              If file does not exist the library will attempt to create it and if it is unable to
     *                              create it will trigger an error.
     *
     *  @param  boolean     $keep   (Optional)  By default, the file to save to / retrieve cookies from is deleted when
     *                              script execution finishes. If you want the file to be preserved, set this argument to
     *                              TRUE.
     *
     *                              Default is FALSE.
     *
     *  @return null
     */
    public function cookies($path, $keep = false)
    {
        // file does not exist
        if (!is_file($path)) {

            // attempt to create it
            if (!($handle = fopen($path, 'a')))

                // if file could not be created, trigger an error
                trigger_error('File "' . $path . '" for storing cookies could not be found nor could it automatically be created! Make sure either that the path to the file points to a writable directory, or create the file yourself and make it writable.', E_USER_ERROR);

            // if file could be create, release handle
            fclose($handle);

        }

        // set these options
        $this->option(array(
            CURLOPT_COOKIEJAR   =>  $path,
            CURLOPT_COOKIEFILE  =>  $path,
        ));

    }

    /**
     *  Downloads one or more files from one or more URLs specified by the <i>$url</i> argument, saves the downloaded
     *  files (with their original name) to the path specified by the <i>$destination_path</i>, and executes the callback
     *  function specified by the <i>$callback</i> argument for each and every request, as soon as each 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 <b>CURLOPT_BINARYTRANSFER</b> option to TRUE, so you might want to change
     *  this back to FALSE/0 or "unset" it using the {@link option()} method, before making a {@link get()}, {@link header()}
     *  or {@link post()} request.
     *
     *  <i>Files are downloaded preserving their name so you may run into trouble when trying to download more images
     *  having the same name (either from the same, or different servers)!</i>
     *
     *  <i>Multiple requests are made asynchronously, in parallel, and the callback function is called for each and every
     *  request, as soon as each request finishes. The number of parallel requests to be made at once can be set through
     *  the {@link threads} property.</i>
     *
     *  <i>Note that in case of multiple URLs, requests may not finish in the same order as initiated!</i>
     *
     *  <code>
     *  // the callback function to be executed for each and every
     *  // request, as soon as a request finishes
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  function mycallback($result) {
     *
     *      // everything went well
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // see all the returned data
     *          print_r('<pre>');
     *          print_r($result);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else die('An error occured: ' . $result->response[1]);
     *
     *  }
     *
     *  // include the Zebra_cURL library
     *  require 'path/to/Zebra_cURL';
     *
     *  // instantiate the Zebra_cURL object
     *  $curl = new Zebra_cURL();
     *
     *  // download 2 images from 2 different websites, and
     *  // execute the "mycallback" function for each request, as soon as it finishes
     *  $curl->download(array(
     *      'http://www.somewebsite.com/images/alpha.jpg',
     *      'http://www.otherwebsite.com/images/omega.jpg',
     *  ), 'destination/path/', 'mycallback');
     *  </code>
     *
     *  @param  mixed   $url                A single or an array of URLs to process.
     *
     *  @param  string  $destination_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.
     *
     *  @param  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 {@link http://www.php.net/manual/ro/function.create-function.php
     *                                      create_function} or, as of PHP 5.3.0, via a {@link http://www.php.net/manual/ro/function.create-function.php
     *                                      closure}.
     *
     *                                      The callback function receives as first argument <b>an object</b> with <b>4
     *                                      properties</b> as described below, while any further arguments passed to the
     *                                      {@link download} method will be passed as extra arguments to the callback function:
     *
     *                                      -   <b>info</b>     -   an associative array containing information about the
     *                                                              request that just finished, as returned by PHP's
     *                                                              {@link http://php.net/manual/en/function.curl-getinfo.php curl_getinfo()}
     *                                                              function; there's also an extra entry called <i>original_url</i>
     *                                                              because, as curl_getinfo() only returns information
     *                                                              about the <b>last</b> request, the original URL may
     *                                                              be lost otherwise.
     *
     *                                      -   <b>headers</b>  -   an associative array with 2 items:
     *
     *                                                              <b>- last_request</b> an array with a single entry
     *                                                              containing the request headers generated by <i>the
     *                                                              last request</i>; 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 {@link option()} method
     *                                                              by setting <b>CURLINFO_HEADER_OUT</b> to 0 or FALSE,
     *                                                              this will be an empty string;
     *
     *                                                              <b>- responses</b> 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 {@link option()} method by setting
     *                                                              <b>CURLOPT_HEADER</b> to 0 or FALSE, this will be an
     *                                                              empty string;
     *
     *                                                              <i>Unless disabled, each entry in the headers' array
     *                                                              is an associative array in the form of property =>
     *                                                              value</i>
     *
     *                                      -   <b>body</b>     -   the response of the request (the content of the page
     *                                                              at the URL).
     *
     *                                                              If "body" is explicitly disabled via the {@link option()}
     *                                                              method by setting <b>CURLOPT_NOBODY</b> to 0 or FALSE,
     *                                                              this will be an empty string;
     *
     *                                      -   <b>response</b> -   the response given by the cURL library as an array
     *                                                              with 2 entries: the first entry represents the result's
     *                                                              code, while the second is the textual representation
     *                                                              of the code; if the request was successful, these
     *                                                              values will be <i>array(0, CURLE_OK);</i> consult
     *                                                              {@link http://www.php.net/manual/en/function.curl-errno.php#103128
     *                                                              this list} to see the possible values of this property;
     *
     *  <samp>If the callback function returns FALSE  while {@link cache} is enabled, the library will not cache the
     *  respective request, making it easy to retry failed requests without having to clear all cache.</samp>
     *
     *  @return null
     */
    public function download($url, $destination_path, $callback = '')
    {

        // if destination path is not a directory or is not writable, trigger an error message
        if (!is_dir($destination_path) || !is_writable($destination_path)) trigger_error('"' . $destination_path . '" is not a valid path or is not writable!', E_USER_ERROR);

        // set download path
        $this->download_path = rtrim($destination_path, '/\\') . '/';

        // instruct the cURL library that it has to do a binary transfer
        $this->option(CURLOPT_BINARYTRANSFER, 1);

        // prior to PHP 5.3, func_get_args() cannot be used as a function parameter, so we need this intermediary step
        $arguments = func_get_args();

        // prepare the arguments to be passed to the callback function
        // (consisting from the first 3, plus any additional arguments passed to the "download" method)
        $arguments = array_merge(array($url, $callback), array_slice($arguments, 3));

        // process request(s)
        call_user_func_array(array($this, '_process'), $arguments);

    }

    /**
     *  Works exactly like the {@link 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 <i>$username</i> and <i>$password</i>
     *  arguments, one or more files specified by the <i>$url</i> argument, saves the downloaded files (with their original
     *  name) to the path specified by the <i>$destination_path</i>, and executes the callback function specified by the
     *  <i>$callback</i> argument for each and every request, as soon as each 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 <b>CURLOPT_BINARYTRANSFER</b> option to TRUE, so you might want to change
     *  this back to FALSE/0 or "unset" it using the {@link option()} method, before making a {@link get()}, {@link header()}
     *  or {@link post()} request.
     *
     *  <i>Files are downloaded preserving their name so you may run into trouble when trying to download more images
     *  having the same name (either from the same, or different servers)!</i>
     *
     *  <i>Multiple requests are made asynchronously, in parallel, and the callback function is called for each and every
     *  request, as soon as each request finishes. The number of parallel requests to be made at once can be set through
     *  the {@link threads} property.</i>
     *
     *  <i>Note that in case of multiple URLs, requests may not finish in the same order as initiated!</i>
     *
     *  <code>
     *  // the callback function to be executed for each and every
     *  // request, as soon as a request finishes
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  function mycallback($result) {
     *
     *      // everything went well
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // see all the returned data
     *          print_r('<pre>');
     *          print_r($result);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else die('An error occured: ' . $result->response[1]);
     *
     *  }
     *
     *  // include the Zebra_cURL library
     *  require 'path/to/Zebra_cURL';
     *
     *  // instantiate the Zebra_cURL object
     *  $curl = new Zebra_cURL();
     *
     *  // connect to the FTP server using the given credential, download a file to a given location and
     *  // execute the "mycallback" function for each request, as soon as it finishes
     *  $curl->download('ftp://somefile.ext', 'destination/path/', 'username', 'password', 'mycallback');
     *  </code>
     *
     *  @param  mixed   $url                A single or an array of URLs to process.
     *
     *  @param  string  $destination_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.
     *
     *  @param  string  $username           (Optional) The username to be used to connect to the FTP server (if required).
     *
     *  @param  string  $password           (Optional) The password to be used to connect to the FTP server (if required).
     *
     *  @param  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 {@link http://www.php.net/manual/ro/function.create-function.php
     *                                      create_function} or, as of PHP 5.3.0, via a {@link http://www.php.net/manual/ro/function.create-function.php
     *                                      closure}.
     *
     *                                      The callback function receives as first argument <b>an object</b> with <b>4
     *                                      properties</b> as described below, while any further arguments passed to the
     *                                      {@link ftp_download} method will be passed as extra arguments to the callback function:
     *
     *                                      -   <b>info</b>     -   an associative array containing information about the
     *                                                              request that just finished, as returned by PHP's
     *                                                              {@link http://php.net/manual/en/function.curl-getinfo.php curl_getinfo()}
     *                                                              function;
     *
     *                                      -   <b>headers</b>  -   an associative array with 2 items:
     *
     *                                                              <b>- last_request</b> an array with a single entry
     *                                                              containing the request headers generated by <i>the
     *                                                              last request</i>; 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 {@link option()} method
     *                                                              by setting <b>CURLINFO_HEADER_OUT</b> to 0 or FALSE,
     *                                                              this will be an empty string;
     *
     *                                                              <b>- responses</b> 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 {@link option()} method by setting
     *                                                              <b>CURLOPT_HEADER</b> to 0 or FALSE, this will be an
     *                                                              empty string;
     *
     *                                                              <i>Unless disabled, each entry in the headers' array
     *                                                              is an associative array in the form of property =>
     *                                                              value</i>
     *
     *                                      -   <b>body</b>     -   the response of the request (the content of the page
     *                                                              at the URL).
     *
     *                                                              If "body" is explicitly disabled via the {@link option()}
     *                                                              method by setting <b>CURLOPT_NOBODY</b> to 0 or FALSE,
     *                                                              this will be an empty string;
     *
     *                                      -   <b>response</b> -   the response given by the cURL library as an array
     *                                                              with 2 entries: the first entry represents the result's
     *                                                              code, while the second is the textual representation
     *                                                              of the code; if the request was successful, these
     *                                                              values will be <i>array(0, CURLE_OK);</i> consult
     *                                                              {@link http://www.php.net/manual/en/function.curl-errno.php#103128
     *                                                              this list} to see the possible values of this property;
     *
     *  <samp>If the callback function returns FALSE  while {@link cache} is enabled, the library will not cache the
     *  respective request, making it easy to retry failed requests without having to clear all cache.</samp>
     *
     *  @return null
     */
    public function ftp_download($url, $destination_path, $username = '', $password = '', $callback = '')
    {

        // if he have at least an username, set username/password
        if ($username != '') $this->option(CURLOPT_USERPWD, $username . ':' . $password);

        // prior to PHP 5.3, func_get_args() cannot be used as a function parameter
        // so we need this intermediary step
        $arguments = func_get_args();

        // prepare the arguments to be passed to the "download" method
        // (consisting from the first 3, plus any additional arguments passed to the "ftp_download" method)
        $arguments = array_merge(array($url, $destination_path, $callback), array_slice($arguments, 5));

        // call the "download" method
        call_user_func_array(array($this, 'download'), $arguments);

    }

    /**
     *  Performs an HTTP <b>GET</b> request to one or more URLs specified by the <i>$url</i> argument and executes the
     *  callback function specified by the <i>$callback</i> argument for each and every request, as soon as each request
     *  finishes.
     *
     *  <i>Multiple requests are made asynchronously, in parallel, and the callback function is called for each and every
     *  request, as soon as each request finishes. The number of parallel requests to be made at once can be set through
     *  the {@link threads} property.</i>
     *
     *  <i>Note that in case of multiple URLs, requests may not finish in the same order as initiated!</i>
     *
     *  <code>
     *  // the callback function to be executed for each and every
     *  // request, as soon as a request finishes
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  function mycallback($result) {
     *
     *      // everything went well
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // see all the returned data
     *          print_r('<pre>');
     *          print_r($result);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else die('An error occured: ' . $result->response[1]);
     *
     *  }
     *
     *  // include the Zebra_cURL library
     *  require 'path/to/Zebra_cURL';
     *
     *  // instantiate the Zebra_cURL object
     *  $curl = new Zebra_cURL();
     *
     *  // cache results in the "cache" folder and for 3600 seconds (one hour)
     *  $curl->cache('cache', 3600);
     *
     *  // let's fetch the RSS feeds of some popular websites
     *  // execute the "mycallback" function for each request, as soon as it finishes
     *  $curl->get(array(
     *      'http://feeds.feedburner.com/alistapart/main',
     *      'http://feeds.feedburner.com/TechCrunch',
     *      'http://feeds.mashable.com/mashable',
     *  ), 'mycallback')
     *  </code>
     *
     *  @param  mixed   $url        A single or an array of URLs to process.
     *
     *  @param  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 {@link http://www.php.net/manual/ro/function.create-function.php
     *                              create_function} or, as of PHP 5.3.0, via a {@link http://www.php.net/manual/ro/function.create-function.php
     *                              closure}.
     *
     *                              The callback function receives as first argument <b>an object</b> with <b>4 properties</b>
     *                              as described below, while any further arguments passed to the {@link get} method will
     *                              be passed as extra arguments to the callback function:
     *
     *                              -   <b>info</b>     -   an associative array containing information about the request
     *                                                      that just finished, as returned by PHP's
     *                                                      {@link http://php.net/manual/en/function.curl-getinfo.php curl_getinfo()}
     *                                                      function;
     *
     *                              -   <b>headers</b>  -   an associative array with 2 items:
     *
     *                                                      <b>- last_request</b> an array with a single entry containing
     *                                                      the request headers generated by <i>the last request</i>; 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 {@link option()}
     *                                                      method by setting <b>CURLINFO_HEADER_OUT</b> to 0 or FALSE,
     *                                                      this will be an empty string;
     *
     *                                                      <b>- responses</b> 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 {@link option()}
     *                                                      method by setting <b>CURLOPT_HEADER</b> to 0 or FALSE, this
     *                                                      will be an empty string;
     *
     *                                                      <i>Unless disabled, each entry in the headers' array is an
     *                                                      associative array in the form of property => value</i>
     *
     *                              -   <b>body</b> -       the response of the request (the content of the page at the
     *                                                      URL).
     *
     *                                                      Unless disabled via the {@link __construct() constructor}, all
     *                                                      applicable characters will be converted to HTML entities via
     *                                                      PHP's {@link http://php.net/manual/en/function.htmlentities.php htmlentities()}
     *                                                      function, so remember to use PHP's {@link http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode()}
     *                                                      function to do reverse this, if it's the case;
     *
     *                                                      If "body" is explicitly disabled via the {@link option()}
     *                                                      method by setting <b>CURLOPT_NOBODY</b> to 0 or FALSE, this
     *                                                      will be an empty string;
     *
     *                              -   <b>response</b> -   the response given by the cURL library as an array with 2
     *                                                      entries: the first entry represents the result's code, while
     *                                                      the second is the textual representation of the code; if the
     *                                                      request was successful, these values will be <i>array(0,
     *                                                      CURLE_OK);</i> consult {@link http://www.php.net/manual/en/function.curl-errno.php#103128
     *                                                      this list} to see the possible values of this property;
     *
     *  <samp>If the callback function returns FALSE  while {@link cache} is enabled, the library will not cache the
     *  respective request, making it easy to retry failed requests without having to clear all cache.</samp>
     *
     *  @return null
     */
    public function get($url, $callback = '')
    {

        // make sure we perform a GET request
		$this->option(CURLOPT_HTTPGET, 1);

        // prior to PHP 5.3, func_get_args() cannot be used as a function parameter
        // so we need this intermediary step
        $arguments = func_get_args();

        // process request(s)
        call_user_func_array(array($this, '_process'), $arguments);

    }

    /**
     *  Works exactly like the {@link get()} method, the only difference being that this method will automatically set
     *  the <b>CURLOPT_NOBODY</b> option to FALSE and thus the <i>body</i> property of the result will be an empty string.
     *  Also, <b>CURLINFO_HEADER_OUT</b> and <b>CURLOPT_HEADER</b> will be set to TRUE and therefore header information
     *  will be available.
     *
     *  <i>Multiple requests are made asynchronously, in parallel, and the callback function is called for each and every
     *  request, as soon as each request finishes. The number of parallel requests to be made at once can be set through
     *  the {@link threads} property.</i>
     *
     *  <i>Note that in case of multiple URLs, requests may not finish in the same order as initiated!</i>
     *
     *  <code>
     *  // the callback function to be executed for each and every
     *  // request, as soon as a request finishes
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  function mycallback($result) {
     *
     *      // everything went well
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // see all the returned data
     *          print_r('<pre>');
     *          print_r($result);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else die('An error occured: ' . $result->response[1]);
     *
     *  }
     *
     *  // include the Zebra_cURL library
     *  require 'path/to/Zebra_cURL';
     *
     *  // instantiate the Zebra_cURL object
     *  $curl = new Zebra_cURL();
     *
     *  // process given URLs execute the "mycallback" function for each
     *  // request, as soon as it finishes
     *  $curl->header('http://www.somewebsite.com', 'mycallback');
     *  </code>
     *
     *  @param  mixed   $url        A single or an array of URLs to process.
     *
     *  @param  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 {@link http://www.php.net/manual/ro/function.create-function.php
     *                              create_function} or, as of PHP 5.3.0, via a {@link http://www.php.net/manual/ro/function.create-function.php
     *                              closure}.
     *
     *                              The callback function receives as first argument <b>an object</b> with <b>4 properties</b>
     *                              as described below, while any further arguments passed to the {@link header} method
     *                              will be passed as extra arguments to the callback function:
     *
     *                              -   <b>info</b>     -   an associative array containing information about the request
     *                                                      that just finished, as returned by PHP's
     *                                                      {@link http://php.net/manual/en/function.curl-getinfo.php curl_getinfo()}
     *                                                      function;
     *
     *                              -   <b>headers</b>  -   an associative array with 2 items:
     *
     *                                                      <b>- last_request</b> an array with a single entry containing
     *                                                      the request headers generated by <i>the last request</i>; so,
     *                                                      remember, if there are redirects involved, there will be more
     *                                                      requests made, but only information from the last one will be
     *                                                      available;
     *
     *                                                      <b>- responses</b> an array with one or more entries (if there
     *                                                      are redirects involved) with the response headers of all the
     *                                                      requests made;
     *
     *                                                      <i>Each entry in the headers' arra…

Large files files are truncated, but you can click here to view the full file