Zebra_cURL.php

<?php

/**
 *  A high-performance solution for making HTTP requests from your PHP projects.
 *
 *  Zebra cURL allows you to run multiple requests concurrently, asynchronously, and supports a wide range of HTTP methods,
 *  including GET, POST, HEADER, PUT, PATCH, and DELETE. In addition to basic requests, this library also offers support
 *  for caching, FTP downloads, HTTP authentication, and proxy requests. This makes it a versatile tool for a wide range
 *  of applications and environments. Whether you're working on a simple script or a complex system, Zebra cURL can help
 *  you streamline your workflow and improve your application's performance.
 *
 *  Read more {@link https://github.com/stefangabos/Zebra_cURL/ here}.
 *
 *  @author     Stefan Gabos <contact@stefangabos.ro>
 *  @version    2.0.0 (last revision: August 24, 2026)
 *  @copyright  © 2013 - 2026 Stefan Gabos
 *  @license    https://www.gnu.org/licenses/lgpl-3.0.txt GNU LESSER GENERAL PUBLIC LICENSE
 *  @package    Zebra_cURL
 */

class Zebra_cURL {

    /**
     *  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
     *  {@link threads} property and then wait for {@link pause_interval} seconds before processing the next batch of
     *  requests.
     *
     *  Default is `0` (the library will keep as many parallel threads as defined by {@link threads} running at all times
     *  until there are no more requests to process).
     *
     *  @since 1.3.0
     *
     *  @var integer
     */
    public $pause_interval;

    /**
     *  The number of parallel, asynchronous requests to be processed by the library, at once.
     *
     *  <code>
     *  // process 30 simultaneous requests at once
     *  $curl->threads = 30;
     *  </code>
     *
     *  Note that unless {@link pause_interval} is set to a value greater than `0`, the library will process a constant
     *  number of requests, at all times; it is doing this by starting a new request as soon as another one finishes.
     *
     *  If {@link pause_interval} is set to a value greater than `0`, the library will process as many requests as set
     *  by the {@link threads} property and then wait for {@link pause_interval} seconds before processing the next
     *  batch of requests.
     *
     *  Values lower than `1` are treated as `1`.
     *
     *  Default is `10`
     *
     *  @var integer
     */
    public $threads;

    /**
     *  Used by the {@cache} method to cache request details
     *
     *  @var array<mixed>|boolean
     *  @access private
     */
    private $cache;

    /**
     *  Used by the {@link option} method to store the cURL options.
     *
     *  @var array<int>
     *  @access private
     */
    private $options;

    /**
     * Used by the {@link _process} method to determine whether to run processed requests' bodies through PHP's
     * {@link https://php.net/manual/en/function.htmlentities.php htmlentities} function.
     *
     * Default is FALSE. Can be changed by instantiating the library with the TRUE argument.
     *
     * @var boolean
     * @access private
     */
    private $_htmlentities;

    /**
     *  Used to tell the library whether to queue requests or to process them right away
     *
     *  @var boolean
     *  @access private
     */
    private $_queue;

    /**
     *  The cURL multi handle
     *
     *  @var \CurlMultiHandle|resource|false
     *  @access private
     */
    private $_multi_handle;

    /**
     *  Used to keep track of all the requests that need to be processed.
     *
     *  @var array<mixed>
     *  @access private
     */
    private $_requests;

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

    /**
     *  The cURL handles of the currently running requests, indexed the same way as {@link _running}.
     *
     *  @var array<mixed>
     *  @access private
     */
    private $_running_map;

    /**
     *  Possible values of the "result" attribute in the object passed to the callback function.
     *  List is kept up to date with the {@link https://github.com/curl/curl/blob/master/include/curl/curl.h source code of curl}
     *
     *  @var array<string>
     *  @access private
     */
    private $_response_messages = array(
        0   =>  'CURLE_OK',
        1   =>  'CURLE_UNSUPPORTED_PROTOCOL',
        2   =>  'CURLE_FAILED_INIT',
        3   =>  'CURLE_URL_MALFORMAT',
        4   =>  'CURLE_NOT_BUILT_IN',
        5   =>  'CURLE_COULDNT_RESOLVE_PROXY',
        6   =>  'CURLE_COULDNT_RESOLVE_HOST',
        7   =>  'CURLE_COULDNT_CONNECT',
        8   =>  'CURLE_WEIRD_SERVER_REPLY',
        9   =>  'CURLE_REMOTE_ACCESS_DENIED',
        10  =>  'CURLE_FTP_ACCEPT_FAILED',
        11  =>  'CURLE_FTP_WEIRD_PASS_REPLY',
        12  =>  'CURLE_FTP_ACCEPT_TIMEOUT',
        13  =>  'CURLE_FTP_WEIRD_PASV_REPLY',
        14  =>  'CURLE_FTP_WEIRD_227_FORMAT',
        15  =>  'CURLE_FTP_CANT_GET_HOST',
        16  =>  'CURLE_HTTP2',
        17  =>  'CURLE_FTP_COULDNT_SET_TYPE',
        18  =>  'CURLE_PARTIAL_FILE',
        19  =>  'CURLE_FTP_COULDNT_RETR_FILE',
        20  =>  'CURLE_OBSOLETE20',                 // NOT USED
        21  =>  'CURLE_QUOTE_ERROR',
        22  =>  'CURLE_HTTP_RETURNED_ERROR',
        23  =>  'CURLE_WRITE_ERROR',
        24  =>  'CURLE_OBSOLETE24',                 // NOT USED
        25  =>  'CURLE_UPLOAD_FAILED',
        26  =>  'CURLE_READ_ERROR',
        27  =>  'CURLE_OUT_OF_MEMORY',
        28  =>  'CURLE_OPERATION_TIMEDOUT',
        29  =>  'CURLE_OBSOLETE29',                 // NOT USED
        30  =>  'CURLE_FTP_PORT_FAILED',
        31  =>  'CURLE_FTP_COULDNT_USE_REST',
        32  =>  'CURLE_OBSOLETE32',                 // NOT USED
        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',
        40  =>  'CURLE_OBSOLETE40',                 // NOT USED
        41  =>  'CURLE_FUNCTION_NOT_FOUND',         // NOT USED since with 7.53.0
        42  =>  'CURLE_ABORTED_BY_CALLBACK',
        43  =>  'CURLE_BAD_FUNCTION_ARGUMENT',
        44  =>  'CURLE_OBSOLETE44',                 // NOT USED
        45  =>  'CURLE_INTERFACE_FAILED',
        46  =>  'CURLE_OBSOLETE46',                 // NOT USED
        47  =>  'CURLE_TOO_MANY_REDIRECTS',
        48  =>  'CURLE_UNKNOWN_OPTION',
        49  =>  'CURLE_SETOPT_OPTION_SYNTAX',
        50  =>  'CURLE_OBSOLETE50',                 // NOT USED
        51  =>  'CURLE_OBSOLETE51',                 // NOT USED
        52  =>  'CURLE_GOT_NOTHING',
        53  =>  'CURLE_SSL_ENGINE_NOTFOUND',
        54  =>  'CURLE_SSL_ENGINE_SETFAILED',
        55  =>  'CURLE_SEND_ERROR',
        56  =>  'CURLE_RECV_ERROR',
        57  =>  'CURLE_OBSOLETE57',                 // NOT USED
        58  =>  'CURLE_SSL_CERTPROBLEM',
        59  =>  'CURLE_SSL_CIPHER',
        60  =>  'CURLE_PEER_FAILED_VERIFICATION',
        61  =>  'CURLE_BAD_CONTENT_ENCODING',
        62  =>  'CURLE_OBSOLETE62',                 // NOT USED since 7.82.0
        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_OBSOLETE75',                 // NOT USED since 7.82.0
        76  =>  'CURLE_OBSOLETE76',                 // NOT USED since 7.82.0
        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',
        85  =>  'CURLE_RTSP_CSEQ_ERROR',
        86  =>  'CURLE_RTSP_SESSION_ERROR',
        87  =>  'CURLE_FTP_BAD_FILE_LIST',
        88  =>  'CURLE_CHUNK_FAILED',
        89  =>  'CURLE_NO_CONNECTION_AVAILABLE',
        90  =>  'CURLE_SSL_PINNEDPUBKEYNOTMATCH',
        91  =>  'CURLE_SSL_INVALIDCERTSTATUS',
        92  =>  'CURLE_HTTP2_STREAM',
        93  =>  'CURLE_RECURSIVE_API_CALL',
        94  =>  'CURLE_AUTH_ERROR',
        95  =>  'CURLE_HTTP3',
        96  =>  'CURLE_QUIC_CONNECT_ERROR',
        97  =>  'CURLE_PROXY',
        98  =>  'CURLE_SSL_CLIENTCERT',
        99  =>  'CURLE_UNRECOVERABLE_POLL',
        100 =>  'CURLE_TOO_LARGE',
        101 =>  'CURLE_ECH_REQUIRED',
    );

    /**
     *  In PHP 8.4 CURLOPT_BINARYTRANSFER was deprecated and it had no effect since PHP 5.1.2
     *  see https://php.watch/versions/8.4/CURLOPT_BINARYTRANSFER-deprecated
     *
     *  We're going to use this flag to add/remove the option where appropriate.
     *
     *  @var boolean
     *  @access private
     */
    private $_use_binarytransfer = false;

    /**
     *  Constructor of the class.
     *
     *  Below is the list of default options set by the library when instantiated. Various methods of the library may
     *  overwrite some of these options when called (see {@link delete}, {@link download}, {@link ftp_download}, {@link get},
     *  {@link header}, {@link post}, {@link put}). The value of any of these options may also be changed with the
     *  {@link option} method. For a full list of available options and their description, consult the
     *  {@link https://www.php.net/manual/en/function.curl-setopt.php PHP documentation}.
     *
     *  -   `CURLINFO_HEADER_OUT`       -   the last request string sent<br>
     *                                      default: `TRUE`
     *
     *  -   `CURLOPT_AUTOREFERER`       -   TRUE to automatically set the *"Referer:"* field in requests where it follows
     *                                      a *"Location:"* redirect<br>
     *                                      default: `TRUE`
     *
     *
     *  -   `CURLOPT_COOKIEFILE`        -   the name of the file containing the cookie data. the cookie file can be in
     *                                      Netscape format, or just plain HTTP-style headers dumped into a file. if the
     *                                      name is an empty string, no cookies are loaded, but cookie handling is still
     *                                      enabled<br>
     *                                      default: `an empty string`
     *
     *  -   `CURLOPT_CONNECTTIMEOUT`    -   the number of seconds to wait while trying to connect<br>
     *                                      default: `10` (use `0` to wait indefinitely)
     *
     *  -   `CURLOPT_ENCODING`          -   the contents of the "Accept-Encoding: " header. this enables automatic decoding
     *                                      of the response. an empty string lets libcurl advertise every encoding it
     *                                      was built with (*gzip*, *deflate*, and, depending on the build, *br* and
     *                                      *zstd*), so the most efficient one supported by both ends gets used<br>
     *                                      default: `an empty string`
     *
     *  -   `CURLOPT_FOLLOWLOCATION`    -   TRUE to 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 that it is sent, unless `CURLOPT_MAXREDIRS` is set - see below).<br>
     *                                      because redirects are followed by default, the result of a request is that
     *                                      of the *final* URL; the URL the request was made to is available as
     *                                      `info['original_url']`, the final one as `info['url']`, and the headers of
     *                                      each hop in `headers['responses']`. set this to `FALSE` through the
     *                                      {@link option} method to get the redirect response itself instead<br>
     *                                      default: `TRUE`
     *
     *  -   `CURLOPT_HEADER`            -   TRUE to include the header in the output<br>
     *                                      default: `TRUE`
     *
     *  -   `CURLOPT_MAXREDIRS`         -   the maximum amount of HTTP redirections to follow. use this option alongside
     *                                      `CURLOPT_FOLLOWLOCATION` - see above<br>
     *                                      default: `50`
     *
     *  -   `CURLOPT_PROTOCOLS`         -   the protocols libcurl is allowed to use for the URLs given to the library.
     *                                      any other scheme (`file://`, `gopher://`, `dict://`, etc.) is refused, which
     *                                      matters when URLs come from user input. {@link ftp_download} also allows `FTP`
     *                                      and `FTPS` for its own requests<br>
     *                                      default: `CURLPROTO_HTTP | CURLPROTO_HTTPS`
     *
     *  -   `CURLOPT_REDIR_PROTOCOLS`   -   the protocols libcurl is allowed to follow redirects to<br>
     *                                      default: `CURLPROTO_HTTP | CURLPROTO_HTTPS`
     *
     *  -   `CURLOPT_RETURNTRANSFER`    -   TRUE to return the transfer's body as a string instead of outputting it
     *                                      directly<br>
     *                                      default: `TRUE`
     *
     *  -   `CURLOPT_SSL_VERIFYHOST`    -   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. 0 to not check the names<br>
     *                                      see the {@link ssl} method for more info<br>
     *                                      default: `TRUE`
     *
     *  -   `CURLOPT_SSL_VERIFYPEER`    -   FALSE to stop cURL from verifying the peer's certificate<br>
     *                                      see the {@link ssl} method for more info<br>
     *                                      default: `TRUE`
     *
     *  -   `CURLOPT_TIMEOUT`           -   the maximum number of seconds to allow cURL functions to execute<br>
     *                                      default: `10`
     *
     *  -   `CURLOPT_USERAGENT`         -   the user agent string of a current Chrome browser on Windows, as some web
     *                                      services will not respond unless a browser-like user-agent string is provided;
     *                                      set your own through the {@link option} method if a different one is needed
     *
     *  @param  boolean $htmlentities       (Optional) Instructs the script whether the response body returned by the
     *                                      {@link get}, {@link post} and the other request methods should be run through
     *                                      PHP's {@link https://php.net/manual/en/function.htmlentities.php htmlentities}
     *                                      function. Useful when the body is to be output as-is in an HTML page; leave
     *                                      it off when the response is meant to be processed (JSON, XML, binary, etc.)
     *
     *                                      Default is `FALSE`
     *
     *  @throws RuntimeException            If the cURL extension is not loaded
     *
     *  @return void
     */
    public function __construct($htmlentities = false) {

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

        // initialize some private properties
        $this->_multi_handle = $this->_queue = false;
        $this->_running = $this->_running_map = $this->_requests = array();

        // the default number of seconds to wait between processing batches of requests
        // 0 means no waiting, process all requests at once
        $this->pause_interval = 0;

        // the default number of parallel, asynchronous, requests to be processed by the library at all times
        // (unless the "pause_interval" property is greater than 0, case in which it refers to the number of requests
        // to be processed before pausing)
        $this->threads = 10;

        // set the user's preference on whether to run htmlentities() on the response body or not
        $this->_htmlentities = $htmlentities;

        // set defaults for libcurl
        // set defaults
        $this->option(array(

            // include the last request headers as a property of the object given as argument to the callback
            CURLINFO_HEADER_OUT         =>  1,

            // automatically set the "Referer:" field where it follows a "Location:" redirect
            CURLOPT_AUTOREFERER         =>  1,

            // the name of the file containing the cookie data; if the name is an empty string, no cookies are
            // loaded, but cookie handling is still enabled
            CURLOPT_COOKIEFILE          =>  '',

            // the number of seconds to wait while trying to connect
            CURLOPT_CONNECTTIMEOUT      =>  10,

            // the contents of the "Accept-Encoding:" header; it enables automatic decoding of the response
            // an empty string lets libcurl advertise every encoding it supports (gzip, deflate, br, zstd, etc.)
            CURLOPT_ENCODING            =>  '',

            // follow any "Location:" header that the server sends as part of the HTTP header - note this is recursive
            // and that PHP will follow as many "Location:" headers as specified by CURLOPT_MAXREDIRS
            CURLOPT_FOLLOWLOCATION      =>  1,

            // include the response header(s) as a property of the object given as argument to the callback
            CURLOPT_HEADER              =>  1,

            // the maximum amount of HTTP redirects to follow; used together with CURLOPT_FOLLOWLOCATION
            CURLOPT_MAXREDIRS           =>  50,

            // this is an HTTP client: refuse any other scheme (file://, gopher://, dict://, etc.) both for the URLs given
            // to the library and for the URLs it gets redirected to
            CURLOPT_PROTOCOLS           =>  CURLPROTO_HTTP | CURLPROTO_HTTPS,
            CURLOPT_REDIR_PROTOCOLS     =>  CURLPROTO_HTTP | CURLPROTO_HTTPS,

            // the maximum number of seconds to allow cURL functions to execute before timing out
            CURLOPT_TIMEOUT             =>  30,

            // most services/websites will block requests with no/non-browser user agents
            // the string is fixed (not random) so that it can be part of the cache key
            CURLOPT_USERAGENT           =>  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',

            // return the transfer as a string of instead of outputting it to the screen
            CURLOPT_RETURNTRANSFER      =>  1,

        ));

        // if PHP version is at least 5.5
        if (version_compare(PHP_VERSION, '5.5') >= 0)

            // disable usage of @ in POST arguments
            // see https://wiki.php.net/rfc/curl-file-upload
            $this->option(CURLOPT_SAFE_UPLOAD, true);

        // for PHP versions lower than 5.1.2 we're still going to use CURLOPT_BINARYTRANSFER where appropriate.
        // for versions of PHP newer than that, we're not going to use it at all
        // see https://php.watch/versions/8.4/CURLOPT_BINARYTRANSFER-deprecated
        if (version_compare(PHP_VERSION, '5.1.2', '<') && defined('CURLOPT_BINARYTRANSFER')) {
            $this->_use_binarytransfer = true;
        }

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

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

    }

