Overview

Packages

  • Requests
    • Authentication
    • Cookies
    • Proxy
    • Session
    • Transport
    • Utilities

Classes

  • Requests
  • Requests_Auth_Basic
  • Requests_Cookie
  • Requests_Cookie_Jar
  • Requests_Hooks
  • Requests_IDNAEncoder
  • Requests_IPv6
  • Requests_IRI
  • Requests_Proxy_HTTP
  • Requests_Response
  • Requests_Response_Headers
  • Requests_Session
  • Requests_SSL
  • Requests_Transport_cURL
  • Requests_Transport_fsockopen
  • Requests_Utility_CaseInsensitiveDictionary
  • Requests_Utility_FilteredIterator

Interfaces

  • Requests_Auth
  • Requests_Hooker
  • Requests_Proxy
  • Requests_Transport

Exceptions

  • Requests_Exception
  • Requests_Exception_HTTP
  • Requests_Exception_HTTP_304
  • Requests_Exception_HTTP_305
  • Requests_Exception_HTTP_306
  • Requests_Exception_HTTP_400
  • Requests_Exception_HTTP_401
  • Requests_Exception_HTTP_402
  • Requests_Exception_HTTP_403
  • Requests_Exception_HTTP_404
  • Requests_Exception_HTTP_405
  • Requests_Exception_HTTP_406
  • Requests_Exception_HTTP_407
  • Requests_Exception_HTTP_408
  • Requests_Exception_HTTP_409
  • Requests_Exception_HTTP_410
  • Requests_Exception_HTTP_411
  • Requests_Exception_HTTP_412
  • Requests_Exception_HTTP_413
  • Requests_Exception_HTTP_414
  • Requests_Exception_HTTP_415
  • Requests_Exception_HTTP_416
  • Requests_Exception_HTTP_417
  • Requests_Exception_HTTP_418
  • Requests_Exception_HTTP_428
  • Requests_Exception_HTTP_429
  • Requests_Exception_HTTP_431
  • Requests_Exception_HTTP_500
  • Requests_Exception_HTTP_501
  • Requests_Exception_HTTP_502
  • Requests_Exception_HTTP_503
  • Requests_Exception_HTTP_504
  • Requests_Exception_HTTP_505
  • Requests_Exception_HTTP_511
  • Requests_Exception_HTTP_Unknown
  • Requests_Exception_Transport
  • Requests_Exception_Transport_cURL
  • Overview
  • Package
  • Class
  • Tree
  • Deprecated

Warning! You are currently reading the documentation for Requests 1.x.

It is recommended to upgrade to Requests 2.x at your earliest convenience. Upgrading to Requests 2.x is fairly straight-forward.
A full list of the changes can be found in the Changelog.

