Request.php

<?php

/*
 * This file is part of the ICanBoogie package.
 *
 * (c) Olivier Laviale <olivier.laviale@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace ICanBoogie\HTTP;

use ICanBoogie\Accessor\AccessorTrait;
use ICanBoogie\HTTP\Headers\ContentType;
use InvalidArgumentException;

use function file_get_contents;
use function ICanBoogie\normalize_url_path;
use function json_decode;

use const JSON_THROW_ON_ERROR;

/**
 * An HTTP request.
 *
 * ```php
 * <?php
 *
 * use ICanBoogie\HTTP\Request;
 *
 * # Creating the main request
 *
 * $request = Request::from($_SERVER);
 *
 * # Creating a request from scratch, with the current environment.
 *
 * $request = Request::from([
 *
 *     Request::OPTION_URI => '/path/to/my/page.html?page=2',
 *     Request::OPTION_USER_AGENT => 'Mozilla'
 *     Request::OPTION_IS_GET => true,
 *     Request::OPTION_IS_XHR => true,
 *     Request::OPTION_IS_LOCAL => true
 *
 * ], $_SERVER);
 * ```
 *
 * @method Response connect(array $params = null)
 * @method Response delete(array $params = null)
 * @method Response get(array $params = null)
 * @method Response head(array $params = null)
 * @method Response options(array $params = null)
 * @method Response post(array $params = null)
 * @method Response put(array $params = null)
 * @method Response patch(array $params = null)
 * @method Response trace(array $params = null)
 *
 * @property-read Request\Context $context the request's context.
 * @property-read Headers $headers the request's headers.
 * @property-read FileList $files the request's files.
 * @property-read bool $authorization Authorization of the request.
 * @property-read int $content_length Length of the request content.
 * @property-read string $ip Remote IP of the request.
 * @property-read bool $is_local Is this a local request?
 * @property-read bool $is_xhr Is this an Ajax request?
 * @property-read RequestMethod $method Method of the request.
 * @property-read string $normalized_path Path of the request normalized using the
 *     `\ICanBoogie\normalize_url_path` function.
 * @property-read string $path Path info of the request.
 * @property-read string $extension The extension of the path.
 * @property-read int $port Port of the request.
 * @property-read string $query_string Query string of the request.
 * @property-read string $script_name Name of the entered script.
 * @property-read string $referer Referer of the request.
 * @property-read string $user_agent User agent of the request.
 * @property-read string $uri URI of the request. The `QUERY_STRING` value of the environment
 * is overwritten when the instance is created with the `$uri` property.
 *
 * @link https://en.wikipedia.org/wiki/Uniform_resource_locator
 */
final class Request implements RequestOptions
{
    /**
     * @uses get_context
     * @uses get_headers
     * @uses get_script_name
     * @uses get_method
     * @uses get_query_string
     * @uses get_content_length
     * @uses get_referer
     * @uses get_user_agent
     * @uses get_is_xhr
     * @uses get_is_local
     * @uses get_ip
     * @uses get_authorization
     * @uses get_uri
     * @uses get_port
     * @uses get_path
     * @uses get_normalized_path
     * @uses get_extension
     */
    use AccessorTrait;

    /**
     * Parameters extracted from the request path.
     *
     * @var array<int|string, mixed>
     */
    public array $path_params = [];

    /**
     * Parameters defined by the query string.
     *
     * @var array<string, mixed>
     */
    public array $query_params = [];

    /**
     * Parameters defined by the request body.
     *
     * @var array<string, mixed>
     */
    public mixed $request_params = [];

    /**
     * Union of {@see $path_params}, {@see $request_params} and {@see $query_params}.
     *
     * **Note**: The property is created during construct and is not updated after. If you modify one of
     * {@see $path_params}, {@see $request_params} and {@see $query_params}, remember to modify {@see $params} as
     * well.
     *
     * @var array<string, mixed>
     */
    public array $params;

    /**
     * TODO: The property should be readonly but cloning is only available from PHP 8.3:
     * https://www.php.net/releases/8.3/en.php#readonly_classes
     */
    private Request\Context $context;

    private function get_context(): Request\Context
    {
        return $this->context;
    }

    /**
     * TODO: The property should be readonly but cloning is only available from PHP 8.3:
     * https://www.php.net/releases/8.3/en.php#readonly_classes
     */
    private Headers $headers;

    private function get_headers(): Headers
    {
        return $this->headers;
    }

    /**
     * Request environment.
     *
     * @var array<string, mixed>
     */
    private array $env;

    /**
     * Files associated with the request.
     *
     * **Note**: The field is not readonly because it can be overwritten by `with()`.
     */
    private FileList $files;

    private function get_files(): FileList
    {
        return $this->files;
    }

    public $cookie;

