User Functions

get_all_users()

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

get_users_dropdown()

/**
 * Print a dropdown list of users.
 *
 * @file App/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_current_user_id()

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

get_current_user()

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

get_user_by()

/**
 * Retrieve user info by a given field from the user's table.
 *
 * @file App/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 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;

get_userdata()

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

get_name()

/**
 * Returns the name of a particular user.
 *
 * Uses `get_name` filter.
 *
 * @file App/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;

get_initials()

/**
 * Shows selected user's initials instead of
 * his/her full name.
 *
 * Uses `get_initials` filter.
 *
 * @file App/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;

get_user_value()

/**
 * Retrieve requested field from user meta table based on user's id.
 *
 * @file App/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;

username_exists()

/**
 * Checks whether the given username exists.
 *
 * Uses `username_exists` filter.
 *
 * @file App/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;

email_exists()

/**
 * Checks whether the given email exists.
 *
 * Uses `email_exists` filter.
 *
 * @file App/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;

get_system_roles()

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

get_user_option()

/**
 * 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 data
 * object as the third parameter.
 *
 * The option will first check for the per site name and then the global name.
 *
 * Uses `get_user_option_$option` filter.
 *
 * @file App/Shared/Helpers/user.php
 * @param string $option User option name.
 * @param string $userId User ID.
 * @return string|false User option value on success or false on failure.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function get_user_option(string $option, string $userId = ''): false|string;

update_user_option()

/**
 * Update user option with global site capability.
 *
 * User options are just like user metadata except that they have support for
 * global site options. If the 'global' parameter is false, which it is by default
 * it will prepend the TriTan CMS table prefix to the option name.
 *
 * Deletes the user option if $newvalue is empty.
 *
 * @file App/Shared/Helpers/user.php
 * @param string $userId User ID.
 * @param string $optionName User option name.
 * @param mixed $newvalue User option value.
 * @param bool $global Optional. Whether option name is global or site specific.
 *                     Default false (site specific).
 * @return bool|int|string User meta ID if the option didn't exist, true on successful update,
 *                         false on failure.
 * @throws CommandPropertyNotFoundException
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 * @throws TypeException
 * @throws UnresolvableQueryHandlerException
 */
function update_user_option(string $userId, string $optionName, mixed $newvalue, bool $global = false): bool|int|string;

delete_user_option()

/**
 * Delete user option with global site capability.
 *
 * User options are just like user metadata except that they have support for
 * global site options. If the 'global' parameter is false, which it is by default
 * it will prepend the TriTan CMS table prefix to the option name.
 *
 * @file App/Shared/Helpers/user.php
 * @param string $userId User ID
 * @param string $optionName User option name.
 * @param bool $global Optional. Whether option name is global or site specific.
 *                     Default false (site specific).
 * @return bool True on success or false on failure.
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 */
function delete_user_option(string $userId, string $optionName, bool $global = false): bool;

cms_insert_user()

/**
 * Insert a user into the database.
 *
 * @file App/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 $admin_layout The user's admin layout option.
 *      @type int $admin_sidebar The user's admin sidebar option
 *      @type string $admin_skin 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;

cms_update_user()

/**
 * Update a user in the database.
 *
 * It is possible to update a user's password by specifying the 'user_pass'
 * value in the $userdata parameter array.
 *
 * See {@see cms_insert_user()} For what fields can be set in $userdata.
 *
 * @file App/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;

cms_delete_user()

/**
 * Deletes a user from the user meta table. To delete user entirely from the system,
 * see `delete_site_user`.
 *
 * @file App/Shared/Helpers/user.php
 * @param string $userId ID of user being deleted.
 * @param string|null $assignId ID of user to whom posts will be assigned.
 *                              Default: NULL.
 * @return bool True on success or false on failure.
 * @throws CommandPropertyNotFoundException
 * @throws ContainerExceptionInterface
 * @throws Exception
 * @throws InvalidArgumentException
 * @throws NotFoundExceptionInterface
 * @throws ReflectionException
 * @throws TypeException
 */
function cms_delete_user(string $userId, ?string $assignId = null): bool;

blacklisted_usernames()

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

reset_password()

/**
 * Resets a user's password.
 *
 * @file App/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;

get_users_by_site_key()

/**
 * Retrieves a list of users by site_key.
 *
 * @file App/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;

get_user_timezone()

/**
 * Returns the logged-in user's timezone.
 *
 * @file App/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;

get_user_date_format()

/**
 * Returns the logged-in user's date format.
 *
 * @file App/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;

get_user_time_format()

/**
 * Returns the logged-in user's time format.
 *
 * @file App/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;

get_user_datetime_format()

/**
 * Returns the logged in user's datetime format.
 *
 * @file App/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;

get_user_datetime()

/**
 * Returns datetime based on user's date format, time format, and timezone.
 *
 * @file App/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;