<?php

/**

 * Requests for PHP

 *

 * Inspired by Requests for Python.

 *

 * Based on concepts from SimplePie_File, RequestCore and WP_Http.

 *

 * @package Requests

 */

namespace WpOrg\Requests;

use WpOrg\Requests\Auth\Basic;

use WpOrg\Requests\Capability;

use WpOrg\Requests\Cookie\Jar;

use WpOrg\Requests\Exception;

use WpOrg\Requests\Exception\InvalidArgument;

use WpOrg\Requests\Hooks;

use WpOrg\Requests\IdnaEncoder;

use WpOrg\Requests\Iri;

use WpOrg\Requests\Proxy\Http;

use WpOrg\Requests\Response;

use WpOrg\Requests\Transport\Curl;

use WpOrg\Requests\Transport\Fsockopen;

use WpOrg\Requests\Utility\InputValidator;

/**

 * Requests for PHP

 *

 * Inspired by Requests for Python.

 *

 * Based on concepts from SimplePie_File, RequestCore and WP_Http.

 *

 * @package Requests

 */

class Requests {

	/**

	 * POST method

	 *

	 * @var string

	 */

	const POST = 'POST';

	/**

	 * PUT method

	 *

	 * @var string

	 */

	const PUT = 'PUT';

	/**

	 * GET method

	 *

	 * @var string

	 */

	const GET = 'GET';

	/**

	 * HEAD method

	 *

	 * @var string

	 */

	const HEAD = 'HEAD';

	/**

	 * DELETE method

	 *

	 * @var string

	 */

	const DELETE = 'DELETE';

	/**

	 * OPTIONS method

	 *

	 * @var string

	 */

	const OPTIONS = 'OPTIONS';

	/**

	 * TRACE method

	 *

	 * @var string

	 */

	const TRACE = 'TRACE';

	/**

	 * PATCH method

	 *

	 * @link https://tools.ietf.org/html/rfc5789

	 * @var string

	 */

	const PATCH = 'PATCH';

	/**

	 * Default size of buffer size to read streams

	 *

	 * @var integer

	 */

	const BUFFER_SIZE = 1160;

	/**

	 * Option defaults.

	 *

	 * @see \WpOrg\Requests\Requests::get_default_options()

	 * @see \WpOrg\Requests\Requests::request() for values returned by this method

	 *

	 * @since 2.0.0

	 *

	 * @var array

	 */

	const OPTION_DEFAULTS = [

		'timeout'          => 10,

		'connect_timeout'  => 10,

		'useragent'        => 'php-requests/' . self::VERSION,

		'protocol_version' => 1.1,

		'redirected'       => 0,

		'redirects'        => 10,

		'follow_redirects' => true,

		'blocking'         => true,

		'type'             => self::GET,

		'filename'         => false,

		'auth'             => false,

		'proxy'            => false,

		'cookies'          => false,

		'max_bytes'        => false,

		'idn'              => true,

		'hooks'            => null,

		'transport'        => null,

		'verify'           => null,

		'verifyname'       => true,

	];

	/**

	 * Default supported Transport classes.

	 *

	 * @since 2.0.0

	 *

	 * @var array

	 */

	const DEFAULT_TRANSPORTS = [

		Curl::class      => Curl::class,

		Fsockopen::class => Fsockopen::class,

	];

	/**

	 * Current version of Requests

	 *

	 * @var string

	 */

	const VERSION = '2.0.11';

	/**

	 * Selected transport name

	 *

	 * Use {@see \WpOrg\Requests\Requests::get_transport()} instead

	 *

	 * @var array

	 */

	public static $transport = [];

	/**

	 * Registered transport classes

	 *

	 * @var array

	 */

	protected static $transports = [];

	/**

	 * Default certificate path.

	 *

	 * @see \WpOrg\Requests\Requests::get_certificate_path()

	 * @see \WpOrg\Requests\Requests::set_certificate_path()

	 *

	 * @var string

	 */

	protected static $certificate_path = __DIR__ . '/../certificates/cacert.pem';

	/**

	 * All (known) valid deflate, gzip header magic markers.

	 *

	 * These markers relate to different compression levels.

	 *

	 * @link https://stackoverflow.com/a/43170354/482864 Marker source.

	 *

	 * @since 2.0.0

	 *

	 * @var array

	 */

	private static $magic_compression_headers = [

		"\x1f\x8b" => true, // Gzip marker.

		"\x78\x01" => true, // Zlib marker - level 1.

		"\x78\x5e" => true, // Zlib marker - level 2 to 5.

		"\x78\x9c" => true, // Zlib marker - level 6.

		"\x78\xda" => true, // Zlib marker - level 7 to 9.

	];

