<?php

/**
 * @noinspection PhpInconsistentReturnPointsInspection
 * @noinspection PhpReturnDocTypeMismatchInspection
 * @noinspection PhpDocSignatureInspection
 */

namespace bff\base;

/**
 * Класс валидации входящих данных (GET, POST, COOKIE ...)
 * @copyright Tamaranga
 */
class Input
{
    public const INPUT_GET = 'g';
    public const INPUT_POST = 'p';
    public const INPUT_COOKIE = 'c';

    /**
     * Получаем значение GET и приводим к безопасной форме
     * @param string|null $name название, null - все GET значения
     * @param int|array $filter фильтр
     * @param array $validation параметры валидации
     * @return mixed
     */
    public function get($name = null, $filter = TYPE_NOCLEAN, array $validation = [])
    {
    }

    /**
     * Приводим данные GET к безопасной форме
     * @param array $variables [название => фильтр/валидация, ...]
     * @param mixed $return @ref результат обработки
     * @param mixed $prefix префикс (подставляемый к названию)
     * @return array
     */
    public function getm(array $variables, &$return = [], $prefix = false)
    {
    }

    /**
     * Приводим данные GET к безопасной форме, основываясь на доступных языках
     * @param array $variables [название => фильтр/валидация, ...]
     * @param mixed $return @ref результат обработки
     * @param mixed $prefix префикс (подставляемый к названию)
     * @return array
     */
    public function getm_lang(array $variables, &$return = [], $prefix = false)
    {
    }

    /**
     * Получаем значение GET/POST и приводим к безопасной форме
     * @param string|null $name название, null - все GET/POST значения
     * @param int|array $filter фильтр
     * @param array $validation параметры валидации
     * @return mixed
     */
    public function getpost($name = null, $filter = TYPE_NOCLEAN, array $validation = [])
    {
    }

    /**
     * Приводим данные GET/POST к безопасной форме
     * @param array $variables [название => фильтр/валидация, ...]
     * @param mixed $return @ref результат обработки
     * @param mixed $prefix префикс (подставляемый к названию)
     * @return array
     */
    public function getpostm(array $variables, &$return = [], $prefix = false)
    {
    }

    /**
     * Получаем значение POST и приводим к безопасной форме
     * @param string|null $name название, null - все POST значения
     * @param int|array $filter фильтр
     * @param array $validation параметры валидации
     * @return mixed
     */
    public function post($name = null, $filter = TYPE_NOCLEAN, array $validation = [])
    {
    }

    /**
     * Приводим данные POST к безопасной форме
     * @param array $variables [название => фильтр/валидация, ...]
     * @param mixed $return @ref результат обработки
     * @param mixed $prefix префикс (подставляемый к названию)
     * @return array
     */
    public function postm(array $variables, &$return = [], $prefix = false)
    {
    }

    /**
     * Приводим данные POST к безопасной форме, основываясь на доступных языках
     * @param array $variables [название => фильтр/валидация, ...]
     * @param mixed $return @ref результат обработки
     * @param mixed $prefix префикс (подставляемый к названию)
     * @return array
     */
    public function postm_lang(array $variables, &$return = [], $prefix = false)
    {
    }

    /**
     * Получаем значение POST/GET и приводим к безопасной форме
     * @param string|null $name название, null - все POST/GET значения
     * @param int|array $filter фильтр
     * @param array $validation параметры валидации
     * @return mixed
     */
    public function postget($name = null, $filter = TYPE_NOCLEAN, array $validation = [])
    {
    }

    /**
     * Приводим данные POST/GET к безопасной форме
     * @param array $variables [название => фильтр/валидация, ...]
     * @param mixed $return @ref результат обработки
     * @param mixed $prefix префикс (подставляемый к названию)
     * @return array
     */
    public function postgetm(array $variables, &$return = [], $prefix = false)
    {
    }

    /**
     * Приводим данные POST/GET к безопасной форме, основываясь на доступных языках
     * @param array $variables [название => фильтр/валидация, ...]
     * @param mixed $return @ref результат обработки
     * @param mixed $prefix префикс (подставляемый к названию)
     * @return array
     */
    public function postgetm_lang(array $variables, &$return = [], $prefix = false)
    {
    }

    /**
     * Получаем значение COOKIE и приводим к безопасной форме
     * @param string|null $name название, null - все COOKIE значения
     * @param int|array $filter фильтр
     * @param array $validation параметры валидации
     * @return mixed
     */
    public function cookie($name = null, $filter = TYPE_STR, array $validation = [])
    {
    }