    /**
     *  Closes the multi handle, and with it any connections still open, when the object is destroyed.
     *
     *  @return void
     */
    public function __destruct() {

        if ($this->_multi_handle) curl_multi_close($this->_multi_handle);

    }

    /**
     *  Enables caching of request results.
     *
     *  >   Note that in case of downloads, only the actual request is cached and not the associated downloads
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // if making requests over HTTPS we need to load a CA bundle
     *  // so we don't get CURLE_SSL_CACERT response from cURL
     *  // you can get this bundle from https://curl.se/docs/caextract.html
     *  $curl->ssl(true, 2, 'path/to/cacert.pem');
     *
     *  // cache results in the "cache" folder and for 86400 seconds (24 hours)
     *  $curl->cache('cache', 86400);
     *
     *  // fetch the RSS feeds of some popular tech-related websites
     *  // and execute a callback function for each request, as soon as it finishes
     *  $curl->get(array(
     *
     *      'https://alistapart.com/main/feed/',
     *      'https://www.smashingmagazine.com/feed/',
     *      'https://code.tutsplus.com/posts.atom',
     *
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  ), function($result) {
     *
     *      // everything went well at cURL level
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // if server responded with code 200 (meaning that everything went well)
     *          // see https://httpstatus.es/ for a list of possible response codes
     *          if ($result->info['http_code'] == 200) {
     *
     *              // see all the returned data
     *              print_r('<pre>');
     *              print_r($result);
     *
     *          // show the server's response code
     *          } else throw new Exception('Server responded with code ' . $result->info['http_code']);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else throw new Exception('cURL responded with: ' . $result->response[0]);
     *
     *  });
     *  </code>
     *
     *  @param  mixed       $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 throw an exception 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 the $chmod
     *                                  argument plus the execute bit wherever the read bit is set (i.e. `0644` gives
     *                                  `0755` for the folder), as folders need it to be traversable.*
     *
     *  @param  integer     $lifetime   (Optional) The number of seconds after which cache will be considered expired.
     *
     *                                  Default is `3600` (one hour).
     *
     *  @param  boolean     $compress   (Optional) If set to `TRUE`, cache files will be
     *                                  {@link https://php.net/manual/en/function.gzcompress.php gzcompress}-ed so that
     *                                  they occupy less disk space.
     *
     *                                  Default is `TRUE`.
     *
     *  @param  integer     $chmod      (Optional) The file system permissions to be set for newly created cache files.
     *
     *                                  I suggest using the value `0644` (or `0600` if cached responses are not meant
     *                                  for other users of the system) 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 `0644`.
     *
     *  @return void
     */
    public function cache($path, $lifetime = 3600, $compress = true, $chmod = 0644) {

        // if caching is not explicitly disabled
        if ($path !== false) {

            // accept permissions given as a string as well (i.e. '0644'), normalize to an integer
            $chmod = intval($chmod, 8);

            // if path doesn't exist, attempt to create it
            // folders get the execute bit wherever the read bit is set, or they would not be traversable
            if (!is_dir($path)) @mkdir($path, $chmod | (($chmod & 0444) >> 2), true);

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

        // if caching is explicitly disabled, set this property to FALSE
        } else $this->cache = false;

    }

    /**
     *  Sets the path and name of the file to save cookie 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.
     *
     *  @param  string      $path   The path to a file to save cookies to / retrieve cookies from.
     *
     *                              *If file does not exist the library will attempt to create it and, if it is unable to
     *                              do so, it will throw an exception.*
     *
     *  @throws RuntimeException    If the file does not exist and cannot be created
     *
     *  @return void
     */
    public function cookies($path) {

        // file does not exist
        if (!is_file($path)) {

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

                // if file could not be created
                throw new RuntimeException('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');

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

            // cookies usually hold session identifiers, make the file readable by the owner only
            chmod($path, 0600);

        }

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

    }

    /**
     *  Performs an HTTP `DELETE` request to one or more URLs with optional POST data, and executes the callback
     *  function specified by the *$callback* argument for each and every request, as soon as the 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_HTTPGET`
     *  - `CURLOPT_FILE`
     *
     *  >   For PHP < 5.1.2 `CURLOPT_BINARYTRANSFER` will also be unset.<br>
     *      For newer versions of PHP this option is not used as {@link https://php.watch/versions/8.4/CURLOPT_BINARYTRANSFER-deprecated
     *      it has no effect and has been deprecated starting with PHP 8.4}.
     *
     *  Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every
     *  request as soon as the request finishes. The number of parallel requests to be constantly processed, at all times,
     *  is set through the {@link threads} property. See also {@link pause_interval}.
     *
     *  >   Because requests are done asynchronously, when initiating multiple requests at once, these may not finish in
     *      the order in which they were initiated!
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // if making requests over HTTPS we need to load a CA bundle
     *  // so we don't get CURLE_SSL_CACERT response from cURL
     *  // you can get this bundle from https://curl.se/docs/caextract.html
     *  $curl->ssl(true, 2, 'path/to/cacert.pem');
     *
     *  // do a DELETE request
     *  // and execute a callback function for each request, as soon as it finishes
     *  $curl->delete(array(
     *
     *      'https://www.somewebsite.com'   =>  array(
     *          'data_1'  =>  'value 1',
     *          'data_2'  =>  'value 2',
     *      ),
     *
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  ), function($result) {
     *
     *      // everything went well at cURL level
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // if server responded with code 200 (meaning that everything went well)
     *          // see https://httpstatus.es/ for a list of possible response codes
     *          if ($result->info['http_code'] == 200) {
     *
     *              // see all the returned data
     *              print_r('<pre>');
     *              print_r($result);
     *
     *          // show the server's response code
     *          } else throw new Exception('Server responded with code ' . $result->info['http_code']);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else throw new Exception('cURL responded with: ' . $result->response[0]);
     *
     *  });
     *  </code>
     *
     *  @param  mixed   $urls       URL(s) to send the request(s) to.
     *
     *                              Read full description of the argument at the {@link post} method.
     *
     *  @param  mixed   $callback   (Optional) Callback function to be called as soon as the request finishes.
     *
     *                              Read full description of the argument at the {@link get} method.
     *
     *  @since 1.3.3
     *
     *  >   If the callback function returns FALSE while {@link cache caching} is enabled, or if cURL reported an error
     *      for the request, the library will not cache the respective request, making it easy to retry failed requests
     *      without having to clear all cache.
     *
     *  @throws InvalidArgumentException    If a URL entry lacks the `url` key or a callback does not exist
     *  @throws RuntimeException            If the cache path is not writable or the cURL multi handle fails
     *
     *  @return void
     */
    public function delete($urls, $callback = '') {

        // normalize URLs
        // (transforms every allowed combination to the same type of array)
        $urls = $this->_prepare_urls($urls);

        // iterate through the list of URLs to process
        foreach ($urls as $values)

            // add each URL and associated properties to the "_requests" property
            $this->_requests[] = array(

                'url'       =>  $values['url'],

                // merge any custom options with the default ones
                'options'   =>

                    (isset($values['options']) ? $values['options'] : array()) +
                    array(
                        CURLINFO_HEADER_OUT     =>  1,
                        CURLOPT_CUSTOMREQUEST   =>  'DELETE',
                        CURLOPT_HEADER          =>  1,
                        CURLOPT_NOBODY          =>  0,
                        CURLOPT_POST            =>  0,
                        CURLOPT_POSTFIELDS      =>  isset($values['data']) ? $values['data'] : '',
                        CURLOPT_HTTPGET         =>  null,
                        CURLOPT_FILE            =>  null,
                    ) +
                    ($this->_use_binarytransfer ? [CURLOPT_BINARYTRANSFER => null] : []),

                'callback'  =>  $callback,

                // additional arguments to pass to the callback function, if any
                'arguments' =>  array_slice(func_get_args(), 2, null, true),

            );

        // if we're just queuing requests for now, do not execute the next lines
        if ($this->_queue) return;

        // if we have to pause between batches of requests, process them sequentially, in batches
        if ($this->pause_interval > 0) $this->_process_paused();

        // if we don't have to pause between batches of requests, process them all at once
        else $this->_process();

    }