	/**

	 * This is a static class, do not instantiate it

	 *

	 * @codeCoverageIgnore

	 */

	private function __construct() {}

	/**

	 * Register a transport

	 *

	 * @param string $transport Transport class to add, must support the \WpOrg\Requests\Transport interface

	 */

	public static function add_transport($transport) {

		if (empty(self::$transports)) {

			self::$transports = self::DEFAULT_TRANSPORTS;

		}

		self::$transports[$transport] = $transport;

	}

	/**

	 * Get the fully qualified class name (FQCN) for a working transport.

	 *

	 * @param array<string, bool> $capabilities Optional. Associative array of capabilities to test against, i.e. `['<capability>' => true]`.

	 * @return string FQCN of the transport to use, or an empty string if no transport was

	 *                found which provided the requested capabilities.

	 */

	protected static function get_transport_class(array $capabilities = []) {

		// Caching code, don't bother testing coverage.

		// @codeCoverageIgnoreStart

		// Array of capabilities as a string to be used as an array key.

		ksort($capabilities);

		$cap_string = serialize($capabilities);

		// Don't search for a transport if it's already been done for these $capabilities.

		if (isset(self::$transport[$cap_string])) {

			return self::$transport[$cap_string];

		}

		// Ensure we will not run this same check again later on.

		self::$transport[$cap_string] = '';

		// @codeCoverageIgnoreEnd

		if (empty(self::$transports)) {

			self::$transports = self::DEFAULT_TRANSPORTS;

		}

		// Find us a working transport.

		foreach (self::$transports as $class) {

			if (!class_exists($class)) {

				continue;

			}

			$result = $class::test($capabilities);

			if ($result === true) {

				self::$transport[$cap_string] = $class;

				break;

			}

		}

		return self::$transport[$cap_string];

	}

	/**

	 * Get a working transport.

	 *

	 * @param array<string, bool> $capabilities Optional. Associative array of capabilities to test against, i.e. `['<capability>' => true]`.

	 * @return \WpOrg\Requests\Transport

	 * @throws \WpOrg\Requests\Exception If no valid transport is found (`notransport`).

	 */

	protected static function get_transport(array $capabilities = []) {

		$class = self::get_transport_class($capabilities);

		if ($class === '') {

			throw new Exception('No working transports found', 'notransport', self::$transports);

		}

		return new $class();

	}

	/**

	 * Checks to see if we have a transport for the capabilities requested.

	 *

	 * Supported capabilities can be found in the {@see \WpOrg\Requests\Capability}

	 * interface as constants.

	 *

	 * Example usage:

	 * `Requests::has_capabilities([Capability::SSL => true])`.

	 *

	 * @param array<string, bool> $capabilities Optional. Associative array of capabilities to test against, i.e. `['<capability>' => true]`.

	 * @return bool Whether the transport has the requested capabilities.

	 */

	public static function has_capabilities(array $capabilities = []) {

		return self::get_transport_class($capabilities) !== '';

	}

	/**#@+

	 * @see \WpOrg\Requests\Requests::request()

	 * @param string $url

	 * @param array $headers

	 * @param array $options

	 * @return \WpOrg\Requests\Response

	 */

	/**

	 * Send a GET request

	 */

	public static function get($url, $headers = [], $options = []) {

		return self::request($url, $headers, null, self::GET, $options);

	}

	/**

	 * Send a HEAD request

	 */

	public static function head($url, $headers = [], $options = []) {

		return self::request($url, $headers, null, self::HEAD, $options);

	}

	/**

	 * Send a DELETE request

	 */

	public static function delete($url, $headers = [], $options = []) {

		return self::request($url, $headers, null, self::DELETE, $options);

	}

	/**

	 * Send a TRACE request

	 */

	public static function trace($url, $headers = [], $options = []) {

		return self::request($url, $headers, null, self::TRACE, $options);

	}

	/**#@-*/

	/**#@+

	 * @see \WpOrg\Requests\Requests::request()

	 * @param string $url

	 * @param array $headers

	 * @param array $data

	 * @param array $options

	 * @return \WpOrg\Requests\Response

	 */

	/**

	 * Send a POST request

	 */

	public static function post($url, $headers = [], $data = [], $options = []) {

		return self::request($url, $headers, $data, self::POST, $options);

	}

	/**

	 * Send a PUT request

	 */

	public static function put($url, $headers = [], $data = [], $options = []) {

		return self::request($url, $headers, $data, self::PUT, $options);

	}