    /**
     * Проверяем наличие переменной по названию
     * @param string $name название
     * @param string|array|null $source название источника: 'g','p','c' (null - any)
     * @return bool
     */
    public function has($name, $source = null)
    {
    }

    /**
     * Проверяем наличие GET переменной по названию
     * @param string $name название
     * @return bool
     */
    public function hasGet($name)
    {
    }

    /**
     * Проверяем наличие POST переменной по названию
     * @param string $name название
     * @return bool
     */
    public function hasPost($name)
    {
    }

    /**
     * Устанавливаем новое значение
     * @param string $name
     * @param mixed $value
     * @param mixed $source self::INPUT_ (true - GET + POST, null - текущий)
     * @return void
     */
    public function set($name, $value, $source = null)
    {
    }

    /**
     * Устанавливаем новое GET значение
     * @param string $name
     * @param mixed $value
     * @param bool $replace false - set only if no value in input data
     * @return void
     */
    public function setGet($name, $value, $replace = true)
    {
    }

    /**
     * Устанавливаем новое POST значение
     * @param string $name
     * @param mixed $value
     * @param bool $replace false - set only if no value in input data
     * @return void
     */
    public function setPost($name, $value, $replace = true)
    {
    }

    /**
     * Приводим одну переменную к безопасной форме и возвращаем её
     * @param mixed $var @ref значение
     * @param int|mixed $type тип
     * @param bool $exists требуется ли очистка переменной либо ее инициализация
     * @param array $extra параметры валидации
     * @return mixed переменная в безопасной форме
     */
    public function clean(&$var, $type = TYPE_NOCLEAN, $exists = true, array $extra = [])
    {
    }

    /**
     * Приводим данные в массиве к безопасной форме
     * @param array $data @ref массив данных, которые необходимо обработать
     * @param array $variables [название => фильтр/валидация, ...]
     * @param array $return @ref результат обработки
     * @return array
     */
    public function clean_array(&$data, $variables, &$return = [])
    {
    }

    /**
     * Проверяем email адрес на корректность
     * @param string $email @ref email адрес
     * @param bool $format форматируем email
     * @return bool
     */
    public function isEmail(&$email, bool $format = false): bool
    {
    }

    /**
     * Проверка, является ли email адрес временным
     * @hooks: input.email.temporary
     * @param string $email email-адрес
     * @return bool true - временный, false - нормальный
     */
    public function isEmailTemporary(string $email): bool
    {
    }

    /**
     * Форматирование email адреса
     * @hooks: input.email.format
     * @param string $email email адрес
     * @param bool $trim
     * @return string
     */
    public function formatEmail(string $email, bool $trim = true): string
    {
    }

    /**
     * Проверка корректности номера телефона
     * @hooks: input.phone.validate.opts, input.phone.validate
     * @param string $phoneNumber @ref номер телефона
     * @param array $opts доп. параметры ['regexp' => '/[^0-9]/', 'min' => 8, 'max' => 30]
     * @return bool корректный номер или нет
     */
    public function isPhoneNumber(&$phoneNumber, array $opts = []): bool
    {
    }

    /**
     * Проверка корректности номера версии
     * Корректные варианты: 1.0.0, 1.0.0
     * @param string $version номер для проверки
     * @param int|array $limit лимит кол-ва подверсий: 3 => X.X.X, 4 => X.X.X.X
     * @return bool корректный номер версии или нет
     */
    public function isVersionNumber($version, $limit = [3,4])
    {
    }

    /**
     * Очистка текста (без HTML тегов)
     * @hooks: input.text.validate
     * @param string $text
     * @param bool $maxLength максимально допустимое кол-во символов или 0|false - без ограничений
     * @param bool|array $activateLinks
     * @return string
     */
    public function cleanTextPlain($text, $maxLength = false, $activateLinks = true): string
    {
    }

    /**
     * Подготовка строки для поиска (UTF-8, сжимание пробелов)
     * @hooks: input.searchstring.validate
     * @param string $string строка поиска
     * @param int $maxLength максимально допустимая длина строки
     * @return string
     */
    public function cleanSearchString(string $string, int $maxLength = 64): string
    {
    }

    /**
     * Fill input data from Request object
     * @param \bff\http\Request|null $request
     * @return void
     */
    public function fill($request = null)
    {
    }
}