    /**
     *  Downloads one or more files from one or more URLs, saves the downloaded files 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 the request finishes.
     *
     *  >   If the path you are downloading from refers to a file, the file's original name will be preserved but, if
     *      you are downloading a file generated by a script (i.e. https://foo.com/bar.php?w=1200&h=800) or the URL has
     *      no file name in it (i.e. https://foo.com/), the downloaded file's name will be random generated. Refer to the
     *      downloaded file's name in the result's `info` attribute, in the `downloaded_filename` section - see the
     *      example below.
     *
     *  >   If you are downloading multiple files with the same name the later ones will overwrite the previous ones.
     *
     *  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_HEADER` = `TRUE`
     *  - `CURLOPT_FILE`
     *
     *  ...and will unset the following options:
     *
     *  - `CURLOPT_CUSTOMREQUEST`
     *  - `CURLOPT_HTTPGET`
     *  - `CURLOPT_NOBODY`
     *  - `CURLOPT_POST`
     *  - `CURLOPT_POSTFIELDS`
     *
     *  >   For PHP < 5.1.2 `CURLOPT_BINARYTRANSFER` will also be set to `TRUE`.<br>
     *      For newer versions of PHP this option is not used as {@link https://php.watch/versions/8.4/CURLOPT_BINARYTRANSFER-deprecated
     *      it has no effect and has been deprecated starting with PHP 8.4}.
     *
     *  Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every
     *  request as soon as the request finishes. The number of parallel requests to be constantly processed, at all times,
     *  is set through the {@link threads} property. See also {@link pause_interval}.
     *
     *  >   Because requests are done asynchronously, when initiating multiple requests at once, these may not finish in
     *      the order in which they were initiated!
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // if making requests over HTTPS we need to load a CA bundle
     *  // so we don't get CURLE_SSL_CACERT response from cURL
     *  // you can get this bundle from https://curl.se/docs/caextract.html
     *  $curl->ssl(true, 2, 'path/to/cacert.pem');
     *
     *  // download 2 images from 2 different websites
     *  // and execute a callback function for each request, as soon as it finishes
     *  $curl->download(array(
     *
     *      'https://www.somewebsite.com/images/alpha.jpg',
     *      'https://www.otherwebsite.com/images/omega.jpg',
     *
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  ), 'destination/path/', function($result) {
     *
     *      // everything went well at cURL level
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // if server responded with code 200 (meaning that everything went well)
     *          // see https://httpstatus.es/ for a list of possible response codes
     *          if ($result->info['http_code'] == 200) {
     *
     *              // see all the returned data
     *              print_r('<pre>');
     *              print_r($result);
     *
     *              // get the downloaded file's path
     *              $result->info['downloaded_filename'];
     *
     *          // show the server's response code
     *          } else throw new Exception('Server responded with code ' . $result->info['http_code']);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else throw new Exception('cURL responded with: ' . $result->response[0]);
     *
     *  });
     *  </code>
     *
     *  @param  mixed       $urls           URL(s) to send the request(s) to.
     *
     *                                      Can be any of the following:
     *
     *                                      <code>
     *                                      // a string
     *                                      $curl->download('https://address.com/file.foo', 'path', 'callback');
     *
     *                                      // an array, for multiple requests
     *                                      $curl->download(array(
     *                                          'https://address1.com/file1.foo',
     *                                          'https://address2.com/file2.bar',
     *                                      ), 'path', 'callback');
     *                                      </code>
     *
     *                                      If {@link option() custom options} need to be set for each request, use the
     *                                      following format:
     *
     *                                      <code>
     *                                      // this can also be an array of arrays, for multiple requests
     *                                      $curl->download(array(
     *
     *                                          // mandatory!
     *                                          'url'       =>  'https://address.com/file.foo',
     *
     *                                          // optional, used to set any cURL option
     *                                          // in the same way you would set with the options() method
     *                                          'options'   =>  array(
     *                                                              CURLOPT_USERAGENT   =>  'Dummy scraper 1.0',
     *                                                          ),
     *
     *                                      ), 'path', 'callback');
     *                                      </code>
     *
     *  @param  string      $path           The path to where to save the file(s) to.
     *
     *                                      *If path is not pointing to a directory or the directory is not writable, the
     *                                      library will throw an exception.*
     *
     *  @param  mixed       $callback       (Optional) Callback function to be called as soon as the request finishes.
     *
     *                                      Read full description of the argument at the {@link get} method.
     *
     *  >   If the callback function returns FALSE while {@link cache caching} is enabled, or if cURL reported an error
     *      for the request, the library will not cache the respective request, making it easy to retry failed requests
     *      without having to clear all cache.
     *
     *  @throws InvalidArgumentException    If *$path* is not a writable directory, a URL entry lacks the `url` key or a callback does not exist
     *  @throws RuntimeException            If a file cannot be created in *$path*, the cache path is not writable or the cURL multi handle fails
     *
     *  @return void
     */
    public function download($urls, $path, $callback = '') {

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

        // normalize URLs
        // (transforms every allowed combination to the same type of array)
        $urls = $this->_prepare_urls($urls);

        // iterate through the list of URLs to process
        foreach ($urls as $values)

            // add each URL and associated properties to the "_requests" property
            $this->_requests[] = array(

                'url'       =>  $values['url'],
                'path'      =>  rtrim($path, '/\\') . '/',

                // merge any custom options with the default ones
                'options'   =>

                    (isset($values['options']) ? $values['options'] : array()) +
                    array(
                        CURLINFO_HEADER_OUT     =>  1,
                        CURLOPT_HEADER          =>  0,
                        CURLOPT_CUSTOMREQUEST   =>  null,
                        CURLOPT_HTTPGET         =>  null,
                        CURLOPT_NOBODY          =>  null,
                        CURLOPT_POST            =>  null,
                        CURLOPT_POSTFIELDS      =>  null,
                    ) +
                    ($this->_use_binarytransfer ? [CURLOPT_BINARYTRANSFER => 1] : []),

                'callback'  =>  $callback,

                // flag indicating that this is a download request
                'download'  =>  true,

                // additional arguments to pass to the callback function, if any
                'arguments' =>  array_slice(func_get_args(), 3, null, true),

            );

        // if we're just queuing requests for now, do not execute the next lines
        if ($this->_queue) return;

        // if we have to pause between batches of requests, process them sequentially, in batches
        if ($this->pause_interval > 0) $this->_process_paused();

        // if we don't have to pause between batches of requests, process them all at once
        else $this->_process();

    }

    /**
     *  Works exactly like the {@link download} method but downloads are made from an FTP server.
     *
     *  Downloads one or more files from an FTP server, to which the connection is made using the given *$username* and
     *  *$password* arguments, 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 the 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_HEADER` = `TRUE`
     *  - `CURLOPT_FILE`
     *  - `CURLOPT_PROTOCOLS` = `CURLPROTO_FTP | CURLPROTO_FTPS | CURLPROTO_HTTP | CURLPROTO_HTTPS`
     *  - `CURLOPT_REDIR_PROTOCOLS` = `CURLPROTO_FTP | CURLPROTO_FTPS | CURLPROTO_HTTP | CURLPROTO_HTTPS`
     *
     *  ...and will unset the following options:
     *
     *  - `CURLOPT_CUSTOMREQUEST`
     *  - `CURLOPT_HTTPGET`
     *  - `CURLOPT_NOBODY`
     *  - `CURLOPT_POST`
     *  - `CURLOPT_POSTFIELDS`
     *
     *  >   For PHP < 5.1.2 `CURLOPT_BINARYTRANSFER` will also be set to `TRUE`.<br>
     *      For newer versions of PHP this option is not used as {@link https://php.watch/versions/8.4/CURLOPT_BINARYTRANSFER-deprecated
     *      it has no effect and has been deprecated starting with PHP 8.4}.
     *
     *  >   If you are downloading multiple files with the same name the later ones will overwrite the previous ones.
     *
     *  Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every
     *  request as soon as the request finishes. The number of parallel requests to be constantly processed, at all times,
     *  is set through the {@link threads} property. See also {@link pause_interval}.
     *
     *  >   Because requests are done asynchronously, when initiating multiple requests at once, these may not finish in
     *      the order in which they were initiated!
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // if making requests over HTTPS we need to load a CA bundle
     *  // so we don't get CURLE_SSL_CACERT response from cURL
     *  // you can get this bundle from https://curl.se/docs/caextract.html
     *  $curl->ssl(true, 2, 'path/to/cacert.pem');
     *
     *  // connect to the FTP server using the given credential, download a file to a given location
     *  // and execute a callback function for each request, as soon as it finishes
     *  $curl->ftp_download(
     *
     *      'ftp://somefile.ext',
     *      'destination/path',
     *      'username',
     *      'password',
     *
     *      // the callback function receives as argument an object with 4 properties
     *      // (info, header, body and response)
     *      function($result) {
     *
     *          // everything went well at cURL level
     *          if ($result->response[1] == CURLE_OK) {
     *
     *              // if server responded with code 200 (meaning that everything went well)
     *              // see https://httpstatus.es/ for a list of possible response codes
     *              if ($result->info['http_code'] == 200) {
     *
     *                  // see all the returned data
     *                  print_r('<pre>');
     *                  print_r($result);
     *
     *              // show the server's response code
     *              } else throw new Exception('Server responded with code ' . $result->info['http_code']);
     *
     *          // something went wrong
     *          // ($result still contains all data that could be gathered)
     *          } else throw new Exception('cURL responded with: ' . $result->response[0]);
     *
     *      }
     *
     *  );
     *  </code>
     *
     *  @param  mixed       $urls           URL(s) to send the request(s) to.
     *
     *                                      Can be any of the following:
     *
     *                                      <code>
     *                                      // a string
     *                                      $curl->ftp_download(
     *                                          'ftp://address.com/file.foo',
     *                                          'destination/path',
     *                                          'username',
     *                                          'password',
     *                                          'callback'
     *                                      );
     *
     *                                      // an array, for multiple requests
     *                                      $curl->ftp_download(array(
     *                                          'ftp://address1.com/file1.foo',
     *                                          'ftp://address2.com/file2.bar',
     *                                      ), 'destination/path', 'username', 'password', 'callback');
     *                                      </code>
     *
     *                                      If {@link option() custom options} need to be set for each request, use the
     *                                      following format:
     *
     *                                      <code>
     *                                      // this can also be an array of arrays, for multiple requests
     *                                      $curl->ftp_download(array(
     *
     *                                          // mandatory!
     *                                          'url'       =>  'ftp://address.com/file.foo',
     *
     *                                          // optional, used to set any cURL option
     *                                          // in the same way you would set with the options() method
     *                                          'options'   =>  array(
     *                                                              CURLOPT_USERAGENT   =>  'Dummy scraper 1.0',
     *                                                          ),
     *
     *                                      ), 'destination/path', 'username', 'password', 'callback');
     *                                      </code>
     *
     *                                      Note that in all the examples above, you are downloading files from a single
     *                                      FTP server. To make requests to multiple FTP servers, set the `CURLOPT_USERPWD`
     *                                      option yourself. The *$username* and *$password* arguments will be overwritten
     *                                      by the values set like this.
     *
     *                                      <code>
     *                                      $curl->ftp_download(array(
     *                                          array(
     *                                              'url'       =>  'ftp://address1.com/file1.foo',
     *                                              'options'   =>  array(
     *                                                                  CURLOPT_USERPWD =>  'username1:password1',
     *                                                              ),
     *                                          ),
     *                                          array(
     *                                              'url'       =>  'ftp://address2.com/file2.foo',
     *                                              'options'   =>  array(
     *                                                                  CURLOPT_USERPWD =>  'username2:password2',
     *                                                              ),
     *                                          ),
     *                                      ), 'destination/path', '', '', 'callback');
     *                                      </code>
     *
     *  @param  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
     *                                      throw an exception.*
     *
     *  @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 the request finishes.
     *
     *                                      Read full description of the argument at the {@link get} method.
     *
     *  >   If the callback function returns FALSE while {@link cache caching} is enabled, or if cURL reported an error
     *      for the request, the library will not cache the respective request, making it easy to retry failed requests
     *      without having to clear all cache.
     *
     *  @throws InvalidArgumentException    If *$path* is not a writable directory, a URL entry lacks the `url` key or a callback does not exist
     *  @throws RuntimeException            If a file cannot be created in *$path*, the cache path is not writable or the cURL multi handle fails
     *
     *  @return void
     */
    public function ftp_download($urls, $path, $username = '', $password = '', $callback = '') {

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

        // normalize URLs
        // (transforms every allowed combination to the same type of array)
        $urls = $this->_prepare_urls($urls);

        // iterate through the list of URLs to process
        foreach ($urls as $values)

            // add each URL and associated properties to the "_requests" property
            $this->_requests[] = array(

                'url'       =>  $values['url'],
                'path'      =>  rtrim($path, '/\\') . '/',

                // merge any custom options with the default ones
                'options'   =>

                    (isset($values['options']) ? $values['options'] : array()) +
                    array(
                        CURLINFO_HEADER_OUT     =>  1,
                        CURLOPT_HEADER          =>  0,
                        CURLOPT_USERPWD         =>  $username != '' ? $username . ':' . $password : null,
                        CURLOPT_PROTOCOLS       =>  CURLPROTO_FTP | CURLPROTO_FTPS | CURLPROTO_HTTP | CURLPROTO_HTTPS,
                        CURLOPT_REDIR_PROTOCOLS =>  CURLPROTO_FTP | CURLPROTO_FTPS | CURLPROTO_HTTP | CURLPROTO_HTTPS,
                        CURLOPT_CUSTOMREQUEST   =>  null,
                        CURLOPT_HTTPGET         =>  null,
                        CURLOPT_NOBODY          =>  null,
                        CURLOPT_POST            =>  null,
                        CURLOPT_POSTFIELDS      =>  null,
                    ) +
                    ($this->_use_binarytransfer ? [CURLOPT_BINARYTRANSFER => 1] : []),

                'callback'  =>  $callback,

                // flag indicating that this is a download request
                'download'  =>  true,

                // additional arguments to pass to the callback function, if any
                'arguments' =>  array_slice(func_get_args(), 5, null, true),

            );

        // if we're just queuing requests for now, do not execute the next lines
        if ($this->_queue) return;

        // if we have to pause between batches of requests, process them sequentially, in batches
        if ($this->pause_interval > 0) $this->_process_paused();

        // if we don't have to pause between batches of requests, process them all at once
        else $this->_process();

    }

