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;

use coding_exception;

use core_text;

use core\attribute\deprecated;

use core\ip_utils;

use invalid_parameter_exception;

use moodle_exception;

// phpcs:disable Generic.CodeAnalysis.EmptyStatement.DetectedIf

/**

 * Parameter validation helpers for Moodle.

 *

 * @package    core

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

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

 */

enum param: string {

    /**

     * PARAM_ALPHA - contains only English ascii letters [a-zA-Z].

     */

    #[param_clientside_regex('^[a-zA-Z]+$')]

    case ALPHA = 'alpha';

    /**

     * PARAM_ALPHAEXT the same contents as PARAM_ALPHA (English ascii letters [a-zA-Z]) plus the chars in quotes: "_-" allowed

     * NOTE: originally this allowed "/" too, please use PARAM_SAFEPATH if "/" needed

     */

    #[param_clientside_regex('^[a-zA-Z_\-]*$')]

    case ALPHAEXT = 'alphaext';

    /**

     * PARAM_ALPHANUM - expected numbers 0-9 and English ascii letters [a-zA-Z] only.

     */

    #[param_clientside_regex('^[a-zA-Z0-9]*$')]

    case ALPHANUM = 'alphanum';

    /**

     * PARAM_ALPHANUMEXT - expected numbers 0-9, letters (English ascii letters [a-zA-Z]) and _- only.

     */

    #[param_clientside_regex('^[a-zA-Z0-9_\-]*$')]

    case ALPHANUMEXT = 'alphanumext';

    /**

     * PARAM_AUTH - actually checks to make sure the string is a valid auth plugin

     */

    case AUTH = 'auth';

    /**

     * PARAM_BASE64 - Base 64 encoded format

     */

    case BASE64 = 'base64';

    /**

     * PARAM_BOOL - converts input into 0 or 1, use for switches in forms and urls.

     */

    case BOOL = 'bool';

    /**

     * PARAM_CAPABILITY - A capability name, like 'moodle/role:manage'. Actually

     * checked against the list of capabilities in the database.

     */

    case CAPABILITY = 'capability';

    /**

     * PARAM_CLEANHTML - cleans submitted HTML code. Note that you almost never want

     * to use this. The normal mode of operation is to use PARAM_RAW when receiving

     * the input (required/optional_param or formslib) and then sanitise the HTML

     * using format_text on output. This is for the rare cases when you want to

     * sanitise the HTML on input. This cleaning may also fix xhtml strictness.

     */

    case CLEANHTML = 'cleanhtml';

    /**

     * PARAM_EMAIL - an email address following the RFC

     */

    case EMAIL = 'email';

    /**

     * PARAM_FILE - safe file name, all dangerous chars are stripped, protects against XSS, SQL injections and directory traversals

     */

    case FILE = 'file';

    /**

     * PARAM_FLOAT - a real/floating point number.

     *

     * Note that you should not use PARAM_FLOAT for numbers typed in by the user.

     * It does not work for languages that use , as a decimal separator.

     * Use PARAM_LOCALISEDFLOAT instead.

     */

    case FLOAT = 'float';

    /**

     * PARAM_LOCALISEDFLOAT - a localised real/floating point number.

     * This is preferred over PARAM_FLOAT for numbers typed in by the user.

     * Cleans localised numbers to computer readable numbers; false for invalid numbers.

     */

    #[param_clientside_regex('^\d*([\.,])\d+$')]

    case LOCALISEDFLOAT = 'localisedfloat';

    /**

     * PARAM_HOST - expected fully qualified domain name (FQDN) or an IPv4 dotted quad (IP address)

     */

    case HOST = 'host';

    /**

     * PARAM_INT - integers only, use when expecting only numbers.

     */

    case INT = 'int';

    /**

     * PARAM_LANG - checks to see if the string is a valid installed language in the current site.

     */

    case LANG = 'lang';

    /**

     * PARAM_LOCALURL - expected properly formatted URL as well as one that refers to the local server itself. (NOT orthogonal to the

     * others! Implies PARAM_URL!)

     */

    case LOCALURL = 'localurl';

    /**

     * PARAM_NOTAGS - all html tags are stripped from the text. Do not abuse this type.

     */

    case NOTAGS = 'notags';