Visit the Requests 2.x documentation.

  1:   2:   3:   4:   5:   6:   7:   8:   9:  10:  11:  12:  13:  14:  15:  16:  17:  18:  19:  20:  21:  22:  23:  24:  25:  26:  27:  28:  29:  30:  31:  32:  33:  34:  35:  36:  37:  38:  39:  40:  41:  42:  43:  44:  45:  46:  47:  48:  49:  50:  51:  52:  53:  54:  55:  56:  57:  58:  59:  60:  61:  62:  63:  64:  65:  66:  67:  68:  69:  70:  71:  72:  73:  74:  75:  76:  77:  78:  79:  80:  81:  82:  83:  84:  85:  86:  87:  88:  89:  90:  91:  92:  93:  94:  95:  96:  97:  98:  99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: 222: 223: 224: 225: 226: 227: 228: 229: 230: 231: 232: 233: 234: 235: 236: 237: 238: 239: 240: 241: 242: 243: 244: 245: 246: 247: 248: 249: 250: 251: 252: 253: 254: 255: 256: 257: 258: 259: 260: 261: 262: 263: 264: 265: 266: 267: 268: 269: 270: 271: 272: 273: 274: 275: 276: 277: 278: 279: 280: 281: 282: 283: 284: 285: 286: 287: 288: 289: 290: 291: 292: 293: 294: 295: 296: 297: 298: 299: 300: 301: 302: 303: 304: 305: 306: 307: 308: 309: 310: 311: 312: 313: 314: 315: 316: 317: 318: 319: 320: 321: 322: 323: 324: 325: 326: 327: 328: 329: 330: 331: 332: 333: 334: 335: 336: 337: 338: 339: 340: 341: 342: 343: 344: 345: 346: 347: 348: 349: 350: 351: 352: 353: 354: 355: 356: 357: 358: 359: 360: 361: 362: 363: 364: 365: 366: 367: 368: 369: 370: 371: 372: 373: 374: 375: 376: 377: 378: 379: 380: 381: 382: 383: 384: 385: 386: 387: 388: 389: 390: 391: 392: 393: 394: 395: 396: 397: 398: 399: 400: 401: 402: 403: 404: 405: 406: 407: 408: 409: 410: 411: 412: 413: 414: 415: 416: 417: 418: 419: 420: 421: 422: 423: 424: 425: 426: 427: 428: 429: 430: 431: 432: 433: 434: 435: 436: 437: 438: 439: 440: 441: 442: 443: 444: 445: 446: 447: 448: 449: 450: 451: 452: 453: 454: 455: 456: 457: 458: 459: 460: 461: 462: 463: 464: 465: 466: 467: 468: 469: 470: 471: 472: 473: 474: 475: 476: 477: 478: 479: 480: 481: 482: 483: 484: 485: 486: 487: 488: 489: 490: 491: 492: 493: 494: 495: 496: 497: 498: 499: 500: 501: 502: 503: 504: 505: 506: 507: 508: 509: 510: 511: 512: 513: 514: 515: 516: 517: 518: 519: 520: 521: 522: 523: 524: 525: 526: 527: 528: 529: 530: 531: 532: 533: 534: 535: 536: 537: 538: 539: 540: 541: 542: 543: 544: 545: 546: 547: 548: 549: 550: 551: 552: 553: 554: 555: 556: 557: 558: 559: 560: 561: 562: 563: 564: 565: 566: 567: 568: 569: 570: 571: 572: 573: 574: 575: 576: 577: 578: 579: 580: 581: 582: 583: 584: 585: 586: 587: 588: 589: 590: 
<?php
/**
 * cURL HTTP transport
 *
 * @package Requests
 * @subpackage Transport
 */

/**
 * cURL HTTP transport
 *
 * @package Requests
 * @subpackage Transport
 */
class Requests_Transport_cURL implements Requests_Transport {
    const CURL_7_10_5 = 0x070A05;
    const CURL_7_16_2 = 0x071002;

    /**
     * Raw HTTP data
     *
     * @var string
     */
    public $headers = '';

    /**
     * Raw body data
     *
     * @var string
     */
    public $response_data = '';

    /**
     * Information on the current request
     *
     * @var array cURL information array, see {@see https://secure.php.net/curl_getinfo}
     */
    public $info;

    /**
     * cURL version number
     *
     * @var int
     */
    public $version;

    /**
     * cURL handle
     *
     * @var resource
     */
    protected $handle;

    /**
     * Hook dispatcher instance
     *
     * @var Requests_Hooks
     */
    protected $hooks;

    /**
     * Have we finished the headers yet?
     *
     * @var boolean
     */
    protected $done_headers = false;

    /**
     * If streaming to a file, keep the file pointer
     *
     * @var resource
     */
    protected $stream_handle;

    /**
     * How many bytes are in the response body?
     *
     * @var int
     */
    protected $response_bytes;

    /**
     * What's the maximum number of bytes we should keep?
     *
     * @var int|bool Byte count, or false if no limit.
     */
    protected $response_byte_limit;