    /**
     *  Performs an HTTP `GET` request to one or more URLs and executes the callback function specified by the *$callback*
     *  argument for each and every request, as soon as the 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_CUSTOMREQUEST`
     *  - `CURLOPT_FILE`
     *  - `CURLOPT_POST`
     *  - `CURLOPT_POSTFIELDS`
     *
     *  >   For PHP < 5.1.2 `CURLOPT_BINARYTRANSFER` will also be unset.<br>
     *      For newer versions of PHP this option is not used as {@link https://php.watch/versions/8.4/CURLOPT_BINARYTRANSFER-deprecated
     *      it has no effect and has been deprecated starting with PHP 8.4}.
     *
     *  Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every
     *  request as soon as the request finishes. The number of parallel requests to be constantly processed, at all times,
     *  is set through the {@link threads} property. See also {@link pause_interval}.
     *
     *  >   Because requests are done asynchronously, when initiating multiple requests at once, these may not finish in
     *      the order in which they were initiated!
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // if making requests over HTTPS we need to load a CA bundle
     *  // so we don't get CURLE_SSL_CACERT response from cURL
     *  // you can get this bundle from https://curl.se/docs/caextract.html
     *  $curl->ssl(true, 2, 'path/to/cacert.pem');
     *
     *  // 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 callback function for each request, as soon as it finishes
     *  $curl->get(array(
     *
     *      'https://alistapart.com/main/feed/',
     *      'https://www.smashingmagazine.com/feed/',
     *      'https://code.tutsplus.com/posts.atom',
     *
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  ), function($result) {
     *
     *      // everything went well at cURL level
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // if server responded with code 200 (meaning that everything went well)
     *          // see https://httpstatus.es/ for a list of possible response codes
     *          if ($result->info['http_code'] == 200) {
     *
     *              // see all the returned data
     *              print_r('<pre>');
     *              print_r($result);
     *
     *          // show the server's response code
     *          } else throw new Exception('Server responded with code ' . $result->info['http_code']);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else throw new Exception('cURL responded with: ' . $result->response[0]);
     *
     *  });
     *  </code>
     *
     *  @param  mixed       $urls           URL(s) to send the request(s) to.
     *
     *                                      Can be any of the following:
     *
     *                                      <code>
     *                                      // a string
     *                                      $curl->get('https://address.com/', 'callback');
     *
     *                                      // an array, for multiple requests
     *                                      $curl->get(array(
     *                                          'https://address1.com/',
     *                                          'https://address2.com/',
     *                                      ), 'callback');
     *                                      </code>
     *
     *                                      If {@link option() custom options} need to be set for each request, use the
     *                                      following format:
     *
     *                                      <code>
     *                                      // this can also be an array of arrays, for multiple requests
     *                                      $curl->get(array(
     *
     *                                          // mandatory!
     *                                          'url'       =>  'https://address.com/',
     *
     *                                          // optional, used to set any cURL option
     *                                          // in the same way you would set with the options() method
     *                                          'options'   =>  array(
     *                                                              CURLOPT_USERAGENT   =>  'Dummy scraper 1.0',
     *                                                          ),
     *
     *                                          // optional, you can pass arguments this way also
     *                                          'data'      =>  array(
     *                                                              'data_1'  =>  'value 1',
     *                                                              'data_2'  =>  'value 2',
     *                                                          ),
     *
     *                                      ), 'callback');
     *                                      </code>
     *
     *  @param  mixed       $callback       (Optional) Callback function to be called as soon as the request finishes.
     *
     *                                      May be given as a string representing the name of an existing function, or
     *                                      as an {@link https://php.net/manual/en/functions.anonymous.php anonymous function}.
     *
     *                                      The callback function receives as first argument **an object** with **4 properties**
     *                                      as described below. Any extra arguments passed to the {@link 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 {@link https://php.net/manual/en/function.curl-getinfo.php curl_getinfo()}
     *                                                          function
     *
     *                                      -   `headers`   -   an associative array with 2 items:
     *
     *                                                          <ul><li><ul><li>
     *                                                          `last_request` - an array with a single entry containing
     *                                                          the request headers generated by *the last request*<br>
     *                                                          therefore, when redirects are involved, only information
     *                                                          from the *last request* will be available<br>
     *                                                          if explicitly disabled by setting `CURLINFO_HEADER_OUT`
     *                                                          to `0` or `FALSE` through the {@link option} method, this
     *                                                          will be an empty string
     *                                                          </li></ul></li></ul>
     *
     *                                                          <ul><li><ul><li>
     *                                                          `responses` an empty string as it is not available for
     *                                                          this method
     *                                                          </li></ul></li></ul>
     *
     *                                      -   `body`      -   the response of the request (the content of the page at
     *                                                          the URL).<br><br>
     *                                                          >   If enabled via the {@link __construct() constructor},
     *                                                              all applicable characters will be converted to HTML entities
     *                                                              via PHP's {@link https://php.net/manual/en/function.htmlentities.php htmlentities}
     *                                                              function, so remember to use PHP's
     *                                                              {@link https://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode}
     *                                                              function in case you need the decoded values<br>
     *                                                              if explicitly disabled by setting `CURLOPT_NOBODY` to `0`
     *                                                              or `FALSE` through the {@link option} method, this will
     *                                                              be an empty string
     *
     *                                      -   `response`  -   the {@link https://www.php.net/manual/en/function.curl-errno.php#103128 response}
     *                                                          given by the cURL library as an array with 3 items:<br>
     *
     *                                                          <ul><li><ul><li>
     *                                                          the textual representation of the result's code (i.e. `CURLE_OK`)
     *                                                          </li></ul></li></ul>
     *                                                          <ul><li><ul><li>
     *                                                          the result's code (i.e. `0`)
     *                                                          </li></ul></li></ul>
     *                                                          <ul><li><ul><li>
     *                                                          the human readable error message as given by cURL
     *                                                          (i.e. `Could not resolve host: example.invalid`), or an
     *                                                          empty string if there was no error
     *                                                          </li></ul></li></ul>
     *
     *  >   If the callback function returns FALSE while {@link cache caching} is enabled, or if cURL reported an error
     *      for the request, the library will not cache the respective request, making it easy to retry failed requests
     *      without having to clear all cache.
     *
     *  @throws InvalidArgumentException    If a URL entry lacks the `url` key or a callback does not exist
     *  @throws RuntimeException            If the cache path is not writable or the cURL multi handle fails
     *
     *  @return void
     */
    public function get($urls, $callback = '') {

        // normalize URLs
        // (transforms every allowed combination to the same type of array)
        $urls = $this->_prepare_urls($urls);

        // iterate through the list of URLs to process
        foreach ($urls as $values)

            // add each URL and associated properties to the "_requests" property
            $this->_requests[] = array(

                'url'       =>  $values['url'] . (isset($values['data']) ? (strpos($values['url'], '?') === false ? '?' : '&') . (is_array($values['data']) ? http_build_query($values['data']) : $values['data']) : ''),

                // merge any custom options with the default ones
                'options'   =>

                    (isset($values['options']) ? $values['options'] : array()) +
                    array(
                        CURLINFO_HEADER_OUT     =>  1,
                        CURLOPT_HEADER          =>  1,
                        CURLOPT_HTTPGET         =>  1,
                        CURLOPT_NOBODY          =>  0,
                        CURLOPT_CUSTOMREQUEST   =>  null,
                        CURLOPT_FILE            =>  null,
                        CURLOPT_POST            =>  null,
                        CURLOPT_POSTFIELDS      =>  null,
                    ) +
                    ($this->_use_binarytransfer ? [CURLOPT_BINARYTRANSFER  =>  null] : []),

                'callback'  =>  $callback,

                // additional arguments to pass to the callback function, if any
                'arguments' =>  array_slice(func_get_args(), 2, null, true),

            );

        // if we're just queuing requests for now, do not execute the next lines
        if ($this->_queue) return;

        // if we have to pause between batches of requests, process them sequentially, in batches
        if ($this->pause_interval > 0) $this->_process_paused();

        // if we don't have to pause between batches of requests, process them all at once
        else $this->_process();

    }

    /**
     *  Works exactly like the {@link 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_CUSTOMREQUEST`
     *  - `CURLOPT_FILE`
     *  - `CURLOPT_POST`
     *  - `CURLOPT_POSTFIELDS`
     *
     *  >   For PHP < 5.1.2 `CURLOPT_BINARYTRANSFER` will also be unset.<br>
     *      For newer versions of PHP this option is not used as {@link https://php.watch/versions/8.4/CURLOPT_BINARYTRANSFER-deprecated
     *      it has no effect and has been deprecated starting with PHP 8.4}.
     *
     *  Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every
     *  request as soon as the request finishes. The number of parallel requests to be constantly processed, at all times,
     *  is set through the {@link threads} property. See also {@link pause_interval}.
     *
     *  >   Because requests are done asynchronously, when initiating multiple requests at once, these may not finish in
     *      the order in which they were initiated!
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // process given URLs
     *  // and execute a callback function for each request, as soon as it finishes
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  $curl->header('https://www.somewebsite.com', function($result) {
     *
     *      // everything went well at cURL level
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // if server responded with code 200 (meaning that everything went well)
     *          // see https://httpstatus.es/ for a list of possible response codes
     *          if ($result->info['http_code'] == 200) {
     *
     *              // see all the returned data
     *              print_r('<pre>');
     *              print_r($result);
     *
     *          // show the server's response code
     *          } else throw new Exception('Server responded with code ' . $result->info['http_code']);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else throw new Exception('cURL responded with: ' . $result->response[0]);
     *
     *  });
     *  </code>
     *
     *  @param  mixed       $urls           URL(s) to send the request(s) to.
     *
     *                                      Read full description of the argument at the {@link get} method.
     *
     *  @param  mixed       $callback       (Optional) Callback function to be called as soon as the request finishes.
     *
     *                                      Read full description of the argument at the {@link get} method.
     *
     *  >   If the callback function returns FALSE while {@link cache caching} is enabled, or if cURL reported an error
     *      for the request, the library will not cache the respective request, making it easy to retry failed requests
     *      without having to clear all cache.
     *
     *  @throws InvalidArgumentException    If a URL entry lacks the `url` key or a callback does not exist
     *  @throws RuntimeException            If the cache path is not writable or the cURL multi handle fails
     *
     *  @return void
     */
    public function header($urls, $callback = '') {

        // normalize URLs
        // (transforms every allowed combination to the same type of array)
        $urls = $this->_prepare_urls($urls);

        // iterate through the list of URLs to process
        foreach ($urls as $values)

            // add each URL and associated properties to the "_requests" property
            $this->_requests[] = array(

                'url'       =>  $values['url'],

                // merge any custom options with the default ones
                'options'   =>

                    (isset($values['options']) ? $values['options'] : array()) +
                    array(
                        CURLINFO_HEADER_OUT     =>  1,
                        CURLOPT_HEADER          =>  1,
                        CURLOPT_HTTPGET         =>  1,
                        CURLOPT_NOBODY          =>  1,
                        CURLOPT_CUSTOMREQUEST   =>  null,
                        CURLOPT_FILE            =>  null,
                        CURLOPT_POST            =>  null,
                        CURLOPT_POSTFIELDS      =>  null,
                    ) +
                    ($this->_use_binarytransfer ? [CURLOPT_BINARYTRANSFER  =>  null] : []),

                'callback'  =>  $callback,

                // additional arguments to pass to the callback function, if any
                'arguments' =>  array_slice(func_get_args(), 2, null, true),

            );

        // if we're just queuing requests for now, do not execute the next lines
        if ($this->_queue) return;

        // if we have to pause between batches of requests, process them sequentially, in batches
        if ($this->pause_interval > 0) $this->_process_paused();

        // if we don't have to pause between batches of requests, process them all at once
        else $this->_process();

    }

    /**
     *  Use this method to make requests to pages that require prior HTTP authentication.
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // prepare user name and password
     *  $curl->http_authentication('username', 'password');
     *
     *  // if making requests over HTTPS we need to load a CA bundle
     *  // so we don't get CURLE_SSL_CACERT response from cURL
     *  // you can get this bundle from https://curl.se/docs/caextract.html
     *  $curl->ssl(true, 2, 'path/to/cacert.pem');
     *
     *  // get content from a page that requires prior HTTP authentication
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  $curl->get('https://www.some-page-requiring-prior-http-authentication.com', function($result) {
     *
     *      // everything went well at cURL level
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // if server responded with code 200 (meaning that everything went well)
     *          // see https://httpstatus.es/ for a list of possible response codes
     *          if ($result->info['http_code'] == 200) {
     *
     *              // see all the returned data
     *              print_r('<pre>');
     *              print_r($result);
     *
     *          // show the server's response code
     *          } else throw new Exception('Server responded with code ' . $result->info['http_code']);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else throw new Exception('cURL responded with: ' . $result->response[0]);
     *
     *  });
     *  </code>
     *
     *  If you have to unset previously set values use
     *
     *  <code>
     *  $curl->http_authentication();
     *  </code>
     *
     *  @param  string      $username       User name to be used for authentication.
     *
     *  @param  string      $password       Password to be used for authentication.
     *
     *  @param  integer     $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<br>
     *                                      `CURLAUTH_BASIC | CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM`
     *
     *                                      `CURLAUTH_ANYSAFE` is an alias for<br>
     *                                      `CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM`
     *
     *                                      Default is `CURLAUTH_ANY`
     *
     *  @return void
     */
    public function http_authentication($username = '', $password = '', $type = CURLAUTH_ANY) {

        // set the required options
        $this->option(array(
            CURLOPT_HTTPAUTH    =>  ($username == '' && $password == '' ? null : $type),
            CURLOPT_USERPWD     =>  ($username == '' && $password == '' ? null : ($username . ':' . $password)),
        ));

    }