    /**

     * PARAM_PATH - safe relative path name, all dangerous chars are stripped, protects against XSS, SQL injections and directory

     * traversals note: the leading slash is not removed, window drive letter is not allowed

     */

    case PATH = 'path';

    /**

     * PARAM_PEM - Privacy Enhanced Mail format

     */

    case PEM = 'pem';

    /**

     * PARAM_PERMISSION - A permission, one of CAP_INHERIT, CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT.

     */

    case PERMISSION = 'permission';

    /**

     * PARAM_RAW specifies a parameter that is not cleaned/processed in any way except the discarding of the invalid utf-8 characters

     */

    case RAW = 'raw';

    /**

     * PARAM_RAW_TRIMMED like PARAM_RAW but leading and trailing whitespace is stripped.

     */

    case RAW_TRIMMED = 'raw_trimmed';

    /**

     * PARAM_SAFEDIR - safe directory name, suitable for include() and require()

     */

    #[param_clientside_regex('^[a-zA-Z0-9_\-]*$')]

    case SAFEDIR = 'safedir';

    /**

     * PARAM_SAFEPATH - several PARAM_SAFEDIR joined by "/", suitable for include() and require(), plugin paths

     * and other references to Moodle code files.

     *

     * This is NOT intended to be used for absolute paths or any user uploaded files.

     */

    #[param_clientside_regex('^[a-zA-Z0-9\/_\-]*$')]

    case SAFEPATH = 'safepath';

    /**

     * PARAM_SEQUENCE - expects a sequence of numbers like 8 to 1,5,6,4,6,8,9.  Numbers and comma only.

     */

    #[param_clientside_regex('^[0-9,]*$')]

    case SEQUENCE = 'sequence';

    /**

     * PARAM_TAG - one tag (interests, blogs, etc.) - mostly international characters and space, <> not supported

     */

    case TAG = 'tag';

    /**

     * PARAM_TAGLIST - list of tags separated by commas (interests, blogs, etc.)

     */

    case TAGLIST = 'taglist';

    /**

     * PARAM_TEXT - general plain text compatible with multilang filter, no other html tags. Please note '<', or '>' are allowed here.

     */

    case TEXT = 'text';

    /**

     * PARAM_THEME - Checks to see if the string is a valid theme name in the current site

     */

    case THEME = 'theme';

    /**

     * PARAM_URL - expected properly formatted URL. Please note that domain part is required, http://localhost/ is not accepted but

     * http://localhost.localdomain/ is ok.

     */

    case URL = 'url';

    /**

     * PARAM_USERNAME - Clean username to only contains allowed characters. This is to be used ONLY when manually creating user

     * accounts, do NOT use when syncing with external systems!!

     */

    case USERNAME = 'username';

    /**

     * PARAM_STRINGID - used to check if the given string is valid string identifier for get_string()

     */

    case STRINGID = 'stringid';

    /**

     * PARAM_CLEAN - obsoleted, please use a more specific type of parameter.

     * It was one of the first types, that is why it is abused so much ;-)

     * @deprecated since 2.0

     */

    #[deprecated(

        replacement: 'a more specific type of parameter',

        since: '2.0',

        reason: 'The CLEAN param type is too generic to perform satisfactory validation',

