Полное руководство по функции get_users() в WordPress

Функция get_users() в WordPress используется для получения списка пользователей, которые соответствуют заданным критериям. Она предоставляет гибкие возможности для создания запросов, что позволяет получить нужные данные о пользователях, начиная от их ID и заканчивая метаданными, привязанными к конкретным пользователям.

Функция get_users() является оберткой для класса WP_User_Query, который отвечает за выполнение запросов к базе данных пользователей. Этот класс позволяет легко фильтровать и сортировать результаты на основе различных критериев.

get_users( array $args = array() ): array

Возвращаемое значение

Функция возвращает массив пользователей. Тип данных в массиве зависит от параметра fields:

• Если fields = 'all' или 'all_with_meta', возвращается массив объектов WP_User.
• Если fields — массив полей из таблицы wp_users, возвращается массив объектов stdClass, содержащих только эти поля.
• Если fields — одно поле таблицы wp_users, возвращается массив значений этого поля (например, ID пользователей).

Примечание о безопасности

Особое внимание следует уделять использованию параметра meta_value. Если этот параметр пустой (строка ""), запрос автоматически исключает условие на meta_value и выполняется поиск только по ключу meta_key. Это может привести к неумышленным ошибкам в выборке и потенциальным проблемам с безопасностью, если данные используются в критически важных местах.

Параметры функции get_users()

Параметр $args — это массив настроек, по которым осуществляется запрос к базе данных пользователей. Он включает следующие ключи:

Основные параметры

• role (строка | массив): Роли пользователей, которых нужно получить. Можно указать одну роль строкой или несколько ролей в виде массива. Например, 'role' => 'administrator' или 'role' => array('author', 'subscriber').
• role__in (массив): Массив ролей, по которым будет производиться выборка. Пользователь должен соответствовать хотя бы одной роли из массива.
• role__not_in (массив): Исключает пользователей с указанными ролями.

Фильтры по логинам и никнеймам

• login (строка): Логин пользователя.
• login__in (массив): Массив логинов для фильтрации.
• login__not_in (массив): Исключает пользователей с указанными логинами.
• nicename (строка): Никнейм пользователя.
• nicename__in (массив): Массив никнеймов для включения в выборку.
• nicename__not_in (массив): Массив никнеймов для исключения.

Фильтры по мета-данным

• meta_key (строка): Ключ мета-данного, по которому происходит выборка.
• meta_value (строка): Значение мета-данного для фильтрации.
• meta_compare (строка): Оператор сравнения для мета-данного (=, !=, >, <, и т.д.).

Параметры сортировки и ограничения

• orderby (строка): Параметр для сортировки результата. Например, user_login, user_email, meta_value, и другие.
• order (строка): Направление сортировки (ASC или DESC).
• number (число): Количество пользователей для возврата. Например, number => 10 вернет только 10 пользователей.
• offset (число): Количество пропущенных пользователей в начале выборки.

Еще параметры $args

• blog_id (int)
  Используется в мультисайтовой установке WordPress. Указывает ID блога, пользователей которого нужно получить.
  По умолчанию: текущий блог.
• capability (string|string[]) (WP 5.9)
  Определяет список возможностей (capabilities), которым должны соответствовать пользователи.
  По умолчанию: ''.
• capability__in (string[]) (WP 5.9)
  Массив возможностей, пользователи с хотя бы одной из которых должны быть включены в выборку.
  По умолчанию: array().
• capability__not_in (string[]) (WP 5.9)
  Массив возможностей, пользователи с которыми должны быть исключены из выборки.
  По умолчанию: array().
• who (string) (устарел)
  Если указать authors, будут показаны только авторы. С WP 5.9 этот параметр устарел, используйте capabilities или role.
• include (array)
  Массив ID пользователей, которых нужно включить в результат, независимо от других условий.
• exclude (array)
  Массив ID пользователей, которых нужно исключить из результата.
• meta_query (array)
  Массив условий по метаполям. Аналогичен параметру meta_query в WP_Query.
• paged (int)
  Номер страницы для пагинации.
• search (string)
  Строка для поиска пользователей.
• search_columns (array)
  Массив колонок для поиска по параметру search. Возможные значения: ID, login, nicename, email, url.
• fields (string|array)
  Поля, которые будут возвращены для каждого пользователя.
  Возможные значения: ID, display_name, user_login, user_nicename, user_email, user_url, user_registered, all, all_with_meta.
• has_published_posts (bool|string|array)
  Указывает, что пользователи должны иметь опубликованные записи определенного типа. Можно указать true, чтобы получить всех пользователей с опубликованными записями любого типа.
• date_query (array)
  Массив условий для фильтрации пользователей по дате регистрации.
• count_total (bool)
  Параметр, используемый для пагинации в WP_User_Query.
  По умолчанию: false.
• cache_results (bool) (WP 6.3)
  Нужно ли кэшировать результаты выборки.
  По умолчанию: true.