    /**
     * A request may be created from the `$_SERVER` super global array. In that case `$_SERVER` is
     * used as environment, the request is created with the following properties:
     *
     * - {@see $cookie}: a reference to the `$_COOKIE` super global.
     * - {@see $path_params}: initialized to an empty array.
     * - {@see $query_params}: a reference to the `$_GET` super global.
     * - {@see $request_params}: a reference to the `$_POST` super global.
     * - {@see $files}: a reference to the `$_FILES` super global.
     *
     * A request may also be created from an array of properties, in which case most of them are
     * mapped to the `$env` constructor param. For instance, `is_xhr` set the
     * `HTTP_X_REQUESTED_WITH` environment property to 'XMLHttpRequest'. In fact, only the
     * following options are preserved:
     *
     * - Request::OPTION_PATH_PARAMS
     * - Request::OPTION_QUERY_PARAMS
     * - Request::OPTION_REQUEST_PARAMS
     * - Request::OPTION_FILES: The files associated with the request.
     * - Request::OPTION_HEADERS: The header fields of the request. If specified, the headers
     * available in the environment are ignored.
     *
     * @phpstan-param array<RequestOptions::*, mixed>|string|null $properties Properties of the request.
     *
     * @param array<string, mixed> $env Environment, usually the `$_SERVER` array.
     *
     * @throws InvalidArgumentException in an attempt to use an unsupported option.
     */
    public static function from(array|string|null $properties = null, array $env = []): self
    {
        if (!$properties) {
            return new self([], $env);
        }

        if ($properties === $_SERVER) {
            return self::from_server();
        }

        if (is_string($properties)) {
            return self::from_uri($properties, $env);
        }

        return self::from_options($properties, $env);
    }

    /**
     * Creates an instance from the `$_SERVER` array.
     */
    private static function from_server(): self
    {
        $content_type = isset($_SERVER['HTTP_CONTENT_TYPE'])
            ? new ContentType($_SERVER['HTTP_CONTENT_TYPE'])
            : null;

        if ($content_type?->type === 'application/json') {
            $json = file_get_contents('php://input');
            $request_params = json_decode($json, true, flags: JSON_THROW_ON_ERROR);
        } else {
            $request_params = &$_POST;
        }

        return self::from([

            self::OPTION_COOKIE => &$_COOKIE,
            self::OPTION_PATH_PARAMS => [],
            self::OPTION_QUERY_PARAMS => &$_GET,
            self::OPTION_REQUEST_PARAMS => $request_params,
            self::OPTION_FILES => &$_FILES, // @codeCoverageIgnore

        ], $_SERVER);
    }

    /**
     * Creates an instance from a URI.
     *
     * @param array<string, mixed> $env
     */
    private static function from_uri(string $uri, array $env): self
    {
        return self::from([ self::OPTION_URI => $uri ], $env);
    }

    /**
     * Creates an instance from an array of properties.
     *
     * @param array<RequestOptions::*, mixed> $options
     * @param array<string, mixed> $env
     *
     * @throws MethodNotAllowed
     */
    private static function from_options(array $options, array $env): self
    {
        if ($options) {
            $options = RequestOptionsMapper::map($options, $env);
        }

        if (!empty($env['QUERY_STRING'])) {
            parse_str($env['QUERY_STRING'], $options[self::OPTION_QUERY_PARAMS]);
        }

        return new self($options, $env);
    }

    /**
     * Initialize the properties {@see $env}, {@see $headers} and {@see $context}.
     *
     * If the {@see $params} property is `null` it is set with a union of {@see $path_params},
     * {@see $request_params} and {@see $query_params}.
     *
     * @phpstan-param array<string, mixed> $options Initial properties.
     *
     * @param array<string, mixed> $env Environment of the request, usually the `$_SERVER` super global.
     *
     * @throws MethodNotAllowed when the request method is not supported.
     */
    private function __construct(array $options, array $env = [])
    {
        $this->context = new Request\Context($this);
        $this->env = $env;
        $this->headers = $options[self::OPTION_HEADERS] ?? new Headers($env);
        $this->files = $options[self::OPTION_FILES] ?? new FileList();
        $this->path_params = $options[self::OPTION_PATH_PARAMS] ?? [];
        $this->query_params = $options[self::OPTION_QUERY_PARAMS] ?? [];
        $this->request_params = $options[self::OPTION_REQUEST_PARAMS] ?? [];
        $this->params = $this->path_params + $this->request_params + $this->query_params;
        $this->cookie = $options[self::OPTION_COOKIE] ?? null;

        $this->assert_method($this->method);
    }

    /**
     * Clone {@see $headers} and {@see $context}, and unset {@see $params}.
     */
    public function __clone()
    {
        $this->headers = clone $this->headers;
        $this->context = clone $this->context;
    }

    /**
     * Asserts that a method is supported.
     */
    private function assert_method(RequestMethod $method): void
    {
    }

    /**
     * Returns a new instance with the specified changed properties.
     *
     * @param array<RequestOptions::*, mixed> $options
     */
    public function with(array $options): self
    {
        $changed = clone $this;

        if ($options) {
            $options = RequestOptionsMapper::map($options, $changed->env);

            foreach ($options as $option => &$value) {
                $changed->$option = $value;
            }
        }

        $changed->params = $changed->path_params + $changed->request_params + $changed->query_params;

        return $changed;
    }