	/**

	 * Send an OPTIONS request

	 */

	public static function options($url, $headers = [], $data = [], $options = []) {

		return self::request($url, $headers, $data, self::OPTIONS, $options);

	}

	/**

	 * Send a PATCH request

	 *

	 * Note: Unlike {@see \WpOrg\Requests\Requests::post()} and {@see \WpOrg\Requests\Requests::put()},

	 * `$headers` is required, as the specification recommends that should send an ETag

	 *

	 * @link https://tools.ietf.org/html/rfc5789

	 */

	public static function patch($url, $headers, $data = [], $options = []) {

		return self::request($url, $headers, $data, self::PATCH, $options);

	}

	/**#@-*/

	/**

	 * Main interface for HTTP requests

	 *

	 * This method initiates a request and sends it via a transport before

	 * parsing.

	 *

	 * The `$options` parameter takes an associative array with the following

	 * options:

	 *

	 * - `timeout`: How long should we wait for a response?

	 *    Note: for cURL, a minimum of 1 second applies, as DNS resolution

	 *    operates at second-resolution only.

	 *    (float, seconds with a millisecond precision, default: 10, example: 0.01)

	 * - `connect_timeout`: How long should we wait while trying to connect?

	 *    (float, seconds with a millisecond precision, default: 10, example: 0.01)

	 * - `useragent`: Useragent to send to the server

	 *    (string, default: php-requests/$version)

	 * - `follow_redirects`: Should we follow 3xx redirects?

	 *    (boolean, default: true)

	 * - `redirects`: How many times should we redirect before erroring?

	 *    (integer, default: 10)

	 * - `blocking`: Should we block processing on this request?

	 *    (boolean, default: true)

	 * - `filename`: File to stream the body to instead.

	 *    (string|boolean, default: false)

	 * - `auth`: Authentication handler or array of user/password details to use

	 *    for Basic authentication

	 *    (\WpOrg\Requests\Auth|array|boolean, default: false)

	 * - `proxy`: Proxy details to use for proxy by-passing and authentication

	 *    (\WpOrg\Requests\Proxy|array|string|boolean, default: false)

	 * - `max_bytes`: Limit for the response body size.

	 *    (integer|boolean, default: false)

	 * - `idn`: Enable IDN parsing

	 *    (boolean, default: true)

	 * - `transport`: Custom transport. Either a class name, or a

	 *    transport object. Defaults to the first working transport from

	 *    {@see \WpOrg\Requests\Requests::getTransport()}

	 *    (string|\WpOrg\Requests\Transport, default: {@see \WpOrg\Requests\Requests::getTransport()})

	 * - `hooks`: Hooks handler.

	 *    (\WpOrg\Requests\HookManager, default: new WpOrg\Requests\Hooks())

	 * - `verify`: Should we verify SSL certificates? Allows passing in a custom

	 *    certificate file as a string. (Using true uses the system-wide root

	 *    certificate store instead, but this may have different behaviour

	 *    across transports.)

	 *    (string|boolean, default: certificates/cacert.pem)

	 * - `verifyname`: Should we verify the common name in the SSL certificate?

	 *    (boolean, default: true)

	 * - `data_format`: How should we send the `$data` parameter?

	 *    (string, one of 'query' or 'body', default: 'query' for

	 *    HEAD/GET/DELETE, 'body' for POST/PUT/OPTIONS/PATCH)

	 *

	 * @param string|Stringable $url URL to request

	 * @param array $headers Extra headers to send with the request

	 * @param array|null $data Data to send either as a query string for GET/HEAD requests, or in the body for POST requests

	 * @param string $type HTTP request type (use Requests constants)

	 * @param array $options Options for the request (see description for more information)

	 * @return \WpOrg\Requests\Response

	 *

	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed $url argument is not a string or Stringable.

	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed $type argument is not a string.

	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed $options argument is not an array.

	 * @throws \WpOrg\Requests\Exception On invalid URLs (`nonhttp`)

	 */

	public static function request($url, $headers = [], $data = [], $type = self::GET, $options = []) {

		if (InputValidator::is_string_or_stringable($url) === false) {

			throw InvalidArgument::create(1, '$url', 'string|Stringable', gettype($url));

		}

		if (is_string($type) === false) {

			throw InvalidArgument::create(4, '$type', 'string', gettype($type));

		}

		if (is_array($options) === false) {

			throw InvalidArgument::create(5, '$options', 'array', gettype($options));

		}

		if (empty($options['type'])) {

			$options['type'] = $type;

		}

		$options = array_merge(self::get_default_options(), $options);