/**
 * Retrieves all users.
 *
 * @file core/Shared/Helpers/user.php
 * @return mixed
 * @throws ReflectionException
 * @throws UnresolvableQueryHandlerException
 */
function get_all_users(): mixed;

/**
 * Print a dropdown list of users.
 *
 * @file core/Shared/Helpers/user.php
 * @param string|null $active If working with active record, it will be the user's id.
 * @return void Dropdown list of users.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_users_dropdown(?string $active = null): void;

/**
 * Get the current user's ID
 *
 * @file core/Shared/Helpers/user.php
 * @return string The current user's ID, or '' if no user is logged in.
 */
function get_current_user_id(): string;

/**
 * Returns object of data for current user.
 *
 * @file core/Shared/Helpers/user.php
 * @return App\Domain\User\Model\User|false
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function cms_get_current_user(): false|User;

/**
 * Retrieve user info by a given field from the user's table.
 *
 * @file core/Shared/Helpers/user.php
 * @param string $field The field to retrieve the user with.
 * @param int|string $value A value for $field (id, login, email, or token).
 * @return App\Domain\User\Model\User|false User array on success, false otherwise.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_user_by(string $field, mixed $value): User|false;

/**
 * Retrieve user info by user_id.
 *
 * @file core/Shared/Helpers/user.php
 * @param mixed $userId User's id.
 * @return App\Domain\User\Model\User|false User array on success, false on failure.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_userdata(string $userId): false|User;

/**
 * Returns the name of a particular user.
 *
 * Uses `user.name` filter.
 *
 * @file core/Shared/Helpers/user.php
 * @param string $id User ID.
 * @param bool $reverse Reverse order (true = Last Name, First Name).
 * @return string User's name.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_name(string $id, bool $reverse = false): string;

/**
 * Shows selected user's initials instead of
 * his/her full name.
 *
 * Uses `user.initials` filter.
 *
 * @file core/Shared/Helpers/user.php
 * @param string $id User ID
 * @param int $initials Number of initials to show.
 * @return string User's initials.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_initials(string $id, int $initials = 2): string;

/**
 * Retrieve requested field from user meta table based on user's id.
 *
 * @file core/Shared/Helpers/user.php
 * @param string $id User ID.
 * @param string $field Data requested of particular user.
 * @return mixed
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_user_value(string $id, string $field): mixed;

/**
 * Checks whether the given username exists.
 *
 * Uses `username.exists` filter.
 *
 * @file core/Shared/Helpers/user.php
 * @param string $username Username to check.
 * @return string|false The user's ID on success or false on failure.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function username_exists(string $username): false|string;

/**
 * Checks whether the given email exists.
 *
 * Uses `email.exists` filter.
 *
 * @file core/Shared/Helpers/user.php
 * @param string $email Email to check.
 * @return string|false The user's ID on success or false on failure.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function email_exists(string $email): false|string;

/**
 * Retrieve a list of system defined user roles.
 *
 * @file core/Shared/Helpers/user.php
 * @param string|null $active User role.
 * @return void
 */
function get_system_roles(?string $active = null): void;

/**
 * Retrieve a list of all users as dropdown options.
 *
 * @file core/Shared/Helpers/user.php
 * @param string|null $active
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 * @throws UnresolvableQueryHandlerException
 */
function get_users_dropdown_list(?string $active = null): void;

/**
 * Retrieve an attribute for specified user.
 *
 * @param string $userId
 * @param string $key
 * @param string|null $siteId
 * @param mixed|null $default
 * @return mixed
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_user_attribute(string $userId, string $key, ?string $siteId = null, mixed $default = null): mixed;

/**
 * @param string $userId
 * @param string $key
 * @param mixed $value
 * @param string|null $siteId
 * @return UserAttributeBag
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function update_user_attribute(string $userId, string $key, mixed $value, ?string $siteId = null): UserAttributeBag;

/**
 * Remove attribute from user_attribute.
 *
 * @param string $siteId
 * @param string $userId
 * @param string $key
 * @return UserAttributeBag
 * @throws ContainerExceptionInterface
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 * @throws TypeException
 */
function delete_user_attribute(string $siteId, string $userId, string $key): UserAttributeBag;

/**
 * @param string $siteId
 * @param string $userId
 * @return void
 * @throws ContainerExceptionInterface
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 * @throws TypeException
 */
function delete_site_user_record(string $siteId, string $userId): void;

/**
 * Retrieve user option that can be either per Site or global.
 *
 * If the user ID is not given, then the current user will be used instead. If
 * the user ID is given, then the user data will be retrieved. The filter for
 * the result, will also pass the original option name and finally the user id
 * as the third parameter.
 *
 * Uses `get.user.option.$option` filter.
 *
 * @file core/Shared/Helpers/user.php
 * @param string $option User option name.
 * @param string $userId User ID.
 * @return bool|string|int|array|null User option value on success or null on failure.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_user_option(string $option, string $userId = ''): bool|string|int|array|null;

/**
 * Insert a user into the database.
 *
 * @file core/Shared/Helpers/user.php
 * @param array|ServerRequestInterface|User $userdata An array, object or User object of user data arguments.
 *
 *  {
 *      @type string $id User's ID. If supplied, the user will be updated.
 *      @type string $pass The plain-text user password.
 *      @type string $login The user's login username.
 *      @type string $fname The user's first name.
 *      @type string $mname The user's middle name.
 *      @type string $lname The user's last name.
 *      @type string $bio The user's biographical description.
 *      @type string $email The user's email address.
 *      @type string $url The user's url.
 *      @type string $status The user's status.
 *      @type int $adminLayout The user's admin layout option.
 *      @type int $adminSidebar The user's admin sidebar option
 *      @type string $adminSkin The user's admin skin option.
 *      @type string $registered Date the user registered. Format is 'Y-m-d H:i:s'.
 *      @type string $modified Date the user's account was updated. Format is 'Y-m-d H:i:s'.
 *  }
 *
 * @return string|Error The newly created user's user_id or Error if user could not be created.
 * @throws CommandPropertyNotFoundException
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 * @throws TypeException
 * @throws UnresolvableQueryHandlerException
 */