    /**
     * Constructor
     */
    public function __construct() {
        $curl          = curl_version();
        $this->version = $curl['version_number'];
        $this->handle  = curl_init();

        curl_setopt($this->handle, CURLOPT_HEADER, false);
        curl_setopt($this->handle, CURLOPT_RETURNTRANSFER, 1);
        if ($this->version >= self::CURL_7_10_5) {
            curl_setopt($this->handle, CURLOPT_ENCODING, '');
        }
        if (defined('CURLOPT_PROTOCOLS')) {
            // phpcs:ignore PHPCompatibility.Constants.NewConstants.curlopt_protocolsFound
            curl_setopt($this->handle, CURLOPT_PROTOCOLS, CURLPROTO_HTTP | CURLPROTO_HTTPS);
        }
        if (defined('CURLOPT_REDIR_PROTOCOLS')) {
            // phpcs:ignore PHPCompatibility.Constants.NewConstants.curlopt_redir_protocolsFound
            curl_setopt($this->handle, CURLOPT_REDIR_PROTOCOLS, CURLPROTO_HTTP | CURLPROTO_HTTPS);
        }
    }

    /**
     * Destructor
     */
    public function __destruct() {
        if (is_resource($this->handle)) {
            curl_close($this->handle);
        }
    }

    /**
     * Perform a request
     *
     * @throws Requests_Exception On a cURL error (`curlerror`)
     *
     * @param string $url URL to request
     * @param array $headers Associative array of request headers
     * @param string|array $data Data to send either as the POST body, or as parameters in the URL for a GET/HEAD
     * @param array $options Request options, see {@see Requests::response()} for documentation
     * @return string Raw HTTP result
     */
    public function request($url, $headers = array(), $data = array(), $options = array()) {
        $this->hooks = $options['hooks'];

        $this->setup_handle($url, $headers, $data, $options);

        $options['hooks']->dispatch('curl.before_send', array(&$this->handle));

        if ($options['filename'] !== false) {
            $this->stream_handle = fopen($options['filename'], 'wb');
        }

        $this->response_data       = '';
        $this->response_bytes      = 0;
        $this->response_byte_limit = false;
        if ($options['max_bytes'] !== false) {
            $this->response_byte_limit = $options['max_bytes'];
        }

        if (isset($options['verify'])) {
            if ($options['verify'] === false) {
                curl_setopt($this->handle, CURLOPT_SSL_VERIFYHOST, 0);
                curl_setopt($this->handle, CURLOPT_SSL_VERIFYPEER, 0);
            }
            elseif (is_string($options['verify'])) {
                curl_setopt($this->handle, CURLOPT_CAINFO, $options['verify']);
            }
        }

        if (isset($options['verifyname']) && $options['verifyname'] === false) {
            curl_setopt($this->handle, CURLOPT_SSL_VERIFYHOST, 0);
        }

        curl_exec($this->handle);
        $response = $this->response_data;

        $options['hooks']->dispatch('curl.after_send', array());

        if (curl_errno($this->handle) === 23 || curl_errno($this->handle) === 61) {
            // Reset encoding and try again
            curl_setopt($this->handle, CURLOPT_ENCODING, 'none');

            $this->response_data  = '';
            $this->response_bytes = 0;
            curl_exec($this->handle);
            $response = $this->response_data;
        }

        $this->process_response($response, $options);

        // Need to remove the $this reference from the curl handle.
        // Otherwise Requests_Transport_cURL wont be garbage collected and the curl_close() will never be called.
        curl_setopt($this->handle, CURLOPT_HEADERFUNCTION, null);
        curl_setopt($this->handle, CURLOPT_WRITEFUNCTION, null);

        return $this->headers;
    }

