<?php

use bff\extend\HooksGroup;

class UsersHooks extends HooksGroup
{
    /**
     * Фильтр альтернативной реализации валидации полей пользователя
     * @see \Users::cleanUserData()
     * @param string $dataKey ключ поля
     * @param callable $callback {
     *   @param mixed $value данные требующие обработки
     *   @param array $data:
     *      array 'data' @ref данные пользователя
     *      array 'extraSettings' доп. настройки валидации
     *   return: mixed обработанные данные
     * }
     * @param int|null $priority приоритет вызова
     */
    public static function userValidateData(string $dataKey, callable $callback, ?int $priority = null)
    {
        return static::add('users.clean.data.' . $dataKey, $callback, $priority);
    }

    /**
     * Хук расширения HTML формы добавления/редактирования пользователя (админ. панель)
     * @param callable $callback {
     *   @param array $data:
     *      boolean 'edit' форма редактирования
     *      array 'data' @ref данные пользователя
     * }
     * @param int|null $priority приоритет вызова
     */
    public static function adminUserForm(callable $callback, ?int $priority = null)
    {
        return static::add('users.admin.user.form', $callback, $priority);
    }

    /**
     * Хук сабмита HTML формы добавления/редактирования пользователя (админ. панель)
     * @param callable $callback {
     *   @param array $data:
     *      integer 'id' ID пользователя или 0 (при добавлении)
     *      array 'data' @ref данные пользователя
     *      array 'groups' @ref группы пользователя
     * }
     * @param int|null $priority приоритет вызова
     */
    public static function adminUserFormSubmit(callable $callback, ?int $priority = null)
    {
        return static::add('users.admin.user.submit', $callback, $priority);
    }

    /**
     * Хук для дополнительных табов формы добавления/редактирования пользователя (админ. панель)
     * @param callable $callback {
     *   @param array $data:
     *      boolean 'edit' форма редактирования
     *      array 'data' @ref данные пользователя
     *   return: array список табов
     * }
     * @param int|null $priority приоритет вызова
     */
    public static function adminUserFormTabsExtra(callable $callback, ?int $priority = null)
    {
        return static::add('users.admin.user.form.tabs.extra', $callback, $priority);
    }

    /**
     * Хук расширения содержимого табов формы добавления/редактирования пользователя (админ. панель)
     * @param callable $callback {
     *   @param array $data:
     *      boolean 'edit' редактирования пользователя
     *      array 'data' @ref данные формы
     * }
     * @param int|null $priority приоритет вызова
     */
    public static function adminUserFormTabsContent(callable $callback, ?int $priority = null)
    {
        return static::add('users.admin.user.form.tabs.content', $callback, $priority);
    }

    /**
     * Хук расширения содержимого блока с информацией о статусе пользователя (админ. панель)
     * @param callable $callback {
     *   @param array $data:
     *      array 'data' @ref данные пользователя
     *      boolean 'popup' блок отображается во всплывающем окне
     *      string 'blockID' ID блока
     * }
     * @param int|null $priority приоритет вызова
     */
    public static function adminUserFormStatus(callable $callback, ?int $priority = null)
    {
        return static::add('users.admin.user.form.status', $callback, $priority);
    }

    /**
     * Хук расширения HTML краткой формы профиля пользователя (админ. панель)
     * @param callable $callback {
     *   @param array $data:
     *      array 'data' @ref данные пользователя
     * }
     * @param int|null $priority приоритет вызова
     */
    public static function adminUserProfileForm(callable $callback, ?int $priority = null)
    {
        return static::add('users.admin.profile.form', $callback, $priority);
    }

    /**
     * Хук сабмита HTML краткой формы профиля пользователя (админ. панель)
     * @see \Users::profile
     * @param callable $callback {
     *   @param array $data:
     *      integer 'id' ID пользователя
     *      array 'data' @ref данные пользователя для сохранения
     * }
     * @param int|null $priority приоритет вызова
     */
    public static function adminUserProfileFormSubmit(callable $callback, ?int $priority = null)
    {
        return static::add('users.admin.profile.submit', $callback, $priority);
    }

    /**
     * Хук расширения всплывающего окна с краткой информацией о пользователе (админ. панель)
     * @param callable $callback {
     *   @param array $data:
     *      array 'data' @ref данные пользователя
     * }
     * @param int|null $priority приоритет вызова
     */
    public static function adminUserInfo(callable $callback, ?int $priority = null)
    {
        return static::add('users.admin.user.info', $callback, $priority);
    }

    /**
     * Хук некоторых этапов авторизации пользователя в админ. панель
     * @param integer $step шаг:
     *   1 - перед проверкой логина/пароля
     *   2 - после проверкой логина/пароля, блокировки и группы доступа в админ. панель
     * @param callable $callback {
     *   @param array $data:
     *      string 'login' логин пользователя (шаг №1)
     *      string 'password' пароль пользователя (шаг №1)
     *      integer 'id' ID пользователя (шаг №2)
     *      array 'data' @ref данные пользователя (шаг №2)
     * }
     * @param int|null $priority приоритет вызова
     */
    public static function adminUserLogin(int $step, callable $callback, ?int $priority = null)
    {
        return static::add('users.admin.login.step' . $step, $callback, $priority);
    }

    /**
     * Хук расширения HTML формы авторизации пользователя (админ. панель)
     * @param callable $callback
     * @param int|null $priority приоритет вызова
     */
    public static function adminUserLoginForm(callable $callback, ?int $priority = null)
    {
        return static::add('users.admin.login.form', $callback, $priority);
    }

    /**
     * Фильтр реализующий возможность подключения сторонних SMS провайдеров
     * @see \modules\users\Sms::send
     * @param callable $callback {
     *   @param string $provider ключ SMS провайдера
     *   @param string $phoneNumber номер телефона
     *   @param string $message текст сообщения
     *   return: string|bool ключ SMS провайдера или true
     * }
     * @param int|null $priority приоритет вызова
     */
    public static function smsSend(callable $callback, ?int $priority = null)
    {
        return static::add('users.sms.send', $callback, $priority);
    }

    /**
     * Фильтр списка настроек подписки на email-уведомления (фронтенд)
     * @see \Users::getEnotifyTypes()
     * @param callable $callback {
     *   @param array $list список настроек в формате:
     *      array(
     *          'уникальный числовой ключ с побитовым шагом' => array(
     *              'title' => 'название',
     *              'priority' => 'приоритет определяющий порядок, например: 1',
     *          ),
     *          ...
     *      )
     *   @param integer $settings текущие настройки
     *   return: array список настроек
     * }
     * @param int|null $priority приоритет вызова
     */
    public static function userEnotifyTypes(callable $callback, ?int $priority = null)
    {
        return static::add('users.enotify.types', $callback, $priority);
    }
}