    /**
     *  Allows the setting of one or more {@link https://php.net/manual/en/function.curl-setopt.php cURL options}.
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // setting a single option
     *  $curl->option(CURLOPT_CONNECTTIMEOUT, 10);
     *
     *  // setting multiple options at once
     *  $curl->option(array(
     *      CURLOPT_TIMEOUT         =>  10,
     *      CURLOPT_CONNECTTIMEOUT  =>  10,
     *  ));
     *
     *  // requests are made here...
     *  </code>
     *
     *  @param  mixed   $option     A single option for which to set a value, or an associative array in the form of
     *                              *option* => *value*.
     *
     *                              *Setting a value to `null` will unset that option.*
     *
     *  @param  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,
     *                              the value of this argument will be ignored.
     *
     *                              *Setting a value to `null` will unset that option.*
     *
     *  @return void
     *
     */
    public function option($option, $value = '') {

        // if $options is given as an array
        if (is_array($option)) {

            // iterate through each of the values
            foreach ($option as $name => $value) {

                // if we need to "unset" an option, unset it
                if (is_null($value)) unset($this->options[$name]);

                // set the value for the option otherwise
                else $this->options[$name] = $value;

            }

        // if option is not given as an array,
        // if we need to "unset" an option, unset it
        } elseif (is_null($value)) unset($this->options[$option]);

        // set the value for the option otherwise
        else $this->options[$option] = $value;

    }

    /**
     *  Performs an HTTP `PATCH` request to one or more URLs and executes the callback function specified by the *$callback*
     *  argument for each and every request, as soon as the request finishes.
     *
     *  This method will automatically set the following options:
     *
     *  - `CURLINFO_HEADER_OUT` - `TRUE`
     *  - `CURLOPT_CUSTOMREQUEST` - `PATCH`
     *  - `CURLOPT_HEADER` - `TRUE`
     *  - `CURLOPT_NOBODY` - `FALSE`
     *  - `CURLOPT_POST` - `FALSE`
     *  - `CURLOPT_POSTFIELDS` - the POST data
     *
     *  ...and will unset the following options:
     *
     *  - `CURLOPT_HTTPGET`
     *  - `CURLOPT_FILE`
     *
     *  >   For PHP < 5.1.2 `CURLOPT_BINARYTRANSFER` will also be unset.<br>
     *      For newer versions of PHP this option is not used as {@link https://php.watch/versions/8.4/CURLOPT_BINARYTRANSFER-deprecated
     *      it has no effect and has been deprecated starting with PHP 8.4}.
     *
     *  Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every
     *  request as soon as the request finishes. The number of parallel requests to be constantly processed, at all times,
     *  is set through the {@link threads} property. See also {@link pause_interval}.
     *
     *  >   Because requests are done asynchronously, when initiating multiple requests at once, these may not finish in
     *      the order in which they were initiated!
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // if making requests over HTTPS we need to load a CA bundle
     *  // so we don't get CURLE_SSL_CACERT response from cURL
     *  // you can get this bundle from https://curl.se/docs/caextract.html
     *  $curl->ssl(true, 2, 'path/to/cacert.pem');
     *
     *  // do a PATCH request and execute a callback function for each request, as soon as it finishes
     *  $curl->patch(array(
     *
     *      'https://www.somewebsite.com'  =>  array(
     *          'data_1'  =>  'value 1',
     *          'data_2'  =>  'value 2',
     *      ),
     *
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  ), function($result) {
     *
     *      // everything went well at cURL level
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // if server responded with code 200 (meaning that everything went well)
     *          // see https://httpstatus.es/ for a list of possible response codes
     *          if ($result->info['http_code'] == 200) {
     *
     *              // see all the returned data
     *              print_r('<pre>');
     *              print_r($result);
     *
     *          // show the server's response code
     *          } else throw new Exception('Server responded with code ' . $result->info['http_code']);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else throw new Exception('cURL responded with: ' . $result->response[0]);
     *
     *  });
     *  </code>
     *
     *  @param  mixed       $urls           URL(s) to send the request(s) to.
     *
     *                                      Read full description of the argument at the {@link post} method.
     *
     *  @param  mixed       $callback       (Optional) Callback function to be called as soon as the request finishes.
     *
     *                                      Read full description of the argument at the {@link get} method.
     *
     *  @since 1.6.0
     *
     *  >   If the callback function returns FALSE while {@link cache caching} is enabled, or if cURL reported an error
     *      for the request, the library will not cache the respective request, making it easy to retry failed requests
     *      without having to clear all cache.
     *
     *  @throws InvalidArgumentException    If a URL entry lacks the `url` key or a callback does not exist
     *  @throws RuntimeException            If the cache path is not writable or the cURL multi handle fails
     *
     *  @return void
     */
    public function patch($urls, $callback = '') {

        // normalize URLs
        // (transforms every allowed combination to the same type of array)
        $urls = $this->_prepare_urls($urls);

        // iterate through the list of URLs to process
        foreach ($urls as $values)

            // add each URL and associated properties to the "_requests" property
            $this->_requests[] = array(

                'url'       =>  $values['url'],

                // merge any custom options with the default ones
                'options'   =>

                    (isset($values['options']) ? $values['options'] : array()) +
                    array(
                        CURLINFO_HEADER_OUT     =>  1,
                        CURLOPT_CUSTOMREQUEST   =>  'PATCH',
                        CURLOPT_HEADER          =>  1,
                        CURLOPT_NOBODY          =>  0,
                        CURLOPT_POST            =>  0,
                        CURLOPT_POSTFIELDS      =>  isset($values['data']) ? $values['data'] : '',
                        CURLOPT_HTTPGET         =>  null,
                        CURLOPT_FILE            =>  null,
                    ) +
                    ($this->_use_binarytransfer ? [CURLOPT_BINARYTRANSFER  =>  null] : []),

                'callback'  =>  $callback,

                // additional arguments to pass to the callback function, if any
                'arguments' =>  array_slice(func_get_args(), 2, null, true),

            );

        // if we're just queuing requests for now, do not execute the next lines
        if ($this->_queue) return;

        // if we have to pause between batches of requests, process them sequentially, in batches
        if ($this->pause_interval > 0) $this->_process_paused();

        // if we don't have to pause between batches of requests, process them all at once
        else $this->_process();

    }

    /**
     *  Performs an HTTP `POST` request to one or more URLs and executes the callback function specified by the *$callback*
     *  argument for each and every request, as soon as the 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_CUSTOMREQUEST`
     *  - `CURLOPT_HTTPGET`
     *  - `CURLOPT_FILE`
     *
     *  >   For PHP < 5.1.2 `CURLOPT_BINARYTRANSFER` will also be unset.<br>
     *      For newer versions of PHP this option is not used as {@link https://php.watch/versions/8.4/CURLOPT_BINARYTRANSFER-deprecated
     *      it has no effect and has been deprecated starting with PHP 8.4}.
     *
     *  Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every
     *  request as soon as the request finishes. The number of parallel requests to be constantly processed, at all times,
     *  is set through the {@link threads} property. See also {@link pause_interval}.
     *
     *  >   Because requests are done asynchronously, when initiating multiple requests at once, these may not finish in
     *      the order in which they were initiated!
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // if making requests over HTTPS we need to load a CA bundle
     *  // so we don't get CURLE_SSL_CACERT response from cURL
     *  // you can get this bundle from https://curl.se/docs/caextract.html
     *  $curl->ssl(true, 2, 'path/to/cacert.pem');
     *
     *  // do a POST request and execute a callback function for each request, as soon as it finishes
     *  $curl->post(array(
     *
     *      'https://www.somewebsite.com'  =>  array(
     *          'data_1'  =>  'value 1',
     *          'data_2'  =>  'value 2',
     *      ),
     *
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  ), function($result) {
     *
     *      // everything went well at cURL level
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // if server responded with code 200 (meaning that everything went well)
     *          // see https://httpstatus.es/ for a list of possible response codes
     *          if ($result->info['http_code'] == 200) {
     *
     *              // see all the returned data
     *              print_r('<pre>');
     *              print_r($result);
     *
     *          // show the server's response code
     *          } else throw new Exception('Server responded with code ' . $result->info['http_code']);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else throw new Exception('cURL responded with: ' . $result->response[0]);
     *
     *  });
     *  </code>
     *
     *  When uploading a file, pass a {@link https://php.net/manual/en/class.curlfile.php CURLFile} object as the value
     *
     *  <code>
     *  $curl->post(array(
     *      'https://www.somewebsite.com'  =>  array(
     *          'data_1'  =>  'value 1',
     *          'data_2'  =>  'value 2',
     *          'data_3'  =>  new CURLFile('/absolute/path/to/file.ext'),
     *  ), 'mycallback');
     *  </code>
     *
     *  @param  mixed       $urls           URL(s) to send the request(s) to.
     *
     *                                      Can be any of the following:
     *
     *                                      <code>
     *                                      // a string (no POST values sent)
     *                                      $curl->post('https://address.com');
     *
     *                                      // an array, for multiple requests (no POST values sent)
     *                                      $curl->post(array(
     *                                          'https://address1.com',
     *                                          'https://address2.com',
     *                                      ));
     *
     *                                      // an associative array in the form of Array(url => post-data),
     *                                      // where "post-data" is an associative array in the form of
     *                                      // Array(name => value) and represents the value(s) to be set for
     *                                      // CURLOPT_POSTFIELDS;
     *                                      // "post‑data" can also be an arbitrary string - useful if you
     *                                      // want to send raw data (like a JSON)
     *                                      $curl->post(array('https://address.com' => array(
     *                                          'data_1'  =>  'value 1',
     *                                          'data_2'  =>  'value 2',
     *                                      )));
     *
     *                                      // just like above but an *array* of associative arrays, for
     *                                      // multiple requests
     *                                      $curl->post(array(
     *                                          array('https://address.com1' => array(
     *                                              'data_1'  =>  'value 1',
     *                                              'data_2'  =>  'value 2',
     *                                          )),
     *                                          array('https://address.com2' => array(
     *                                              'data_1'  =>  'value 1',
     *                                              'data_2'  =>  'value 2',
     *                                          )),
     *                                      ));
     *                                      </code>
     *
     *                                      If {@link option() custom options} need to be set for each request, use the
     *                                      following format:
     *
     *                                      <code>
     *                                      // this can also be an array of arrays, for multiple requests
     *                                      $curl->post(array(
     *
     *                                          // mandatory!
     *                                          'url'       =>  'https://address.com',
     *
     *                                          // optional, used to set any cURL option
     *                                          // in the same way you would set with the options() method
     *                                          'options'   =>  array(
     *                                                              CURLOPT_USERAGENT   =>  'Dummy scraper 1.0',
     *                                                          ),
     *
     *                                          // optional, if you need to pass any arguments
     *                                          // (equivalent of setting CURLOPT_POSTFIELDS using
     *                                          // the "options" entry above)
     *                                          'data'      =>  array(
     *                                                              'data_1'  =>  'value 1',
     *                                                              'data_2'  =>  'value 2',
     *                                                          ),
     *                                      ));
     *                                      </code>
     *
     *                                      To post a file, pass a {@link https://php.net/manual/en/class.curlfile.php CURLFile}
     *                                      object as the value. Values are never interpreted as file paths, so a string
     *                                      starting with `@` is sent as-is (`{@link https://wiki.php.net/rfc/curl-file-upload CURLOPT_SAFE_UPLOAD}`
     *                                      is always `TRUE`).
     *
     *                                      <code>
     *                                      $curl->post(array('https://address.com' => array(
     *                                          'data_1'  =>  'value 1',
     *                                          'data_2'  =>  'value 2',
     *                                          'data_3'  =>  new CURLFile('/absolute/path/to/file.ext'),
     *                                      )));
     *                                      </code>
     *
     *                                      >   If any data is sent, the "Content-Type" header will be set to
     *                                          "multipart/form-data"
     *
     *  @param  mixed       $callback       (Optional) Callback function to be called as soon as the request finishes.
     *
     *                                      Read full description of the argument at the {@link get} method.
     *
     *  >   If the callback function returns FALSE while {@link cache caching} is enabled, or if cURL reported an error
     *      for the request, the library will not cache the respective request, making it easy to retry failed requests
     *      without having to clear all cache.
     *
     *  @throws InvalidArgumentException    If a URL entry lacks the `url` key or a callback does not exist
     *  @throws RuntimeException            If the cache path is not writable or the cURL multi handle fails
     *
     *  @return void
     */
    public function post($urls, $callback = '') {

        // normalize URLs
        // (transforms every allowed combination to the same type of array)
        $urls = $this->_prepare_urls($urls);

        // iterate through the list of URLs to process
        foreach ($urls as $values)

            // add each URL and associated properties to the "_requests" property
            $this->_requests[] = array(

                'url'       =>  $values['url'],
                'options'   =>

                    (isset($values['options']) ? $values['options'] : array()) +
                    array(
                        CURLINFO_HEADER_OUT     =>  1,
                        CURLOPT_HEADER          =>  1,
                        CURLOPT_NOBODY          =>  0,
                        CURLOPT_POST            =>  1,
                        CURLOPT_POSTFIELDS      =>  isset($values['data']) ? $values['data'] : '',
                        CURLOPT_CUSTOMREQUEST   =>  null,
                        CURLOPT_HTTPGET         =>  null,
                        CURLOPT_FILE            =>  null,
                    ) +
                    ($this->_use_binarytransfer ? [CURLOPT_BINARYTRANSFER  =>  null] : []),

                'callback'  =>  $callback,

                // additional arguments to pass to the callback function, if any
                'arguments' =>  array_slice(func_get_args(), 2, null, true),

            );

        // if we're just queuing requests for now, do not execute the next lines
        if ($this->_queue) return;

        // if we have to pause between batches of requests, process them sequentially, in batches
        if ($this->pause_interval > 0) $this->_process_paused();

        // if we don't have to pause between batches of requests, process them all at once
        else $this->_process();

    }

