Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

// GNU General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace core\router;

use core\exception\coding_exception;

use core\router\schema\parameter;

use core\router\schema\response\response;

use core\router\schema\request_body;

use Attribute;

/**

 * Routing attribute.

 *

 * @package    core

 * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]

class route {

    /** @var string[] The list of HTTP Methods */

    protected null|array $method = null;

    /**

     * The parent route, if relevant.

     *

     * A method-level route may have a class-level route as a parent. The two are combined to provide

     * a fully-qualified path.

     *

     * @var route|null

     */

    protected readonly ?route $parentroute;

    /**

     * Constructor for a new Moodle route.

     *

     * @param string $title A title to briefly describe the route (not translated)

     * @param string $description A verbose explanation of the operation behavior (not translated)

     * @param string $summary A short summary of what the operation does (not translated)

     * @param null|string[] $security A list of security mechanisms

     * @param null|string $path The path to match

     * @param null|array|string $method The method, or methods, supported

     * @param parameter[] $pathtypes Validators for the path arguments

     * @param parameter[] $queryparams Validators for the path arguments

     * @param parameter[] $headerparams Validators for the path arguments

     * @param request_body|null $requestbody Validators for the path arguments

     * @param response[] $responses A list of possible response types

     * @param bool $deprecated Whether this endpoint is deprecated

     * @param string[] $tags A list of tags

     * @param bool $cookies Whether this request requires cookies

     * @param bool $abortafterconfig Whether to abort after configuration

     * @param mixed[] ...$extra Any additional arguments not yet supported in this version of Moodle

     * @throws coding_exception

     */

    public function __construct(

        /** @var string A title to briefly describe the route (not translated) */

        public readonly string $title = '',

        /** @var string A verbose explanation of the operation behavior (not translated) */

        public readonly string $description = '',

        /** @var string A short summary of what the operation does (not translated) */

        public readonly string $summary = '',

        /** @var array<string> A list of security mechanisms */

        public readonly ?array $security = null,

        /**

         * The path to the route.

         *

         * This is relative to the parent route, if one exists.

         * A route must be set on one, or both, of the class and method level routes.

         *

         * @var string|null

         */

        public ?string $path = null,

        null|array|string $method = null,

        /** @var parameter[] A list of param types for path arguments */

        protected readonly array $pathtypes = [],

        /** @var parameter[] A list of query parameters with matching types */

        protected readonly array $queryparams = [],

        /** @var parameter[] A list of header parameters */

        protected readonly array $headerparams = [],

        /** @var null|request_body A list of parameters found in the body */

        public readonly ?request_body $requestbody = null,

        /** @var response[] A list of possible response types */

        protected readonly array $responses = [],

        /** @var bool Whether this endpoint is deprecated */

        public readonly bool $deprecated = false,

        /** @var string[] A list of tags */

        public readonly array $tags = [],

        /** @var bool Whether this request may use cookies */

        public readonly bool $cookies = true,

        /** @var bool Whether to abort after configuration */

        public readonly bool $abortafterconfig = false,

        /** @var null|array Whether to require login or not */

        public readonly ?require_login $requirelogin = null,

        /** @var string[] The list of scopes required to access this page */

        public readonly ?array $scopes = null,

        // Note. We do not make use of these extras.

        // These allow us to add additional arguments in future versions, whilst allowing plugins to use this version.

        ...$extra,

    ) {

        // Normalise the method.

        if (is_string($method)) {

            $method = [$method];

        }

        $this->method = $method;

        // Validate the query parameters.

        if (count(array_filter($this->queryparams, fn($pathtype) => !is_a($pathtype, parameter::class)))) {

            throw new coding_exception('All query parameters must be an instance of \core\router\parameter.');

        }

        if (count(array_filter($this->queryparams, fn($pathtype) => $pathtype->get_in() !== 'query'))) {

            throw new coding_exception('All query parameters must be in the query.');

        }

        // Validate the path parameters.

        if (count(array_filter($this->pathtypes, fn($pathtype) => !is_a($pathtype, parameter::class)))) {

            throw new coding_exception('All path parameters must be an instance of \core\router\parameter.');

        }

        if (count(array_filter($this->pathtypes, fn($pathtype) => $pathtype->get_in() !== 'path'))) {

            throw new coding_exception('All path properties must be in the path.');

        }

        // Validate the header parameters.

        if (count(array_filter($this->headerparams, fn($pathtype) => !is_a($pathtype, parameter::class)))) {

            throw new coding_exception('All path parameters must be an instance of \core\router\parameter.');

        }

        if (count(array_filter($this->headerparams, fn($pathtype) => $pathtype->get_in() !== 'header'))) {

            throw new coding_exception('All header properties must be in the path.');

        }

    }

    /**

     * Set the parent route, usually a Class-level route.

     *

     * @param route $parent

     * @return self

     */

    public function set_parent(route $parent): self {

        $this->parentroute = $parent;

        return $this;

    }

    /**

     * Get the fully-qualified path for this route relative to root.

     *

     * This includes the path of any parent route.

     *

     * @return string

     */

    public function get_path(): string {

        $path = $this->path ?? '';

        if (isset($this->parentroute)) {

            $path = $this->parentroute->get_path() . $path;

        }

        return $path;

    }

    /**

     * Get the list of HTTP methods associated with this route.

     *

     * @param null|string[] $default The default methods to use if none are set

     * @return null|string[]

     */

    public function get_methods(?array $default = null): ?array {

        $methods = $this->method;

        if (isset($this->parentroute)) {

            $parentmethods = $this->parentroute->get_methods();

            if ($methods) {

                $methods = array_unique(

                    array_merge($parentmethods ?? [], $methods),

                );

            } else {

                $methods = $parentmethods;

            }

        }

        // If there are no methods from either this attribute or any parent, use the default.

        $methods = $methods ?? $default;

        if ($methods) {

            sort($methods);

        }

        return $methods;

    }

    /**

     * Get the list of path parameters, including any from the parent.

     *

     * @return array

     */

    public function get_path_parameters(): array {

        $parameters = [];

        if (isset($this->parentroute)) {

            $parameters = $this->parentroute->get_path_parameters();

        }

        foreach ($this->pathtypes as $parameter) {

            $parameters[$parameter->get_name()] = $parameter;

        }

        return $parameters;

    }

    /**

     * Get the list of path parameters, including any from the parent.

     *

     * @return array

     */

    public function get_header_parameters(): array {

        $parameters = [];

        if (isset($this->parentroute)) {

            $parameters = $this->parentroute->get_header_parameters();

        }

        foreach ($this->headerparams as $parameter) {

            $parameters[$parameter->get_name()] = $parameter;

        }

        return $parameters;

    }

    /**

     * Get the list of path parameters, including any from the parent.

     *

     * @return array

     */

    public function get_query_parameters(): array {

        $parameters = [];

        if (isset($this->parentroute)) {

            $parameters = $this->parentroute->get_query_parameters();

        }

        foreach ($this->queryparams as $parameter) {

            $parameters[$parameter->get_name()] = $parameter;

        }

        return $parameters;

    }

    /**

     * Get the request body for this route.

     *

     * @return request_body|null

     */

    public function get_request_body(): ?request_body {

        return $this->requestbody;

    }

    /**

     * Whether this route expects a request body.

     *

     * @return bool

     */

    public function has_request_body(): bool {

        return $this->requestbody !== null;

    }

    /**

     * Get all responses.

     *

     * @return response[]

     */

    public function get_responses(): array {

        return $this->responses;

    }

    /**

     * Get the response with the specified response code.

     *

     * @param int $statuscode

     * @return response|null

     */

    public function get_response_with_status_code(int $statuscode): ?response {

        foreach ($this->get_responses() as $response) {

            if ($response->get_status_code() === $statuscode) {

                return $response;

            }

        }

        return null;

    }

    /**

     * Whether this route expects any validatable parameters.

     * That is, any parameter in the path, query params, or the request body.

     *

     * @return bool

     */

    public function has_any_validatable_parameter(): bool {

        return count($this->get_path_parameters()) || count($this->get_query_parameters()) || $this->has_request_body();

    }

}