    /**
     * Send multiple requests simultaneously
     *
     * @param array $requests Request data
     * @param array $options Global options
     * @return array Array of Requests_Response objects (may contain Requests_Exception or string responses as well)
     */
    public function request_multiple($requests, $options) {
        // If you're not requesting, we can't get any responses ¯\_(ツ)_/¯
        if (empty($requests)) {
            return array();
        }

        $multihandle = curl_multi_init();
        $subrequests = array();
        $subhandles  = array();

        $class = get_class($this);
        foreach ($requests as $id => $request) {
            $subrequests[$id] = new $class();
            $subhandles[$id]  = $subrequests[$id]->get_subrequest_handle($request['url'], $request['headers'], $request['data'], $request['options']);
            $request['options']['hooks']->dispatch('curl.before_multi_add', array(&$subhandles[$id]));
            curl_multi_add_handle($multihandle, $subhandles[$id]);
        }

        $completed       = 0;
        $responses       = array();
        $subrequestcount = count($subrequests);

        $request['options']['hooks']->dispatch('curl.before_multi_exec', array(&$multihandle));

        do {
            $active = 0;

            do {
                $status = curl_multi_exec($multihandle, $active);
            }
            while ($status === CURLM_CALL_MULTI_PERFORM);

            $to_process = array();

            // Read the information as needed
            while ($done = curl_multi_info_read($multihandle)) {
                $key = array_search($done['handle'], $subhandles, true);
                if (!isset($to_process[$key])) {
                    $to_process[$key] = $done;
                }
            }

            // Parse the finished requests before we start getting the new ones
            foreach ($to_process as $key => $done) {
                $options = $requests[$key]['options'];
                if ($done['result'] !== CURLE_OK) {
                    //get error string for handle.
                    $reason          = curl_error($done['handle']);
                    $exception       = new Requests_Exception_Transport_cURL(
                        $reason,
                        Requests_Exception_Transport_cURL::EASY,
                        $done['handle'],
                        $done['result']
                    );
                    $responses[$key] = $exception;
                    $options['hooks']->dispatch('transport.internal.parse_error', array(&$responses[$key], $requests[$key]));
                }
                else {
                    $responses[$key] = $subrequests[$key]->process_response($subrequests[$key]->response_data, $options);

                    $options['hooks']->dispatch('transport.internal.parse_response', array(&$responses[$key], $requests[$key]));
                }

                curl_multi_remove_handle($multihandle, $done['handle']);
                curl_close($done['handle']);

                if (!is_string($responses[$key])) {
                    $options['hooks']->dispatch('multiple.request.complete', array(&$responses[$key], $key));
                }
                $completed++;
            }
        }
        while ($active || $completed < $subrequestcount);

        $request['options']['hooks']->dispatch('curl.after_multi_exec', array(&$multihandle));

        curl_multi_close($multihandle);

        return $responses;
    }

    /**
     * Get the cURL handle for use in a multi-request
     *
     * @param string $url URL to request
     * @param array $headers Associative array of request headers
     * @param string|array $data Data to send either as the POST body, or as parameters in the URL for a GET/HEAD
     * @param array $options Request options, see {@see Requests::response()} for documentation
     * @return resource Subrequest's cURL handle
     */
    public function &get_subrequest_handle($url, $headers, $data, $options) {
        $this->setup_handle($url, $headers, $data, $options);

        if ($options['filename'] !== false) {
            $this->stream_handle = fopen($options['filename'], 'wb');
        }

        $this->response_data       = '';
        $this->response_bytes      = 0;
        $this->response_byte_limit = false;
        if ($options['max_bytes'] !== false) {
            $this->response_byte_limit = $options['max_bytes'];
        }
        $this->hooks = $options['hooks'];

        return $this->handle;
    }