    /**
     *  Instructs the library to make all requests through a proxy server.
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // if making requests over HTTPS we need to load a CA bundle
     *  // so we don't get CURLE_SSL_CACERT response from cURL
     *  // you can get this bundle from https://curl.se/docs/caextract.html
     *  $curl->ssl(true, 2, 'path/to/cacert.pem');
     *
     *  // connect to a proxy server
     *  // (that's a random one i got from https://www.proxynova.com/proxy-server-list/)
     *  $curl->proxy('91.221.252.18', '8080');
     *
     *  // fetch a page and execute a callback function when done
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  $curl->get('https://www.somewebsite.com/', function($result) {
     *
     *      // everything went well at cURL level
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // if server responded with code 200 (meaning that everything went well)
     *          // see https://httpstatus.es/ for a list of possible response codes
     *          if ($result->info['http_code'] == 200) {
     *
     *              // see all the returned data
     *              print_r('<pre>');
     *              print_r($result);
     *
     *          // show the server's response code
     *          } else throw new Exception('Server responded with code ' . $result->info['http_code']);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else throw new Exception('cURL responded with: ' . $result->response[0]);
     *
     *  });
     *  </code>
     *
     *  @param  string      $proxy      The HTTP proxy to make requests through.
     *
     *                                  Can be an URL or an IP address.
     *
     *                                  *This option can also be set using the {@link option} method and setting
     *                                  `CURLOPT_PROXY` to the desired value.*
     *
     *                                  Setting this argument to `FALSE` will unset all the proxy-related options.
     *
     *  @param  integer     $port       (Optional) The port number of the proxy to connect to.
     *
     *                                  Default is `80`.
     *
     *                                  *This option can also be set using the {@link option} method and setting
     *                                  `CURLOPT_PROXYPORT` to the desired value.*
     *
     *  @param  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 {@link option} method
     *                                  and setting `CURLOPT_PROXYUSERPWD` to the desired value formatted like
     *                                  `[username]:[password]`.*
     *
     *  @param  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 {@link option} method
     *                                  and setting `CURLOPT_PROXYUSERPWD` to the desired value formatted like
     *                                  `[username]:[password]`.*
     *
     *  @param  boolean     $tunnel     (Optional) Whether to tunnel *all* requests through the proxy using the HTTP
     *                                  `CONNECT` method (`CURLOPT_HTTPPROXYTUNNEL`), making the proxy a blind relay.
     *
     *                                  HTTPS requests are always tunneled, regardless of this setting. For plain HTTP
     *                                  requests the default is to let the proxy handle them as an HTTP proxy, because
     *                                  many proxies refuse `CONNECT` to anything but port 443.
     *
     *                                  Default is `FALSE`.
     *
     *  @return void
     */
    public function proxy($proxy, $port = 80, $username = '', $password = '', $tunnel = false) {

        // if not disabled
        if ($proxy) {

            // set the required options
            $this->option(array(
                CURLOPT_HTTPPROXYTUNNEL     =>  $tunnel ? 1 : null,
                CURLOPT_PROXY               =>  $proxy,
                CURLOPT_PROXYPORT           =>  $port,
                CURLOPT_PROXYUSERPWD        =>  $username != '' ? $username . ':' . $password : null,
            ));

        // if disabled
        } else {

            // unset proxy-related options
            $this->option(array(
                CURLOPT_HTTPPROXYTUNNEL     =>  null,
                CURLOPT_PROXY               =>  null,
                CURLOPT_PROXYPORT           =>  null,
                CURLOPT_PROXYUSERPWD        =>  null,
            ));

        }

    }

    /**
     *  Performs an HTTP `PUT` request to one or more URLs and executes the callback function specified by the *$callback*
     *  argument for each and every request, as soon as the 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_HTTPGET`
     *  - `CURLOPT_FILE`
     *
     *  >   For PHP < 5.1.2 `CURLOPT_BINARYTRANSFER` will also be unset.<br>
     *      For newer versions of PHP this option is not used as {@link https://php.watch/versions/8.4/CURLOPT_BINARYTRANSFER-deprecated
     *      it has no effect and has been deprecated starting with PHP 8.4}.
     *
     *  Multiple requests are processed asynchronously, in parallel, and the callback function is called for each and every
     *  request as soon as the request finishes. The number of parallel requests to be constantly processed, at all times,
     *  is set through the {@link threads} property. See also {@link pause_interval}.
     *
     *  >   Because requests are done asynchronously, when initiating multiple requests at once, these may not finish in
     *      the order in which they were initiated!
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // if making requests over HTTPS we need to load a CA bundle
     *  // so we don't get CURLE_SSL_CACERT response from cURL
     *  // you can get this bundle from https://curl.se/docs/caextract.html
     *  $curl->ssl(true, 2, 'path/to/cacert.pem');
     *
     *  // do a PUT request and execute a callback function for each request, as soon as it finishes
     *  $curl->put(array(
     *
     *      'https://www.somewebsite.com'  =>  array(
     *          'data_1'  =>  'value 1',
     *          'data_2'  =>  'value 2',
     *      ),
     *
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  ), function($result) {
     *
     *      // everything went well at cURL level
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // if server responded with code 200 (meaning that everything went well)
     *          // see https://httpstatus.es/ for a list of possible response codes
     *          if ($result->info['http_code'] == 200) {
     *
     *              // see all the returned data
     *              print_r('<pre>');
     *              print_r($result);
     *
     *          // show the server's response code
     *          } else throw new Exception('Server responded with code ' . $result->info['http_code']);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else throw new Exception('cURL responded with: ' . $result->response[0]);
     *
     *  });
     *  </code>
     *
     *  @param  mixed       $urls           URL(s) to send the request(s) to.
     *
     *                                      Read full description of the argument at the {@link post} method.
     *
     *  @param  mixed       $callback       (Optional) Callback function to be called as soon as the request finishes.
     *
     *                                      Read full description of the argument at the {@link get} method.
     *
     *  @since 1.3.3
     *
     *  >   If the callback function returns FALSE while {@link cache caching} is enabled, or if cURL reported an error
     *      for the request, the library will not cache the respective request, making it easy to retry failed requests
     *      without having to clear all cache.
     *
     *  @throws InvalidArgumentException    If a URL entry lacks the `url` key or a callback does not exist
     *  @throws RuntimeException            If the cache path is not writable or the cURL multi handle fails
     *
     *  @return void
     */
    public function put($urls, $callback = '') {

        // normalize URLs
        // (transforms every allowed combination to the same type of array)
        $urls = $this->_prepare_urls($urls);

        // iterate through the list of URLs to process
        foreach ($urls as $values)

            // add each URL and associated properties to the "_requests" property
            $this->_requests[] = array(

                'url'       =>  $values['url'],

                // merge any custom options with the default ones
                'options'   =>

                    (isset($values['options']) ? $values['options'] : array()) +
                    array(
                        CURLINFO_HEADER_OUT     =>  1,
                        CURLOPT_CUSTOMREQUEST   =>  'PUT',
                        CURLOPT_HEADER          =>  1,
                        CURLOPT_NOBODY          =>  0,
                        CURLOPT_POST            =>  0,
                        CURLOPT_POSTFIELDS      =>  isset($values['data']) ? $values['data'] : '',
                        CURLOPT_HTTPGET         =>  null,
                        CURLOPT_FILE            =>  null,
                    ) +
                    ($this->_use_binarytransfer ? [CURLOPT_BINARYTRANSFER  =>  null] : []),

                'callback'  =>  $callback,

                // additional arguments to pass to the callback function, if any
                'arguments' =>  array_slice(func_get_args(), 2, null, true),

            );

        // if we're just queuing requests for now, do not execute the next lines
        if ($this->_queue) return;

        // if we have to pause between batches of requests, process them sequentially, in batches
        if ($this->pause_interval > 0) $this->_process_paused();

        // if we don't have to pause between batches of requests, process them all at once
        else $this->_process();

    }

    /**
     *  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 {@link start} method is called, all calls to {@link delete}, {@link download}, {@link ftp_download},
     *  {@link get}, {@link header}, {@link post} and {@link put} methods will queue up rather than being executed right
     *  away. Once the {@link start} method is called, all queued requests will be processed while values of
     *  {@link threads} and {@link pause_interval} properties will still apply.
     *
     *  <code>
     *  // the callback function to be executed for each and every
     *  // request, as soon as the request finishes
     *  // the callback function receives as argument an object with 4 properties
     *  // (info, header, body and response)
     *  function mycallback($result) {
     *
     *      // everything went well at cURL level
     *      if ($result->response[1] == CURLE_OK) {
     *
     *          // if server responded with code 200 (meaning that everything went well)
     *          // see https://httpstatus.es/ for a list of possible response codes
     *          if ($result->info['http_code'] == 200) {
     *
     *              // see all the returned data
     *              print_r('<pre>');
     *              print_r($result);
     *
     *          // show the server's response code
     *          } else throw new Exception('Server responded with code ' . $result->info['http_code']);
     *
     *      // something went wrong
     *      // ($result still contains all data that could be gathered)
     *      } else throw new Exception('cURL responded with: ' . $result->response[0]);
     *
     *  }
     *
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // if making requests over HTTPS we need to load a CA bundle
     *  // so we don't get CURLE_SSL_CACERT response from cURL
     *  // you can get this bundle from https://curl.se/docs/caextract.html
     *  $curl->ssl(true, 2, 'path/to/cacert.pem');
     *
     *  // queue requests - useful for grouping different types of requests
     *  // in this example, when the "start" method is called, we'll execute
     *  // the "get" and the "post" requests asynchronously
     *  $curl->queue();
     *
     *  // do a POST and execute the callback function when done
     *  $curl->post(array(
     *      'https://www.somewebsite.com'  =>  array(
     *          'data_1'  =>  'value 1',
     *          'data_2'  =>  'value 2',
     *      ),
     *  ), 'mycallback');
     *
     *  // fetch the RSS feeds of some popular websites
     *  // and execute the callback function for each request, as soon as it finishes
     *  $curl->get(array(
     *      'https://alistapart.com/main/feed/',
     *      'https://www.smashingmagazine.com/feed/',
     *      'https://code.tutsplus.com/posts.atom',
     *  ), 'mycallback')
     *
     *  // execute queued requests
     *  $curl->start();
     *  </code>
     *
     *  @since 1.3.0
     *
     *  @return void
     */
    public function queue() {

        // set a flag indicating the library to queue requests rather than executing them right away
        $this->_queue = true;

    }

    /**
     *  A shorthand for making a single {@link get} request without the need of a callback function.
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // if making requests over HTTPS we need to load a CA bundle
     *  // so we don't get CURLE_SSL_CACERT response from cURL
     *  // you can get this bundle from https://curl.se/docs/caextract.html
     *  $curl->ssl(true, 2, 'path/to/cacert.pem');
     *
     *  // get page's content only
     *  $content = $curl->scrape('https://www.somewebsite.com/');
     *
     *  // print that to screen
     *  echo $content;
     *
     *  // also get extra information about the page
     *  $content = $curl->scrape('https://www.somewebsite.com/', false);
     *
     *  // print that to screen
     *  print_r('<pre>');
     *  print_r($content);
     *  </code>
     *
     *  >   Prior to `1.6.3` this method's name was incorrectly `scrap`. For backward compatibility purposes that variant
     *      is also available to use but highly discouraged as it will be removed in the future.
     *
     *  @param  mixed       $url        An URL to fetch.
     *
     *                                  >   Note that this method only supports a single URL. For processing multiple URLs
     *                                      at once, see the {@link get() get} method.
     *
     *                                  >   The request is made immediately even if {@link queue} mode is active; requests
     *                                      already in the queue are left untouched.
     *
     *  @param  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 scraped page, as an object with properties as described for the *$callback*
     *                                  argument of the {@link get} method.
     *
     *                                  Default is `TRUE`.
     *
     *  @since 1.3.3
     *
     *  @throws InvalidArgumentException    If *$url* is not a string
     *
     *  @return mixed   Returns the scraped page's content, when *$body_only* is set to `TRUE`, or an object with properties
     *                  as described for the *$callback* argument of the {@link get} method.
     */
    public function scrape($url, $body_only = true) {

        // this method requires the $url argument to be a string
        if (is_array($url)) throw new InvalidArgumentException('URL must be a string');

        // this method is synchronous by nature so the request is made right away even if queue() was called; queue mode
        // and any already queued requests are set aside and restored afterwards
        $queue = $this->_queue;
        $requests = $this->_requests;
        $this->_queue = false;
        $this->_requests = array();

        $result = null;

        try {

            // make the request
            $this->get($url, function($response) use (&$result) {
                $result = $response;
            });

        } catch (Exception $exception) {

            // restore the queue even if the request throws
            $this->_queue = $queue;
            $this->_requests = $requests;
            throw $exception;

        }

        // restore queue
        $this->_queue = $queue;
        $this->_requests = $requests;

        // return result
        return $body_only ? $result->body : $result;

    }

    /**
     *  Same as the {@link scrape()} method but with incorrect name.
     *  Kept for backward compatibility purposes.
     *
     *  @param  mixed       $url        An URL to fetch.
     *
     *                                  >   Note that this method only supports a single URL. For processing multiple URLs
     *                                      at once, see the {@link get() get} method.
     *
     *                                  >   The request is made immediately even if {@link queue} mode is active; requests
     *                                      already in the queue are left untouched.
     *
     *  @param  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 scraped page, as an object with properties as described for the *$callback*
     *                                  argument of the {@link get} method.
     *
     *                                  Default is `TRUE`.
     *
     *  @return mixed   Returns the scraped page's content, when *$body_only* is set to `TRUE`, or an object with properties
     *                  as described for the *$callback* argument of the {@link get} method.
     *  @access private
     */
    public function scrap($url, $body_only = true) {
        return $this->scrape($url, $body_only);
    }