function cms_insert_user(array|ServerRequestInterface|User $userdata): string|Error;

/**
 * Update a user in the database.
 *
 * It is possible to update a user's password by specifying the 'pass'
 * value in the $userdata parameter array.
 *
 * See {@see cms_insert_user()} For what fields can be set in $userdata.
 *
 * @file core/Shared/Helpers/user.php
 * @param array|ServerRequestInterface|User $userdata An array of user data or a user object of type stdClass or User.
 * @return string|Error The updated user's id or return an Error if the user could not be updated.
 * @throws CommandPropertyNotFoundException
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 * @throws TypeException
 * @throws UnresolvableQueryHandlerException
 */
function cms_update_user(array|ServerRequestInterface|User $userdata): string|Error;

/**
 * New user email queued when account is created.
 *
 * @file core/Shared/Helpers/user.php
 * @param string $userId User id.
 * @param string $pass Plaintext password.
 * @return bool True on success, false on failure or Exception.
 * @throws EnvironmentIsBrokenException
 * @throws Exception
 */
function queue_new_user_email(string $userId, string $pass): bool;

/**
 * Reset password email queued when reset button is clicked on the user's screen.
 *
 * @file core/Shared/Helpers/user.php
 * @param User $user User object.
 * @return string|bool User id on success, false on failure.
 * @throws EnvironmentIsBrokenException
 */
function queue_reset_user_password(User $user): bool|string;

/**
 * Email sent to user with new generated password.
 *
 * @file core/Shared/Helpers/user.php
 * @param object|array $user User object|array.
 * @param string $password Plaintext password.
 * @return bool True on success, false on failure or Exception.
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws ReflectionException
 * @throws SessionException
 */
function send_reset_password_email(object|array $user, string $password): bool;

/**
 * Email sent to user with changed/updated password.
 *
 * @file core/Shared/Helpers/user.php
 * @param object|array $user User array.
 * @param string $password Plaintext password.
 * @param array $userdata Updated user array.
 * @return bool True on success, false on failure or Exception.
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws ReflectionException
 * @throws SessionException
 */
function send_password_change_email(object|array $user, string $password, array $userdata): bool;

/**
 * Email sent to user with changed/updated email.
 *
 * @file core/Shared/Helpers/user.php
 * @param object|array $user Original user array.
 * @param array $userdata Updated user array.
 * @return bool True on success, false on failure or Exception.
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws ReflectionException
 * @throws SessionException
 */
function send_email_change_email(object|array $user, array $userdata): bool;

/**
 * An extensive list of blacklisted usernames.
 *
 * Uses `blacklisted_usernames` filter.
 *
 * @file core/Shared/Helpers/user.php
 * @return array Array of blacklisted usernames.
 * @throws Exception
 * @throws ReflectionException
 */
function blacklisted_usernames(): array;

/**
 * Resets a user's password.
 *
 * @file core/Shared/Helpers/user.php
 * @param string $userId ID of user whose password is to be reset.
 * @return bool|string User id on success or Exception on failure.
 * @throws CommandCouldNotBeHandledException
 * @throws EnvironmentIsBrokenException
 * @throws Exception
 * @throws ReflectionException
 * @throws SessionException
 * @throws TypeException
 * @throws UnresolvableCommandHandlerException
 */
function reset_password(string $userId): bool|string;

/**
 * Retrieves a list of users by site_key.
 *
 * @file core/Shared/Helpers/user.php
 * @param string $siteKey Site key.
 * @return array|false|string User array on success.
 * @throws ContainerExceptionInterface
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_users_by_site_key(string $siteKey = ''): array|string|bool;

/**
 * Returns the logged-in user's timezone.
 *
 * @file core/Shared/Helpers/user.php
 * @return mixed Logged in user's timezone or system's timezone if false.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_user_timezone(): mixed;

/**
 * Returns the logged-in user's date format.
 *
 * @file core/Shared/Helpers/user.php
 * @return mixed Logged in user's date format or system's date format if false.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_user_date_format(): mixed;

/**
 * Returns the logged-in user's time format.
 *
 * @file core/Shared/Helpers/user.php
 * @return mixed Logged in user's time format or system's time format if false.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_user_time_format(): mixed;

/**
 * Returns the logged in user's datetime format.
 *
 * @file core/Shared/Helpers/user.php
 * @return string Logged in user's datetime format or system's datetime format.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_user_datetime_format(): string;

/**
 * Returns datetime based on user's date format, time format, and timezone.
 *
 * @file core/Shared/Helpers/user.php
 * @param string $string Datetime string.
 * @param string $format Format of the datetime string.
 * @return string Datetime string based on logged in user's date format,
 *                time format and timezone. Otherwise, it will use system settings.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_user_datetime(string $string, string $format = 'Y-m-d H:i:s'): string;