Пример 1: Получение всех пользователей с определенной ролью

Этот код выводит список всех пользователей с ролью «администратор», выводя их email:

$users = get_users( array(
    'role'   => 'administrator',
    'fields' => ['user_email'],
) );

foreach ( $users as $user ) {
    echo '<p>' . esc_html( $user->user_email ) . '</p>';
}

Пример 2: Использование поиска по имени

Функция поддерживает поиск по различным полям (логин, email, ID). В следующем примере ищем всех пользователей, имя которых начинается на «john»:

$users = get_users( array(
    'search' => 'john*',
    'search_columns' => array( 'user_login', 'user_email' ),
) );

foreach ( $users as $user ) {
    echo '<p>' . esc_html( $user->user_email ) . '</p>';
}

Пример 3: Поиск по мета-данным

Вы можете искать пользователей, у которых установлено определенное мета-значение. Например, чтобы найти пользователей с ключом city и значением New York:

$users = get_users( array(
    'meta_key'     => 'city',
    'meta_value'   => 'New York',
    'meta_compare' => '='
) );

foreach ( $users as $user ) {
    echo '<p>' . esc_html( $user->display_name ) . '</p>';
}

Пример 4: Фильтрация по нескольким ролям

Чтобы получить список пользователей, у которых есть хотя бы одна из ролей «author» или «subscriber»:

$users = get_users( array(
    'role__in' => array( 'author', 'subscriber' ),
) );

foreach ( $users as $user ) {
    echo '<p>' . esc_html( $user->display_name ) . '</p>';
}

Пример 5: Получение конкретных полей

Если вам не нужны все данные о пользователе, вы можете ограничить результат конкретными полями. В следующем примере получаем только логин пользователей:

$users = get_users( array(
    'fields' => array( 'user_login' ),
) );

foreach ( $users as $user ) {
    echo '<p>' . esc_html( $user->user_login ) . '</p>';
}

Пример 6: Получение пользователей с диапазоном значений кастомного поля

Вы также можете использовать операторы для сравнения значений кастомных полей, например, для получения пользователей с определенным диапазоном значений. Допустим, у нас есть поле age, и мы хотим получить пользователей, чей возраст больше 25 лет.

$args = array(
    'meta_key'     => 'age',
    'meta_value'   => '25',
    'meta_compare' => '>'
);

$users = get_users($args);

foreach ($users as $user) {
    echo '<p>' . esc_html($user->display_name) . ', возраст: ' . get_user_meta($user->ID, 'age', true) . '</p>';
}

Здесь мы указываем, что хотим получить всех пользователей, у которых значение метаполя age больше 25. Оператор meta_compare в данном случае — это >, который задает сравнение «больше».

Пример 7: Поиск по нескольким метаполям

Можно объединять несколько условий для поиска по кастомным полям с использованием meta_query. Например, если мы хотим найти всех пользователей старше 30 лет, которые работают в отделе «Продажи»:

$args = array(
    'meta_query' => array(
        'relation' => 'AND',
        array(
            'key'     => 'age',
            'value'   => '30',
            'compare' => '>'
        ),
        array(
            'key'     => 'department',
            'value'   => 'Продажи',
            'compare' => '='
        )
    )
);

$users = get_users($args);

foreach ($users as $user) {
    echo '<p>' . esc_html($user->display_name) . ' — ' . get_user_meta($user->ID, 'department', true) . '</p>';
}

Параметр meta_query позволяет добавлять несколько условий поиска. Мы используем relation со значением AND, чтобы объединить условия: возраст должен быть больше 30, а отдел — «Продажи».

Пример 8: Работа с параметром orderby

Параметр orderby в функции get_users позволяет указать поле, по которому нужно отсортировать результат. Возможные значения включают ID, user_login, user_registered, display_name, post_count и другие. Вы также можете сортировать по кастомным полям, используя meta_value или meta_value_num.

Если мы хотим отсортировать пользователей по имени, можно использовать следующий код:

$args = array(
    'orderby' => 'display_name',
    'order'   => 'ASC' // Сортировка по возрастанию
);

$users = get_users($args);

foreach ($users as $user) {
    echo '<p>' . esc_html($user->display_name) . '</p>';
}

Мы указываем, что сортировать нужно по значению метаполя age, используя orderby => 'meta_value_num', и задаем сортировку по убыванию с помощью order => 'DESC'.

Пример 9: Пагинация и лимитирование результатов

Для ограничения числа получаемых пользователей используется параметр number, а для пагинации — параметры offset и paged.

Если вам нужно вывести только 5 пользователей:

$args = array(
    'number' => 5
);

$users = get_users($args);

foreach ($users as $user) {
    echo '<p>' . esc_html($user->display_name) . '</p>';
}

Заключение

Функция get_users является мощным инструментом для работы с пользователями WordPress. Она предоставляет множество возможностей для фильтрации и сортировки пользователей по стандартным и кастомным полям, а также поддерживает расширенные запросы через meta_query.