    /**
     *  Requests made over HTTPS usually require additional configuration, depending on the server. Most of the times
     *  {@link __construct() the defaults} set by the library will get you through but, if defaults are not working,
     *  you can set specific options using this method.
     *
     *  <code>
     *  // instantiate the class
     *  $curl = new Zebra_cURL();
     *
     *  // instruct the library to skip verifying peer's SSL certificate
     *  // (ignored if request is not made through HTTPS)
     *  $curl->ssl(false);
     *
     *  // fetch a page
     *  $curl->get('https://www.somewebsite.com/', function($result) {
     *      print_r("<pre>");
     *      print_r($result);
     *  });
     *  </code>
     *
     *  @param  boolean     $verify_peer        (Optional) Should the peer's certificate be verified by cURL?
     *
     *                                          Default is `TRUE`.
     *
     *                                          *This option can also be set using the {@link option} method and
     *                                          setting `CURLOPT_SSL_VERIFYPEER` to the desired value.*
     *
     *                                          When you are communicating over HTTPS (or any other protocol that
     *                                          uses TLS), it will, by default, verify that the server is signed by a
     *                                          trusted Certificate Authority (CA) and it will most likely fail.
     *
     *                                          When it does fail, instead of disabling this check, better
     *                                          {@link https://curl.se/docs/caextract.html download the CA bundle
     *                                          from Mozilla} and reference it through the *$file* argument below.
     *
     *  @param  integer     $verify_host        (Optional) Specifies whether 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 {@link option} method and setting
     *                                          `CURLOPT_SSL_VERIFYHOST` to the desired value.*
     *
     *  @param  mixed       $file               (Optional) An absolute path to a file holding the 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 {@link option} method and setting
     *                                          `CURLOPT_CAINFO` to the desired value.*
     *
     *  @param  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 {@link option} method and setting
     *                                          `CURLOPT_CAPATH` to the desired value.*
     *
     *  @throws InvalidArgumentException        If *$file* or *$path* do not exist
     *
     *  @return void
     */
    public function ssl($verify_peer = true, $verify_host = 2, $file = false, $path = false) {

        // set default options
        $this->option(array(
            CURLOPT_SSL_VERIFYPEER => $verify_peer,
            CURLOPT_SSL_VERIFYHOST => $verify_host,
        ));

        // if a path to a file holding one or more certificates to verify the peer with was given
        if ($file !== false) {

            // if file could be found, use it
            if (is_file($file)) $this->option(CURLOPT_CAINFO, $file);

            // if file was not found, trigger an error
            else throw new InvalidArgumentException('File "' . $file . '", holding one or more certificates to verify the peer with, was not found');

        }

        // if a directory holding multiple CA certificates was given
        if ($path !== false) {

            // if folder could be found, use it
            if (is_dir($path)) $this->option(CURLOPT_CAPATH, $path);

            // if folder was not found, trigger an error
            else throw new InvalidArgumentException('Directory "' . $path . '", holding one or more CA certificates to verify the peer with, was not found');

        }

    }

    /**
     *  Executes queued requests.
     *
     *  See {@link queue} method.
     *
     *  @since 1.3.0
     *
     *  @return void
     */
    public function start() {

        // indicate the library that it should execute queued requests
        $this->_queue = false;

        // if we have to pause between batches of requests, process them sequentially, in batches
        if ($this->pause_interval > 0) $this->_process_paused();

        // if we don't have to pause between batches of requests, process them all at once
        else $this->_process();

    }

    /**
     *  Detaches and closes the cURL handles of all the currently running requests, closes the files they were
     *  downloading to, and resets the list of running requests.
     *
     *  @return void
     *
     *  @access private
     */
    private function _discard_running_requests() {

        // iterate through the requests that are currently running
        foreach ($this->_running_map as $resource_number => $handle) {

            // detach the request's handle from the multi handle and close it
            curl_multi_remove_handle($this->_multi_handle, $handle);
            curl_close($handle);

            // get the request associated with the handle
            $request = $this->_running[$resource_number];

            // if the request was a download, close the file it was streaming to
            if (isset($request['download']) && $request['download'] && is_resource($request['file_handler']))
                fclose($request['file_handler']);

        }

        // forget about running requests and about requests still waiting in the queue
        $this->_running = $this->_running_map = array();

    }

    /**
     *  Returns the cache file name associated with a specific request.
     *
     *  The name is derived from the URL and from the full set of cURL options the request is made with - instance-level
     *  options (cookies, headers, authentication, proxy, etc.) merged with the request's own options.
     *
     *  @param  array<mixed>    $request    The request for which to return the associated cache file name.
     *
     *  @return string  Returns the path and name of the cache file associated with the request.
     *
     *  @access private
     */
    private function _get_cache_file_name($request) {

        $options = $this->_get_request_options($request);

        // remove empty values and values that cannot be part of the key (file handles, callbacks such as CURLOPT_PROGRESSFUNCTION)
        foreach ($options as $key => $value)
            if (is_null($value) || $value === '' || is_resource($value) || $value instanceof Closure) unset($options[$key]);

        // callback, arguments, the file name/handle used for downloads and the cache file name itself are not part of the key
        $request = array_diff_key($request, array('callback' => '', 'arguments' => '', 'file_name' => '', 'file_handler' => '', 'cache_file' => ''));

        $request['options'] = $options;

        // return the path and name of the file name associated with the request
        return rtrim($this->cache['path'], '/') . '/' . md5(serialize($request));

    }

    /**
     *  Returns the cURL options to use for a request: the instance-level options set via {@link option()} merged with
     *  the request's own options, where request options win and a `null` value removes the option.
     *
     *  Instance-level options are left untouched so that a request's options do not leak into subsequent requests.
     *
     *  @param  array<mixed>    $request    A request, as stored in the internal queue.
     *
     *  @return array<mixed>
     *
     *  @access private
     */
    private function _get_request_options($request) {

        $options = $this->options;

        // request options override instance options; null removes an option
        foreach ($request['options'] as $key => $value) {
            if (is_null($value)) unset($options[$key]);
            else $options[$key] = $value;
        }

        // cURL cannot handle nested arrays in CURLOPT_POSTFIELDS, so we need to flatten them to PHP-style keys
        // (i.e. 'a' => array('b' => 1, 'c' => array(2, 3)) becomes 'a[b]' => 1, 'a[c][0]' => 2, 'a[c][1]' => 3) which the
        // receiving side turns back into the original nested array
        if (isset($options[CURLOPT_POSTFIELDS]) && is_array($options[CURLOPT_POSTFIELDS])) {

            $flatten = function($fields, $prefix = '') use (&$flatten) {
                $result = array();
                foreach ($fields as $key => $value) {
                    $name = $prefix === '' ? $key : $prefix . '[' . $key . ']';
                    if (is_array($value)) foreach ($flatten($value, $name) as $nested_name => $nested_value) $result[$nested_name] = $nested_value;
                    else $result[$name] = $value;
                }
                return $result;
            };

            $options[CURLOPT_POSTFIELDS] = $flatten($options[CURLOPT_POSTFIELDS]);

        }

        // libcurl changes the request method as a side effect of each of these options (CURLOPT_POSTFIELDS switches to
        // POST, CURLOPT_POST set to 0 switches back to GET, etc.) so they are applied first, in this exact order,
        // regardless of the order they were given in
        $first = array(CURLOPT_HTTPGET, CURLOPT_NOBODY, CURLOPT_POST, CURLOPT_POSTFIELDS);

        // in some cases, CURLOPT_HTTPAUTH and CURLOPT_USERPWD need to be set as last options in order to work
        $last = array(CURLOPT_USERPWD, CURLOPT_HTTPAUTH);

        $result = array();

        foreach ($first as $key) if (array_key_exists($key, $options)) $result[$key] = $options[$key];
        foreach ($options as $key => $value) if (!in_array($key, $first) && !in_array($key, $last)) $result[$key] = $value;
        foreach ($last as $key) if (array_key_exists($key, $options)) $result[$key] = $options[$key];

        return $result;

    }

    /**
     *  Parse response headers.
     *
     *  It parses a string containing one or more HTTP headers and returns an array of headers where each entry also
     *  contains an associative array of *name* => *value* for each row of data in the respective header.
     *
     *  @param  string  $headers    A string containing one or more HTTP headers, where multiple headers are separated by
     *                              a blank line.
     *
     *  @return mixed               Returns an array of headers where each entry also contains an associative array of
     *                              *name* => *value* for each row of data in the respective header.
     *
     *                              Header names are returned exactly as sent by the server, i.e. `Content-Type` over
     *                              HTTP/1.1 but `content-type` over HTTP/2, where header names are always lowercase.
     *
     *                              If `CURLOPT_HEADER` is set to `FALSE` or `0`, this method will return an empty string.
     *
     *  @access private
     */
    private function _parse_headers($headers) {

        $result = array();

        // if we have nothing to work with
        if ($headers != '') {

            // split multiple headers by blank lines (header blocks are separated by an empty line, usually "\r\n\r\n")
            $headers = preg_split('/(\r?\n){2,}/', trim($headers));

            // when called with a second argument we are parsing request headers rather than response headers
            $first_line_name = func_num_args() == 2 ? 'Request Method: ' : 'Status: ';

            // iterate through the headers
            foreach ($headers as $index => $header) {

                // get all the lines in the header
                // lines in headers look like [name]:[optional whitespace][value]
                // also, the first line, the status, does not have a name, so we add the name now
                preg_match_all('/^([^:\r\n]+):[ \t]*(.*)$/m', $first_line_name . trim($header), $matches);

                // save results
                foreach ($matches[0] as $key => $value) {

                    // if don't yet have this headers
                    if (!isset($result[$index][$matches[1][$key]]))

                        $result[$index][$matches[1][$key]] = trim($matches[2][$key]);

                    // if we already have this header
                    else {

                        // first, turn it into an array
                        if (!is_array($result[$index][$matches[1][$key]])) $result[$index][$matches[1][$key]] = array($result[$index][$matches[1][$key]]);

                        // add value to array
                        $result[$index][$matches[1][$key]][] = trim($matches[2][$key]);

                    }

                }

            }

        }

        // return headers as an array
        return $result;

    }

    /**
     *  Normalizes URLs.
     *
     *  Since URLs can be given as a string, an array of URLs, one associative array or an array of associative arrays,
     *  this method normalizes all of those into an array of associative arrays.
     *
     *  @param  string|array<mixed> $urls   The URLs to normalize.
     *
     *  @return array<mixed>
     *  @access private
     */
    private function _prepare_urls($urls) {

        // if $urls is *one* associative array containing one of "url", "options" and "data" entries
        if (is_array($urls) && !empty(array_intersect(array('url', 'options', 'data'), array_keys($urls)))) {

            // since "url" is mandatory, stop if not present
            if (!isset($urls['url'])) throw new InvalidArgumentException('"url" key is missing from argument');

            // return as an array of arrays
            return array($urls);

        // if $urls is an array
        } elseif (is_array($urls)) {

            $result = array();

            // iterate over the entries in the array
            foreach ($urls as $key => $values) {

                // if key is numeric
                // we take it that everything we need is inside $values
                if (is_numeric($key)) {

                    // if $values is an associative array containing one of "url", "options" and "data" entries, like
                    // array(
                    //      'url'       =>  'https://address.com',
                    //      'options'   =>  array(...)
                    // )
                    if (is_array($values) && !empty(array_intersect(array('url', 'options', 'data'), array_keys($values)))) {

                        // keep everything as it is
                        $result[] = $values;

                    // if $values is an array containing an associative array where the key is the URL and the value is
                    // another array containing at least one of "url", "options" or "data" entries, like
                    // array('https://address.com' => array(
                    //      'options'   =>  array(...),
                    // ))
                    } elseif (is_array($values) && !is_numeric(key($values)) && is_array(current($values)) && !empty(array_intersect(array('url', 'options', 'data'), array_keys(current($values))))) {

                        // normalize values
                        $result[] = array_merge(array('url' => key($values)), current($values));

                    // if $values is an associative array where the key is the URL and the value is
                    // another array of POST values
                    // array('https://address.com' => array('foo' => 'bar'))
                    } elseif (is_array($values)) {

                        // normalize values
                        $result[] = array(
                            'url'   =>  key($values),
                            'data'  =>  current($values)
                        );

                    // if $values is not an array or not an associative array containing one of "url", "options" and "data" entries, like
                    // 'https://address.com'
                    } else {

                        // it has to be the URL
                        $result[] = array('url' => $values);

                    }

                // if key is not numeric
                // we take it that key is the URL
                } else {

                    // if $values is an associative array containing one of "url", "options" and "data" entries, like
                    // array(
                    //      'url'       =>  'https://address.com',
                    //      'options'   =>  array(...)
                    // )
                    if (is_array($values) && !empty(array_intersect(array('url', 'options', 'data'), array_keys($values)))) {

                        // normalize values
                        $result[] = array_merge(array('url' => $key), $values);

                    // if $values is an associative array with POST values, like
                    // array('foo' => 'bar'))
                    } else {

                        // the values have to be the POST values
                        $result[] = array('url' => $key, 'data' => $values);

                    }

                }

            }

            // update the values
            $urls = $result;

        // if $urls is not an array, as in
        // 'https://address.com'
        } else {

            // it has to be the URL, and make it an array of arrays
            $urls = array(array('url' => $urls));

        }

        // return the normalized array
        return $urls;

    }