    /**
     * Setup the cURL handle for the given data
     *
     * @param string $url URL to request
     * @param array $headers Associative array of request headers
     * @param string|array $data Data to send either as the POST body, or as parameters in the URL for a GET/HEAD
     * @param array $options Request options, see {@see Requests::response()} for documentation
     */
    protected function setup_handle($url, $headers, $data, $options) {
        $options['hooks']->dispatch('curl.before_request', array(&$this->handle));

        // Force closing the connection for old versions of cURL (<7.22).
        if (!isset($headers['Connection'])) {
            $headers['Connection'] = 'close';
        }

        /**
         * Add "Expect" header.
         *
         * By default, cURL adds a "Expect: 100-Continue" to most requests. This header can
         * add as much as a second to the time it takes for cURL to perform a request. To
         * prevent this, we need to set an empty "Expect" header. To match the behaviour of
         * Guzzle, we'll add the empty header to requests that are smaller than 1 MB and use
         * HTTP/1.1.
         *
         * https://curl.se/mail/lib-2017-07/0013.html
         */
        if (!isset($headers['Expect']) && $options['protocol_version'] === 1.1) {
            $headers['Expect'] = $this->get_expect_header($data);
        }

        $headers = Requests::flatten($headers);

        if (!empty($data)) {
            $data_format = $options['data_format'];

            if ($data_format === 'query') {
                $url  = self::format_get($url, $data);
                $data = '';
            }
            elseif (!is_string($data)) {
                $data = http_build_query($data, null, '&');
            }
        }

        switch ($options['type']) {
            case Requests::POST:
                curl_setopt($this->handle, CURLOPT_POST, true);
                curl_setopt($this->handle, CURLOPT_POSTFIELDS, $data);
                break;
            case Requests::HEAD:
                curl_setopt($this->handle, CURLOPT_CUSTOMREQUEST, $options['type']);
                curl_setopt($this->handle, CURLOPT_NOBODY, true);
                break;
            case Requests::TRACE:
                curl_setopt($this->handle, CURLOPT_CUSTOMREQUEST, $options['type']);
                break;
            case Requests::PATCH:
            case Requests::PUT:
            case Requests::DELETE:
            case Requests::OPTIONS:
            default:
                curl_setopt($this->handle, CURLOPT_CUSTOMREQUEST, $options['type']);
                if (!empty($data)) {
                    curl_setopt($this->handle, CURLOPT_POSTFIELDS, $data);
                }
        }

        // cURL requires a minimum timeout of 1 second when using the system
        // DNS resolver, as it uses `alarm()`, which is second resolution only.
        // There's no way to detect which DNS resolver is being used from our
        // end, so we need to round up regardless of the supplied timeout.
        //
        // https://github.com/curl/curl/blob/4f45240bc84a9aa648c8f7243be7b79e9f9323a5/lib/hostip.c#L606-L609
        $timeout = max($options['timeout'], 1);

        if (is_int($timeout) || $this->version < self::CURL_7_16_2) {
            curl_setopt($this->handle, CURLOPT_TIMEOUT, ceil($timeout));
        }
        else {
            // phpcs:ignore PHPCompatibility.Constants.NewConstants.curlopt_timeout_msFound
            curl_setopt($this->handle, CURLOPT_TIMEOUT_MS, round($timeout * 1000));
        }

        if (is_int($options['connect_timeout']) || $this->version < self::CURL_7_16_2) {
            curl_setopt($this->handle, CURLOPT_CONNECTTIMEOUT, ceil($options['connect_timeout']));
        }
        else {
            // phpcs:ignore PHPCompatibility.Constants.NewConstants.curlopt_connecttimeout_msFound
            curl_setopt($this->handle, CURLOPT_CONNECTTIMEOUT_MS, round($options['connect_timeout'] * 1000));
        }
        curl_setopt($this->handle, CURLOPT_URL, $url);
        curl_setopt($this->handle, CURLOPT_REFERER, $url);
        curl_setopt($this->handle, CURLOPT_USERAGENT, $options['useragent']);
        if (!empty($headers)) {
            curl_setopt($this->handle, CURLOPT_HTTPHEADER, $headers);
        }
        if ($options['protocol_version'] === 1.1) {
            curl_setopt($this->handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
        }
        else {
            curl_setopt($this->handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
        }

        if ($options['blocking'] === true) {
            curl_setopt($this->handle, CURLOPT_HEADERFUNCTION, array($this, 'stream_headers'));
            curl_setopt($this->handle, CURLOPT_WRITEFUNCTION, array($this, 'stream_body'));
            curl_setopt($this->handle, CURLOPT_BUFFERSIZE, Requests::BUFFER_SIZE);
        }
    }

    /**
     * Process a response
     *
     * @param string $response Response data from the body
     * @param array $options Request options
     * @return string|false HTTP response data including headers. False if non-blocking.
     * @throws Requests_Exception
     */
    public function process_response($response, $options) {
        if ($options['blocking'] === false) {
            $fake_headers = '';
            $options['hooks']->dispatch('curl.after_request', array(&$fake_headers));
            return false;
        }
        if ($options['filename'] !== false && $this->stream_handle) {
            fclose($this->stream_handle);
            $this->headers = trim($this->headers);
        }
        else {
            $this->headers .= $response;
        }

        if (curl_errno($this->handle)) {
            $error = sprintf(
                'cURL error %s: %s',
                curl_errno($this->handle),
                curl_error($this->handle)
            );
            throw new Requests_Exception($error, 'curlerror', $this->handle);
        }
        $this->info = curl_getinfo($this->handle);

        $options['hooks']->dispatch('curl.after_request', array(&$this->headers, &$this->info));
        return $this->headers;
    }

    /**
     * Collect the headers as they are received
     *
     * @param resource $handle cURL resource
     * @param string $headers Header string
     * @return integer Length of provided header
     */
    public function stream_headers($handle, $headers) {
        // Why do we do this? cURL will send both the final response and any
        // interim responses, such as a 100 Continue. We don't need that.
        // (We may want to keep this somewhere just in case)
        if ($this->done_headers) {
            $this->headers      = '';
            $this->done_headers = false;
        }
        $this->headers .= $headers;

        if ($headers === "\r\n") {
            $this->done_headers = true;
        }
        return strlen($headers);
    }

    /**
     * Collect data as it's received
     *
     * @since 1.6.1
     *
     * @param resource $handle cURL resource
     * @param string $data Body data
     * @return integer Length of provided data
     */
    public function stream_body($handle, $data) {
        $this->hooks->dispatch('request.progress', array($data, $this->response_bytes, $this->response_byte_limit));
        $data_length = strlen($data);

        // Are we limiting the response size?
        if ($this->response_byte_limit) {
            if ($this->response_bytes === $this->response_byte_limit) {
                // Already at maximum, move on
                return $data_length;
            }

            if (($this->response_bytes + $data_length) > $this->response_byte_limit) {
                // Limit the length
                $limited_length = ($this->response_byte_limit - $this->response_bytes);
                $data           = substr($data, 0, $limited_length);
            }
        }

        if ($this->stream_handle) {
            fwrite($this->stream_handle, $data);
        }
        else {
            $this->response_data .= $data;
        }

        $this->response_bytes += strlen($data);
        return $data_length;
    }

    /**
     * Format a URL given GET data
     *
     * @param string $url
     * @param array|object $data Data to build query using, see {@see https://secure.php.net/http_build_query}
     * @return string URL with data
     */
    protected static function format_get($url, $data) {
        if (!empty($data)) {
            $query     = '';
            $url_parts = parse_url($url);
            if (empty($url_parts['query'])) {
                $url_parts['query'] = '';
            }
            else {
                $query = $url_parts['query'];
            }

            $query .= '&' . http_build_query($data, null, '&');
            $query  = trim($query, '&');

            if (empty($url_parts['query'])) {
                $url .= '?' . $query;
            }
            else {
                $url = str_replace($url_parts['query'], $query, $url);
            }
        }
        return $url;
    }

    /**
     * Whether this transport is valid
     *
     * @codeCoverageIgnore
     * @return boolean True if the transport is valid, false otherwise.
     */
    public static function test($capabilities = array()) {
        if (!function_exists('curl_init') || !function_exists('curl_exec')) {
            return false;
        }

        // If needed, check that our installed curl version supports SSL
        if (isset($capabilities['ssl']) && $capabilities['ssl']) {
            $curl_version = curl_version();
            if (!(CURL_VERSION_SSL & $curl_version['features'])) {
                return false;
            }
        }

        return true;
    }

    /**
     * Get the correct "Expect" header for the given request data.
     *
     * @param string|array $data Data to send either as the POST body, or as parameters in the URL for a GET/HEAD.
     * @return string The "Expect" header.
     */
    protected function get_expect_header($data) {
        if (!is_array($data)) {
            return strlen((string) $data) >= 1048576 ? '100-Continue' : '';
        }

        $bytesize = 0;
        $iterator = new RecursiveIteratorIterator(new RecursiveArrayIterator($data));

        foreach ($iterator as $datum) {
            $bytesize += strlen((string) $datum);

            if ($bytesize >= 1048576) {
                return '100-Continue';
            }
        }

        return '';
    }
}
Requests 1.8.1 API Documentation API documentation generated by ApiGen