    /**
     * Returns the script name.
     *
     * The setter is volatile, the value is returned from the ENV key `SCRIPT_NAME`.
     */
    private function get_script_name(): string
    {
        return $this->env['SCRIPT_NAME'];
    }

    /**
     * Returns the request method.
     *
     * This is the getter for the `method` magic property.
     *
     * The method is retrieved from {@see $env}, if the key `REQUEST_METHOD` is not defined,
     * the method defaults to {@see METHOD_GET}.
     */
    private function get_method(): RequestMethod
    {
        $method = RequestMethod::from_mixed($this->env['REQUEST_METHOD'] ?? 'GET');

        if ($method === RequestMethod::METHOD_POST && !empty($this->request_params['_method'])) {
            $method = RequestMethod::from_mixed($this->request_params['_method']);
        }

        return $method;
    }

    /**
     * Returns the query string of the request.
     *
     * The value is obtained from the `QUERY_STRING` key of the {@see $env} array.
     */
    private function get_query_string(): ?string
    {
        return $this->env['QUERY_STRING'] ?? null;
    }

    /**
     * Returns the content length of the request.
     *
     * The value is obtained from the `CONTENT_LENGTH` key of the {@see $env} array.
     */
    private function get_content_length(): ?int
    {
        return $this->env['CONTENT_LENGTH'] ?? null;
    }

    /**
     * Returns the referer of the request.
     *
     * The value is obtained from the `HTTP_REFERER` key of the {@see $env} array.
     */
    private function get_referer(): ?string
    {
        return $this->env['HTTP_REFERER'] ?? null;
    }

    /**
     * Returns the user agent of the request.
     *
     * The value is obtained from the `HTTP_USER_AGENT` key of the {@see $env} array.
     *
     * @return string|null
     */
    private function get_user_agent(): ?string
    {
        return $this->env['HTTP_USER_AGENT'] ?? null;
    }

    /**
     * Checks if the request is a `XMLHTTPRequest`.
     */
    private function get_is_xhr(): bool
    {
        return !empty($this->env['HTTP_X_REQUESTED_WITH'])
            && str_contains($this->env['HTTP_X_REQUESTED_WITH'], 'XMLHttpRequest');
    }

    /**
     * Checks if the request is local.
     */
    private function get_is_local(): bool
    {
        $ip = $this->ip;

        if ($ip == '::1' || preg_match('/^127\.0\.0\.\d{1,3}$/', $ip)) {
            return true;
        }

        return preg_match('/^0:0:0:0:0:0:0:1(%.*)?$/', $ip);
    }

    /**
     * Returns the remote IP of the request.
     *
     * If defined, the `HTTP_X_FORWARDED_FOR` header is used to retrieve the original IP.
     *
     * If the `REMOTE_ADDR` header is empty, the request is considered local; thus `::1` is returned.
     *
     * @link https://en.wikipedia.org/wiki/X-Forwarded-For
     */
    private function get_ip(): string
    {
        $forwarded_for = $this->headers['X-Forwarded-For'];

        if ($forwarded_for) {
            [ $ip ] = explode(',', $forwarded_for);

            return $ip;
        }

        return $this->env['REMOTE_ADDR'] ?? '::1';
    }

    private function get_authorization(): ?string
    {
        if (isset($this->env['HTTP_AUTHORIZATION'])) {
            return $this->env['HTTP_AUTHORIZATION'];
        } elseif (isset($this->env['X-HTTP_AUTHORIZATION'])) {
            return $this->env['X-HTTP_AUTHORIZATION'];
        } elseif (isset($this->env['X_HTTP_AUTHORIZATION'])) {
            return $this->env['X_HTTP_AUTHORIZATION'];
        } elseif (isset($this->env['REDIRECT_X_HTTP_AUTHORIZATION'])) {
            return $this->env['REDIRECT_X_HTTP_AUTHORIZATION'];
        }

        return null;
    }

    /**
     * Returns the `REQUEST_URI` environment key.
     *
     * If the `REQUEST_URI` key is not defined by the environment, the value is fetched from
     * the `$_SERVER` array. If the key is not defined in the `$_SERVER` array `null` is returned.
     */
    private function get_uri(): ?string
    {
        return $this->env['REQUEST_URI'] ?? ($_SERVER['REQUEST_URI'] ?? null);
    }

    /**
     * Returns the port of the request.
     */
    private function get_port(): int
    {
        return $this->env['REQUEST_PORT'];
    }

    /**
     * Returns the path of the request, that is the `REQUEST_URI` without the query string.
     */
    private function get_path(): string
    {
        $uri = $this->uri;
        $qs_pos = strpos($uri, '?');

        return ($qs_pos === false) ? $uri : substr($uri, 0, $qs_pos);
    }

    /**
     * Returns the {@see $path} property normalized using the
     * `ICanBoogie\normalize_url_path()` function.
     */
    private function get_normalized_path(): string
    {
        return normalize_url_path($this->path);
    }

    /**
     * Returns the extension of the path info.
     *
     * @return mixed
     */
    private function get_extension()
    {
        return pathinfo($this->path, PATHINFO_EXTENSION);
    }
}