    /**
     *  Does the actual work.
     *
     *  @return void
     *
     *  @access private
     */
    private function _process() {

        // requests left running by a previous call that was aborted by an exception (thrown from a callback, for instance)
        // would otherwise be picked up by this call, with stale state, so we discard them
        $this->_discard_running_requests();

        // if caching is enabled but path doesn't exist, or is not writable
        if ($this->cache !== false && (!is_dir($this->cache['path']) || !is_writable($this->cache['path']))) {

            // empty the queue before throwing so that the offending requests do not linger until the next call
            $this->_requests = array();

            throw new RuntimeException('Cache path "' . $this->cache['path'] . '" does not exist or is not writable');

        }

        // iterate through the requests to process
        foreach ($this->_requests as $index => $request) {

            // if callback function is defined but it doesn't exists
            if ($request['callback'] != '' && !is_callable($request['callback'])) {

                // empty the queue before throwing so that the offending requests do not linger until the next call
                $this->_requests = array();

                // the check is for when callback functions are defined as methods of a class
                throw new InvalidArgumentException('Callback function "' . (is_array($request['callback']) ? array_pop($request['callback']) : $request['callback']) . '" does not exist');

            }

            // if caching is enabled
            if ($this->cache !== false) {

                // get the name to be used for the cache file associated with the request
                // (and keep it with the request so that it is not computed again when the result is to be cached)
                $cache_file = $this->_requests[$index]['cache_file'] = $this->_get_cache_file_name($request);

                // if cache file exists, is not expired and we have a callback
                if ($request['callback'] != '' && file_exists($cache_file) && filemtime($cache_file) + $this->cache['lifetime'] > time()) {

                    $data = file_get_contents($cache_file);

                    if ($data !== false && $this->cache['compress']) $data = @gzuncompress($data);

                    // cached results are plain stdClass objects; refuse to instantiate anything else from the cache file
                    if ($data !== false)
                        $data = PHP_VERSION_ID >= 70000 ? unserialize($data, array('allowed_classes' => array('stdClass'))) : unserialize($data);

                    // a corrupt/truncated cache file is treated as a cache miss and the request is made again
                    if ($data instanceof stdClass) {

                        // prepare the arguments to pass to the callback function
                        $arguments = array_merge(

                            // made of the result from the cache file...
                            array($data),

                            // ...and any additional arguments (minus the first 2)
                            (array)$request['arguments']

                        );

                        // feed them as arguments to the callback function
                        call_user_func_array($request['callback'], $arguments);

                        // remove this request from the list so it doesn't get processed
                        unset($this->_requests[$index]);

                    }

                }

            }

        }

        // if there are any requests to process
        if (!empty($this->_requests)) {

            // initialize the multi handle, unless already initialized by a previous call
            // this will allow us to process multiple handles in parallel and, since it is kept for the lifetime of the
            // object, connections are reused across calls (and across batches when pausing between them)
            if (!$this->_multi_handle) $this->_multi_handle = curl_multi_init();

            // queue the first batch of requests
            // (as many as defined by the "threads" property, or less if there aren't as many requests)
            $this->_queue_requests();

            // a flag telling the library if there are any requests currently processing
            $running = null;

            // loop
            do {

                // get status update
                while (($status = curl_multi_exec($this->_multi_handle, $running)) == CURLM_CALL_MULTI_PERFORM);

                // on a multi-handle error (out of memory, internal error, etc.) release everything and bail out
                if ($status != CURLM_OK) {

                    // release the running requests and forget about the requests still waiting in the queue
                    $this->_discard_running_requests();
                    $this->_requests = array();

                    // close the multi curl handle
                    curl_multi_close($this->_multi_handle);
                    $this->_multi_handle = false;

                    throw new RuntimeException('cURL multi handle error: ' . (function_exists('curl_multi_strerror') ? curl_multi_strerror($status) : $status));

                }

                // if a request was just completed, we'll have to find out which one
                while ($info = curl_multi_info_read($this->_multi_handle)) {

                    // get handle of the completed request
                    $handle = $info['handle'];

                    // get content associated with the handle
                    // (NULL when the transfer went to a file, as with downloads, so cast to keep "body" a string)
                    $content = (string)curl_multi_getcontent($handle);

                    // get the handle's ID - the same way it was computed when the request was queued
                    $resource_number = PHP_MAJOR_VERSION < 8 ? (int)$handle : spl_object_id($handle);

                    // get the information associated with the request
                    $request = $this->_running[$resource_number];

                    // create a new object in which we will store all the data associated with the handle,
                    // as properties of this object
                    $result = new stdClass();

                    // get information about the request
                    $result->info = curl_getinfo($handle);

                    $append = array('original_url' => $request['url']);

                    // if a proxy was used
                    if (!empty($this->options[CURLOPT_PROXY])) {

                        // add proxy related information
                        $append['proxy'] = $this->options[CURLOPT_PROXY];
                        if (isset($this->options[CURLOPT_PROXYPORT]))
                            $append['proxy_port'] = $this->options[CURLOPT_PROXYPORT];

                    }

                    // extend the "info" property with the original URL
                    $result->info = $append + $result->info;

                    // if request was a POST
                    if (isset($request['options'][CURLOPT_POSTFIELDS]) && $request['options'][CURLOPT_POSTFIELDS])

                        // put POST parameters in the response
                        $result->post = $request['options'][CURLOPT_POSTFIELDS];

                    // last request headers
                    $result->headers['last_request'] =

                        (

                            // if CURLINFO_HEADER_OUT is set
                            isset($request['options'][CURLINFO_HEADER_OUT]) &&

                            // if CURLINFO_HEADER_OUT is TRUE
                            $request['options'][CURLINFO_HEADER_OUT] == 1 &&

                            // if we actually have this information
                            isset($result->info['request_header'])

                        // extract request headers
                        ) ? $this->_parse_headers($result->info['request_header'], true) : '';

                    // remove request headers information from its previous location
                    if (isset($result->info['request_header'])) unset($result->info['request_header']);

                    // get headers (unless we were explicitly told not to)
                    $result->headers['responses'] = (isset($request['options'][CURLOPT_HEADER]) && $request['options'][CURLOPT_HEADER] == 1) ?

                        $this->_parse_headers(substr($content, 0, $result->info['header_size'])) :

                        '';

                    // get output (unless we were explicitly told not to)
                    $result->body = !isset($request['options'][CURLOPT_NOBODY]) || $request['options'][CURLOPT_NOBODY] == 0 ?

                        (isset($request['options'][CURLOPT_HEADER]) && $request['options'][CURLOPT_HEADER] == 1 ?

                        substr($content, $result->info['header_size']) :

                        $content) :

                        '';

                    // if _htmlentities is set to TRUE, we're not doing a binary transfer and we have a body, run htmlentities() on it
                    // ENT_IGNORE because htmlentities returns an empty string if the input contains an invalid utf-8 sequence
                    if ($this->_htmlentities && (!isset($request['download']) || !$request['download']) && $result->body != '')
                        $result->body = htmlentities($result->body, ENT_IGNORE, 'utf-8');

                    // get cURL's response code, its name and the human readable error message (an empty string on success)
                    // result codes newer than our list of names fall back to curl_strerror()
                    $result->response = array(
                        isset($this->_response_messages[$info['result']]) ? $this->_response_messages[$info['result']] : (function_exists('curl_strerror') ? curl_strerror($info['result']) : 'CURLE_UNKNOWN'),
                        $info['result'],
                        curl_error($handle),
                    );

                    // if we have a callback
                    if (isset($request['callback']) && $request['callback'] != '') {

                        // prepare the arguments to pass to the callback function
                        $arguments = array_merge(

                            // made of the "result" object...
                            array($result),

                            // ...and any additional arguments
                            $request['arguments']

                        );

                        // if downloaded a file
                        if (isset($request['download']) && $request['download']) {

                            // close the file so that everything is flushed to disk before the callback gets to look at it
                            fclose($request['file_handler']);

                            // we make a dummy array with the first first 2 elements (which we also remove from the $arguments[0]->info array)
                            $tmp_array = array_splice($arguments[0]->info, 0, 2);

                            // make available the name we saved the file with
                            // (we need to merge the first 2 elements, our new array and the rest of the elements)
                            $arguments[0]->info = array_merge($tmp_array, array('downloaded_filename' => $request['file_name']), $arguments[0]->info);

                        }

                        // feed them as arguments to the callback function
                        // and save the callback's response, if any
                        $callback_response = call_user_func_array($request['callback'], $arguments);

                    // if no callback function, we assume the response is TRUE
                    } else $callback_response = true;

                    // if caching is enabled and the callback function did not return FALSE nor did the cURL request returned an error
                    if ($this->cache !== false && $callback_response !== false && $result->response[1] == CURLE_OK) {

                        // get the name of the cache file associated with the request
                        $cache_file = isset($request['cache_file']) ? $request['cache_file'] : $this->_get_cache_file_name($request);

                        // write to a temporary file and rename it into place so that concurrent readers never see a partially written cache file
                        $temporary_file = $cache_file . '.' . getmypid() . '.tmp';

                        // once file is written successfully
                        if (file_put_contents($temporary_file, $this->cache['compress'] ? gzcompress(serialize($result)) : serialize($result), LOCK_EX) !== false) {

                            // set rights on the file and rename
                            chmod($temporary_file, $this->cache['chmod']);
                            rename($temporary_file, $cache_file);

                        }

                    }

                    // if there are more URLs to process and we're don't pause between batches of requests, queue the next one(s)
                    if (!empty($this->_requests) && !$this->pause_interval) $this->_queue_requests();

                    // remove the handle that we finished processing
                    // this needs to be done *after* we've already queued a new URL for processing
                    curl_multi_remove_handle($this->_multi_handle, $handle);

                    // make sure the handle gets closed
                    curl_close($handle);

                    // if we downloaded a file and there was no callback to close the file for us
                    if (isset($request['download']) && $request['download'] && is_resource($request['file_handler']))

                        // close the associated file pointer
                        fclose($request['file_handler']);

                    // we don't need the information associated with this request anymore
                    unset($this->_running[$resource_number]);
                    unset($this->_running_map[$resource_number]);

                }

                // waits until curl_multi_exec() returns CURLM_CALL_MULTI_PERFORM or until the timeout, whatever happens first
                // call usleep() if a select returns -1 - workaround for PHP bug: https://bugs.php.net/bug.php?id=61141
                if ($running && curl_multi_select($this->_multi_handle) === -1) usleep(1000);

            // as long as there are threads running or requests waiting in the queue
            } while ($running || !empty($this->_running));

        }

    }

    /**
     *  A wrapper for the {@link _process} method used when we need to pause between batches of requests to
     *  process.
     *
     *  @return void
     *
     *  @access private
     */
    private function _process_paused() {

        // copy all requests to another variable
        $urls = $this->_requests;

        // while there are URLs to process
        while (!empty($urls)) {

            // get from the entire list of requests as many as specified by the "threads" property
            $this->_requests = array_splice($urls, 0, max(1, (int)$this->threads), array());

            // process those requests
            $this->_process();

            // wait for as many seconds as specified by the "pause_interval" property
            if (!empty($urls)) sleep($this->pause_interval);

        }

    }

    /**
     *  A helper method used by the {@link _process} method, taking care of keeping a constant number of requests
     *  queued, so that as soon as one request finishes another one will instantly take its place, thus making sure that
     *  the maximum allowed number of parallel threads are running all the time.
     *
     *  @return void
     *
     *  @access private
     */
    private function _queue_requests() {

        // get the number of remaining urls
        $requests_count = count($this->_requests);

        // iterate through the items in the queue
        for ($i = 0; $i < min($requests_count, max(1, (int)$this->threads)); $i++) {

            // remove the first request from the queue
            $request = array_shift($this->_requests);

            // initialize individual cURL handle with the URL
            $handle = curl_init($request['url']);

            // get the handle's ID
            // (the resource ID for PHP 7 and below, the object ID for PHP 8+ where $handle is a "CurlHandle" object)
            $resource_number = PHP_MAJOR_VERSION < 8 ? (int)$handle : spl_object_id($handle);

            // if we're downloading something
            if (isset($request['download']) && $request['download']) {

                // use parse_url to analyze the string
                // we use this so we won't have hashtags and/or query string in the file's name later on
                $parsed = parse_url($request['url']);

                // the name to save the file by
                // if the downloaded path refers to something with a query string (i.e. download.php?foo=bar&w=1000&h=1000)
                // the downloaded file's name would be "download.php" and, if you are downloading multiple files, each one
                // would overwrite the previous one; therefore we use an md5 of the query string in this case
                if (isset($parsed['query']) && $parsed['query'] != '') $file_name = md5($parsed['query']);

                // otherwise use the last segment of the path, decoded (i.e. "my%20file.pdf" is saved as "my file.pdf")
                else $file_name = isset($parsed['path']) ? basename(rawurldecode($parsed['path'])) : '';

                // if there is no usable file name in the URL (i.e. https://foo.com or https://foo.com/), use an md5 of the URL
                if (in_array($file_name, array('', '.', '..'), true)) $file_name = md5($request['url']);

                $request['file_name'] = $request['path'] . $file_name;

                // open a file and save the file pointer
                $request['file_handler'] = fopen($request['file_name'], 'w');

                if ($request['file_handler'] === false) {

                    // empty the queue before throwing so that the offending requests do not linger until the next call
                    $this->_requests = array();

                    throw new RuntimeException('File "' . $request['file_name'] . '" could not be created for writing');

                }

                // tell libcurl to use the file for streaming the download
                $request['options'][CURLOPT_FILE] = $request['file_handler'];

            }

            // set options for the handle
            curl_setopt_array($handle, $this->_get_request_options($request));

            // add the normal handle to the multi handle
            curl_multi_add_handle($this->_multi_handle, $handle);

            // keep track of the cURL handle associated with the running request
            $this->_running_map[$resource_number] = $handle;

            // add request to the list of running requests
            $this->_running[$resource_number] = $request;

        }

    }

}