        emit: false,

    )]

    case CLEAN = 'clean';

    /**

     * PARAM_INTEGER - deprecated alias for PARAM_INT

     * @deprecated since 2.0

     */

    #[deprecated(

        replacement: 'param::INT',

        since: '2.0',

        reason: 'Alias for INT',

        final: true,

    )]

    case INTEGER = 'integer';

    /**

     * PARAM_NUMBER - deprecated alias of PARAM_FLOAT

     * @deprecated since 2.0

     */

    #[deprecated(

        replacement: 'param::FLOAT',

        since: '2.0',

        reason: 'Alias for FLOAT',

        final: true,

    )]

    case NUMBER = 'number';

    /**

     * PARAM_ACTION - deprecated alias for PARAM_ALPHANUMEXT, use for various actions in forms and urls

     * NOTE: originally alias for PARAM_ALPHANUMEXT

     * @deprecated since 2.0

     */

    #[deprecated(

        replacement: 'param::ALPHANUMEXT',

        since: '2.0',

        reason: 'Alias for PARAM_ALPHANUMEXT',

        final: true,

    )]

    case ACTION = 'action';

    /**

     * PARAM_FORMAT - deprecated alias for PARAM_ALPHANUMEXT, use for names of plugins, formats, etc.

     * NOTE: originally alias for PARAM_APLHA

     * @deprecated since 2.0

     */

    #[deprecated(

        replacement: 'param::ALPHANUMEXT',

        since: '2.0',

        reason: 'Alias for PARAM_ALPHANUMEXT',

        final: true,

    )]

    case FORMAT = 'format';

    /**

     * PARAM_MULTILANG - deprecated alias of PARAM_TEXT.

     * @deprecated since 2.0

     */

    #[deprecated(

        replacement: 'param::TEXT',

        since: '2.0',

        reason: 'Alias for PARAM_TEXT',

        final: true,

    )]

    case MULTILANG = 'multilang';

    /**

     * PARAM_TIMEZONE - expected timezone. Timezone can be int +-(0-13) or float +-(0.5-12.5) or

     * string separated by '/' and can have '-' &/ '_' (eg. America/North_Dakota/New_Salem

     * America/Port-au-Prince)

     */

    case TIMEZONE = 'timezone';

    /**

     * PARAM_CLEANFILE - deprecated alias of PARAM_FILE; originally was removing regional chars too

     * @deprecated since 2.0

     */

    #[deprecated(

        replacement: 'param::FILE',

        since: '2.0',

        reason: 'Alias for PARAM_FILE',

    )]

    case CLEANFILE = 'cleanfile';

    /**

     * PARAM_COMPONENT is used for full component names (aka frankenstyle) such as 'mod_forum = 'core_rating', 'auth_ldap'.

     * Short legacy subsystem names and module names are accepted too ex: 'forum = 'rating', 'user'.

     * Only lowercase ascii letters, numbers and underscores are allowed, it has to start with a letter.

     * NOTE: numbers and underscores are strongly discouraged in plugin names!

     */

    #[param_clientside_regex('^[a-z][a-z0-9]*(_(?:[a-z][a-z0-9_](?!__))*)?[a-z0-9]+$')]

    case COMPONENT = 'component';

    /**

     * PARAM_AREA is a name of area used when addressing files, comments, ratings, etc.

     * It is usually used together with context id and component.

     * Only lowercase ascii letters, numbers and underscores are allowed, it has to start with a letter.

     */

    #[param_clientside_regex('^[a-z](?:[a-z0-9_](?!__))*[a-z0-9]+$')]

    case AREA = 'area';

    /**

     * PARAM_PLUGIN is used for plugin names such as 'forum = 'glossary', 'ldap', 'paypal', 'completionstatus'.

     * Only lowercase ascii letters, numbers and underscores are allowed, it has to start with a letter.

     * NOTE: numbers and underscores are strongly discouraged in plugin names! Underscores are forbidden in module names.

     */

    #[param_clientside_regex('^[a-z](?:[a-z0-9_](?!__))*[a-z0-9]+$')]

    case PLUGIN = 'plugin';

    /**

     * Get the canonical enumerated parameter from the parameter type name.

     *

     * @param string $paramname

     * @return param

     * @throws coding_exception If the parameter is unknown.

     */

    public static function from_type(string $paramname): self {

        $from = self::tryFrom($paramname)?->canonical();

        if ($from) {

            return $from;

        }

        throw new \coding_exception("Unknown parameter type '{$paramname}'");

    }

    /**

     * Canonicalise the parameter.

     *

     * This method is used to support aliasing of deprecated parameters.

     *

     * @return param

     */

    private function canonical(): self {

        return match ($this) {

            self::ACTION => self::ALPHANUMEXT,

            self::CLEANFILE => self::FILE,

            self::FORMAT => self::ALPHANUMEXT,

            self::INTEGER => self::INT,

            self::MULTILANG => self::TEXT,

            self::NUMBER => self::FLOAT,

            default => $this,

        };

    }

    /**

     * Used by {@link optional_param()} and {@link required_param()} to

     * clean the variables and/or cast to specific types, based on

     * an options field.

     *

     * <code>

     * $course->format = param::ALPHA->clean($course->format);

     * $selectedgradeitem = param::INT->clean($selectedgradeitem);

     * </code>

     *

     * @param mixed $value the value to clean

     * @return mixed

     * @throws coding_exception

     */

    public function clean(mixed $value): mixed {

        // Check and emit a deprecation notice if required.

        deprecation::emit_deprecation_if_present($this);

        if (is_array($value)) {

            throw new coding_exception('clean() can not process arrays, please use clean_array() instead.');

        } else if (is_object($value)) {

            if (method_exists($value, '__toString')) {

                $value = $value->__toString();

            } else {

                throw new coding_exception('clean() can not process objects, please use clean_array() instead.');

            }

        }

        $canonical = $this->canonical();

        if ($this !== $canonical) {

            return $canonical->clean($value);

        }

        $methodname = "clean_param_value_{$this->value}";

        if (!method_exists(self::class, $methodname)) {

            throw new coding_exception("Method not found for cleaning {$this->value}");

        }

        return $this->{$methodname}($value);

    }

    /**

     * Get the clientside regular expression for this parameter.

     *

     * @return null|string

     */

    public function get_clientside_expression(): ?string {

        $ref = new \ReflectionClassConstant(self::class, $this->name);

        $attributes = $ref->getAttributes(param_clientside_regex::class);

        if (count($attributes) === 0) {

            return null;

        }

        return $attributes[0]->newInstance()->regex;

    }

    /**

     * Returns a value for the named variable, taken from request arguments.

     *

     * This function should be used to initialise all required values

     * in a script that are based on parameters.  Usually it will be

     * used like this:

     *    $id = param::INT->required_param('id');

     *

     *

     * @param string $paramname the name of the page parameter we want

     * @return mixed

     * @throws moodle_exception

     */

    public function required_param(string $paramname): mixed {

        return $this->clean($this->get_request_parameter($paramname, true));

    }

    /**

     * Returns a particular array value for the named variable, taken from request arguments.

     * If the parameter doesn't exist then an error is thrown because we require this variable.

     *

     * This function should be used to initialise all required values

     * in a script that are based on parameters.  Usually it will be

     * used like this:

     *    $ids = required_param_array('ids', PARAM_INT);

     *

     * Note: arrays of arrays are not supported, only alphanumeric keys with _ and - are supported

     *

     * @param string $paramname the name of the page parameter we want

     * @return array

     * @throws moodle_exception

     */

    public function required_param_array(string $paramname): array {

        $param = $this->get_request_parameter($paramname, true);

        if (!is_array($param)) {

            throw new \moodle_exception('missingparam', '', '', $paramname);

        }

        $result = [];

        foreach ($param as $key => $value) {

            if (!preg_match('/^[a-z0-9_-]+$/i', $key)) {

                debugging(

                    "Invalid key name in required_param_array() detected: {$key}, parameter: {$paramname}",

                );

                continue;

            }

            $result[$key] = $this->clean($value);

        }

        return $result;

    }

    /**

     * Returns a particular value for the named variable from the request arguments,

     * otherwise returning a given default.

     *

     * This function should be used to initialise all optional values

     * in a script that are based on parameters.  Usually it will be

     * used like this:

     *    $name = param::TEXT->optional_param('name', 'Fred');

     *

     * @param string $paramname the name of the page parameter we want

     * @param mixed  $default the default value to return if nothing is found

     * @return mixed

     */

    public function optional_param(string $paramname, mixed $default): mixed {

        $param = $this->get_request_parameter($paramname, false);

        if ($param === null) {

            return $default;

        }

        return $this->clean($param);

    }

    /**

     * Returns a particular array value for the named variable from the request arguments,

     * otherwise returning a given default.

     *

     * This function should be used to initialise all optional values

     * in a script that are based on parameters.  Usually it will be

     * used like this:

     *    $ids = param::INT->optional_param_arrayt('id', array());

     *

     * Note: arrays of arrays are not supported, only alphanumeric keys with _ and - are supported.

     *

     * @param string $paramname the name of the page parameter we want

     * @param mixed $default the default value to return if nothing is found

     * @return array

     */

    public function optional_param_array(string $paramname, mixed $default): mixed {

        $param = $this->get_request_parameter($paramname, false);

        if ($param === null) {

            return $default;

        }

        if (!is_array($param)) {

            debugging(

                "optional_param_array() only expects array parameters: {$paramname}",

            );

            return $default;

        }

        $result = [];

        foreach ($param as $key => $value) {

            if (!preg_match('/^[a-z0-9_-]+$/i', $key)) {

                debugging(

                    "Invalid key name in optional_param_array() detected: {$key}, parameter: {$paramname}",

                );

                continue;

            }

            $result[$key] = $this->clean($value);

        }

        return $result;

    }

    /**

     * Returns a particular value for the named variable, taken from the POST, or GET params.

     *

     * Parameters are fetched from POST first, then GET.

     *

     * @param string $paramname

     * @param bool $require

     * @return mixed

     * @throws moodle_exception If the parameter was not found and the value is required

     */

    private function get_request_parameter(

        string $paramname,

        bool $require,

    ): mixed {

        if (isset($_POST[$paramname])) {

            return $_POST[$paramname];

        } else if (isset($_GET[$paramname])) {

            return $_GET[$paramname];

        } else if ($require) {

            throw new \moodle_exception('missingparam', '', '', $paramname);

        }

        return null;

    }

    /**

     * Strict validation of parameter values, the values are only converted

     * to requested PHP type. Internally it is using clean_param, the values

     * before and after cleaning must be equal - otherwise

     * an invalid_parameter_exception is thrown.

     * Objects and classes are not accepted.

     *

     * @param mixed $param

     * @param bool $allownull are nulls valid value?

     * @param string $debuginfo optional debug information

     * @return mixed the $param value converted to PHP type

     * @throws invalid_parameter_exception if $param is not of given type

     */

    public function validate_param(

        mixed $param,

        bool $allownull = NULL_NOT_ALLOWED,

        string $debuginfo = '',

    ): mixed {

        if (is_null($param)) {

            if ($allownull == NULL_ALLOWED) {

                return null;

            } else {

                throw new invalid_parameter_exception($debuginfo);

            }

        }

        if (is_array($param) || is_object($param)) {

            throw new invalid_parameter_exception($debuginfo);

        }

        $cleaned = $this->clean($param);

        if ($this->canonical() === self::FLOAT) {

            // Do not detect precision loss here.

            if (is_float($param) || is_int($param)) {

                // These always fit.

            } else if (!is_numeric($param) || !preg_match('/^[\+-]?[0-9]*\.?[0-9]*(e[-+]?[0-9]+)?$/i', (string)$param)) {

                throw new invalid_parameter_exception($debuginfo);

            }

        } else if ((string) $param !== (string) $cleaned) {

            // Conversion to string is usually lossless.

            throw new invalid_parameter_exception($debuginfo);

        }

        return $cleaned;

    }

    /**

     * Makes sure array contains only the allowed types, this function does not validate array key names!

     *

     * <code>

     * $options = param::INT->clean_param_array($options);

     * </code>

     *

     * @param array|null $param the variable array we are cleaning

     * @param bool $recursive clean recursive arrays

     * @return array

     * @throws coding_exception

     */

    public function clean_param_array(

        ?array $param,

        bool $recursive = false,

    ) {

        // Convert null to empty array.

        $param = (array) $param;

        foreach ($param as $key => $value) {

            if (is_array($value)) {

                if ($recursive) {

                    $param[$key] = $this->clean_param_array($value, true);

                } else {

                    throw new coding_exception('clean_param_array can not process multidimensional arrays when $recursive is false.');

                }

            } else {

                $param[$key] = $this->clean($value);

            }

        }

        return $param;

    }

    /**

     * Validation for PARAM_RAW.

     *

     * @param mixed $param

     * @return mixed

     */

    protected function clean_param_value_raw(mixed $param): mixed {

        // No cleaning at all.

        return fix_utf8($param);

    }

    /**

     * Validation for PARAM_RAW_TRIMMED.

     *

     * @param mixed $param

     * @return string

     */

    protected function clean_param_value_raw_trimmed(mixed $param): string {

        // No cleaning, but strip leading and trailing whitespace.

        return trim((string) $this->clean_param_value_raw($param));

    }

    /**

     * Validation for PARAM_CLEAN.

     *

     * @param mixed $param

     * @return string

     */

    protected function clean_param_value_clean(mixed $param): string {

        // General HTML cleaning, try to use more specific type if possible this is deprecated!

        // Please use more specific type instead.

        if (is_numeric($param)) {

            return $param;

        }

        $param = fix_utf8($param);

        // Sweep for scripts, etc.

        return clean_text($param);

    }

    /**

     * Validation for PARAM_CLEANHTML.

     */

    protected function clean_param_value_cleanhtml(mixed $param): mixed {

        // Clean html fragment.

        $param = (string)fix_utf8($param);

        // Sweep for scripts, etc.

        $param = clean_text($param, FORMAT_HTML);

        return trim($param);

    }

    /**

     * Validation for PARAM_INT.

     *

     * @param mixed $param

     * @return int

     */

    protected function clean_param_value_int(mixed $param): int {

        // Convert to integer.

        return (int)$param;

    }

    /**

     * Validation for PARAM_FLOAT.

     *

     * @param mixed $param

     * @return float

     */

    protected function clean_param_value_float(mixed $param): float {

        // Convert to float.

        return (float)$param;

    }

    /**

     * Validation for PARAM_LOCALISEDFLOAT.

     *

     * @param mixed $param

     * @return mixed

     */

    protected function clean_param_value_localisedfloat(mixed $param): mixed {

        // Convert to float.

        return unformat_float($param, true);

    }

    /**

     * Validation for PARAM_ALPHA.

     *

     * @param mixed $param

     * @return mixed

     */

    protected function clean_param_value_alpha(mixed $param): mixed {

        // Remove everything not `a-z`.

        return preg_replace('/[^a-zA-Z]/i', '', (string)$param);

    }

    /**

     * Validation for PARAM_ALPHAEXT.

     *

     * @param mixed $param

     * @return mixed

     */

    protected function clean_param_value_alphaext(mixed $param): mixed {

        // Remove everything not `a-zA-Z_-` (originally allowed "/" too).

        return preg_replace('/[^a-zA-Z_-]/i', '', (string)$param);

    }

    /**

     * Validation for PARAM_ALPHANUM.

     *

     * @param mixed $param

     * @return mixed

     */

    protected function clean_param_value_alphanum(mixed $param): mixed {

        // Remove everything not `a-zA-Z0-9`.

        return preg_replace('/[^A-Za-z0-9]/i', '', (string)$param);

    }

    /**

     * Validation for PARAM_ALPHANUMEXT.

     *

     * @param mixed $param

     * @return mixed

     */

    protected function clean_param_value_alphanumext(mixed $param): mixed {

        // Remove everything not `a-zA-Z0-9_-`.

        return preg_replace('/[^A-Za-z0-9_-]/i', '', (string)$param);

    }

    /**

     * Validation for PARAM_SEQUENCE.

     *

     * @param mixed $param

     * @return mixed

     */

    protected function clean_param_value_sequence(mixed $param): mixed {

        // Remove everything not `0-9,`.

        return preg_replace('/[^0-9,]/i', '', (string)$param);

    }

    /**

     * Validation for PARAM_BOOL.

     *

     * @param mixed $param

     * @return mixed

     */

    protected function clean_param_value_bool(mixed $param): mixed {

        // Convert to 1 or 0.

        $tempstr = strtolower((string)$param);

        if ($tempstr === 'on' || $tempstr === 'yes' || $tempstr === 'true') {

            $param = 1;

        } else if ($tempstr === 'off' || $tempstr === 'no' || $tempstr === 'false') {

            $param = 0;

        } else {

            $param = empty($param) ? 0 : 1;

        }

        return $param;

    }

    /**

     * Validation for PARAM_NOTAGS.

     *

     * @param mixed $param

     * @return mixed

     */

    protected function clean_param_value_notags(mixed $param): mixed {

        // Strip all tags.

        $param = fix_utf8($param);

        return strip_tags((string)$param);

    }

    /**

     * Validation for PARAM_TEXT.

     *

     * @param mixed $param

     * @return mixed

     */

    protected function clean_param_value_text(mixed $param): mixed {

        // Leave only tags needed for multilang.

        $param = fix_utf8($param);

        // If the multilang syntax is not correct we strip all tags because it would break xhtml strict which is required

        // for accessibility standards please note this cleaning does not strip unbalanced '>' for BC compatibility reasons.

        do {

            if (strpos((string)$param, '</lang>') !== false) {

                // Old and future mutilang syntax.

                $param = strip_tags($param, '<lang>');

                if (!preg_match_all('/<.*>/suU', $param, $matches)) {

                    break;

                }

                $open = false;

                foreach ($matches[0] as $match) {

                    if ($match === '</lang>') {

                        if ($open) {

                            $open = false;

                            continue;

                        } else {

                            break 2;

                        }

                    }

                    if (!preg_match('/^<lang lang="[a-zA-Z0-9_-]+"\s*>$/u', $match)) {

                        break 2;

                    } else {

                        $open = true;

                    }

                }

                if ($open) {

                    break;

                }

                return $param;

            } else if (strpos((string)$param, '</span>') !== false) {

                // Current problematic multilang syntax.

                $param = strip_tags($param, '<span>');

                if (!preg_match_all('/<.*>/suU', $param, $matches)) {

                    break;

                }

                $open = false;

                foreach ($matches[0] as $match) {

                    if ($match === '</span>') {

                        if ($open) {

                            $open = false;

                            continue;

                        } else {

                            break 2;

                        }

                    }

                    if (!preg_match('/^<span(\s+lang="[a-zA-Z0-9_-]+"|\s+class="multilang"){2}\s*>$/u', $match)) {

                        break 2;

                    } else {

                        $open = true;

                    }

                }

                if ($open) {

                    break;

                }

                return $param;

            }

        } while (false);

        // Easy, just strip all tags, if we ever want to fix orphaned '&' we have to do that in format_string().

        return strip_tags((string)$param);

    }

    /**

     * Validation for PARAM_COMPONENT.

     *

     * @param mixed $param

     * @return string

     */

    protected function clean_param_value_component(mixed $param): string {

        // We do not want any guessing here, either the name is correct or not

        // please note only normalised component names are accepted.

        $param = (string)$param;

        if (!preg_match('/^[a-z][a-z0-9]*(_[a-z][a-z0-9_]*)?[a-z0-9]+$/', $param)) {

            return '';

        }

        if (strpos($param, '__') !== false) {

            return '';

        }

        if (strpos($param, 'mod_') === 0) {

            // Module names must not contain underscores because we need to differentiate them from invalid plugin types.

            if (substr_count($param, '_') != 1) {

                return '';

            }

        }

        return $param;

    }

    /**

     * Validation for PARAM_PLUGIN.

     *

     * @param mixed $param

     * @return string

     */

    protected function clean_param_value_plugin(mixed $param): string {

        return $this->clean_param_value_area($param);

    }

    /**

     * Validation for PARAM_AREA.

     *

     * @param mixed $param

     * @return string

     */

    protected function clean_param_value_area(mixed $param): string {

        // We do not want any guessing here, either the name is correct or not.

        if (!is_valid_plugin_name($param)) {

            return '';

        }

        return $param;

    }

    /**

     * Validation for PARAM_SAFEDIR

     *

     * @param mixed $param

     * @return string

     */

    protected function clean_param_value_safedir(mixed $param): string {

        // Remove everything not a-zA-Z0-9_- .

        return preg_replace('/[^a-zA-Z0-9_-]/i', '', (string)$param);

    }

    /**

     * Validation for PARAM_SAFEPATH.

     *

     * @param mixed $param

     * @return string

     */

    protected function clean_param_value_safepath(mixed $param): string {

        // Remove everything not a-zA-Z0-9/_- .

        return preg_replace('/[^a-zA-Z0-9\/_-]/i', '', (string)$param);

    }

    /**

     * Validation for PARAM_FILE.

     *

     * @param mixed $param

     * @return string

     */

    protected function clean_param_value_file(mixed $param): string {

        // Strip all suspicious characters from filename.

        $param = (string)fix_utf8($param);

        // phpcs:ignore moodle.Strings.ForbiddenStrings.Found

        $param = preg_replace('~[[:cntrl:]]|[&<>"`\|\':\\\\/]~u', '', $param);

        if ($param === '.' || $param === '..') {

            $param = '';

        }

        return $param;

    }

    /**

     * Validation for PARAM_PATH.

     *

     * @param mixed $param

     * @return string

     */

    protected function clean_param_value_path(mixed $param): string {

        // Strip all suspicious characters from file path.

        $param = (string)fix_utf8($param);

        $param = str_replace('\\', '/', $param);