| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Source view] [Print] [Project Stats]
Abilities API: WP_Abilities_Users class.
| File Size: | 1021 lines (38 kb) |
| Included or required: | 1 time |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
| register() X-Ref |
| Registers all user abilities. Must run on the `wp_abilities_api_init` hook. |
| register_users_query() X-Ref |
| Registers the read-only `core/users-query` ability. Unlike `core/get-user-info`, which only returns the current user's own profile, this ability is generic and reads any user the current user is allowed to see. |
| check_permission( $input = array() X-Ref |
| Permission callback for the `core/users-query` ability. Performs request-level checks only, and never looks users up. Which users are returned is decided by the query arguments in {@see self::execute_users_query()}. return: bool True if the request may proceed, false otherwise. param: mixed $input Optional. The ability input. Default empty array. |
| execute_users_query( $input = array() X-Ref |
| Executes the `core/users-query` ability. return: array<string, mixed>|WP_Error A page of user data, or a WP_Error on failure. param: mixed $input Optional. The ability input. Default empty array. |
| get_input_object( array $input, string $key ) X-Ref |
| Reads an object member of the input, such as `where` or `pagination`. Accepts what schema validation reads as an object: an array, a `stdClass`, or an empty string. Only the REST run controller converts input to the schema types, so callers that bypass it, such as a direct WP_Ability::execute() call, can pass any of them. return: array<mixed>|null The member as an array, an empty array when it is omitted, param: array<mixed> $input The ability input. param: string $key The member name. |
| parse_filter_int( $value, int $min ) X-Ref |
| Parses a raw input value into an integer of at least a minimum, or null when invalid. Accepts the whole numbers that the integer schema accepts: native integers, floats such as the 2.0 that JSON encoders produce, and integer strings such as "2", "2.0", or "+2". Only the REST run controller converts input to the schema types, so other callers, such as the MCP adapter or a direct WP_Ability::execute() call, pass them on unconverted. Anything else, such as a fraction, is rejected rather than coerced: a malformed ID would otherwise resolve to another user. return: int|null The parsed integer, or null when the value is not an integer >= $min. param: mixed $value The raw input value. param: int $min The smallest acceptable value. |
| get_public_post_types() X-Ref |
| Returns publicly viewable post types. Uses {@see is_post_type_viewable()} rather than the `public` registration argument, since `public` alone does not guarantee a post type is viewable on the front end. Deliberately resolved on every call rather than cached: post types can be unregistered or re-registered with different arguments between the ability being registered and the ability being used. return: string[] Publicly viewable post type names. |
| normalize_fields( array $input ) X-Ref |
| Returns the requested field paths, or a lean default set when none are given. An empty or absent `fields` value selects a lean set of common read fields. Otherwise the requested paths are returned. The input schema has already validated them against the paths from {@see self::get_field_paths()} before the ability executes, and {@see self::format_user()} ignores any other path. The `id` field is always included, matching the REST users controller where `id` is present in every context. This also guarantees the result is never empty, so it always serializes as a JSON object. return: string[] List of requested field paths. param: array<mixed> $input The ability input. |
| get_user_properties() X-Ref |
| Returns the user field definitions, keyed by field name in output order. This is the single source of truth for the ability's user fields: the output schema uses the definitions directly, while the input schema `fields` enum lists each field, followed by the path of each of its sub-fields, such as `registered.gmt`. The field set is deliberately unconditional: the registered schemas are a registration-time snapshot, so conditional availability (such as `avatar_urls` honoring the `show_avatars` option) is enforced per call in {@see self::format_user()} instead of here, where the option could change between registration and use. return: array<string, mixed> User field definitions. |
| get_field_paths() X-Ref |
| Returns the field paths the `fields` input accepts, in output order. Each user field is followed by the path of each sub-field its definition declares, such as `registered`, `registered.site` and `registered.gmt`. Requesting a field returns all of its sub-fields, while a sub-field path returns only that sub-field. return: string[] The field paths. |
| is_field_requested( string $path, array $fields ) X-Ref |
| Checks whether a field path is requested. A field such as `registered` is requested when it or one of its paths, such as `registered.gmt`, is requested, and a path such as `registered.gmt` is requested when it or its whole field is. return: bool Whether the field path is requested. param: string $path The field path, such as `registered` or `registered.gmt`. param: string[] $fields The requested field paths. |
| normalize_id_list( $value ) X-Ref |
| Normalizes a mixed value into a list of user IDs. Accepts a list, a single ID, or a comma-separated string, which it parses with wp_parse_list(), as schema validation does. Each item is read with parse_filter_int(), so an item that is not a whole number of at least 1, such as a fraction or a negative number, is dropped rather than truncated or made positive, which would read it as the ID of another user. return: int[] Unique user IDs. param: mixed $value Raw value. |
| normalize_string_list( $value ) X-Ref |
| Normalizes a mixed value into a list of strings. Accepts arrays and CSV strings, which it parses with wp_parse_list(), as schema validation does. Schema validation accepts a CSV string for an array, and only the REST run controller converts input to the schema types, so callers that bypass it, such as a direct WP_Ability::execute() call, can pass one. Empty and duplicate items need no handling here, because validation has already rejected them. return: string[] Normalized strings. param: mixed $value Raw value. |
| normalize_has_published_posts( array $where ) X-Ref |
| Normalizes the `has_published_posts` filter. Accepts the string and integer forms of `true` alongside the native boolean. Schema validation accepts them, and only the REST run controller converts input to the schema types, so callers that bypass it, such as a direct WP_Ability::execute() call, can pass one. return: bool|string[]|null Normalized query value, or null when omitted. param: array<mixed> $where The `where` filters. |
| get_users_query_input_schema() X-Ref |
| Builds the input schema for the `core/users-query` ability. The input has three members: `where` selects the users, `fields` selects the fields returned for each user, and `pagination` selects the page of results. The `where` filters can be combined in any way, and a user must match all of them. return: array<string, mixed> The input JSON Schema. |
| get_users_query_output_schema() X-Ref |
| Builds the output schema for the `core/users-query` ability. Every request returns the same shape: a page of users in `items`, and the totals across all pages in `pagination`. Only `id` is required in a user, because it is always returned. The other fields are optional because the `fields` input lets the caller request any subset, and restricted fields are omitted when unavailable. return: array<string, mixed> The output JSON Schema. |
| format_user( WP_User $user, array $fields ) X-Ref |
| Formats a user into the ability output shape. Fields are selected with {@see self::is_field_requested()}, so `registered` returns both of its sub-fields, while `registered.site` or `registered.gmt` returns only that one. Only the requested fields the current user can see are included, except `id`, which {@see self::normalize_fields()} always requests. return: array<string, mixed> The formatted user data. param: WP_User $user The user object. param: string[] $fields The requested field paths. |
| format_registered_date( WP_User $user, DateTimeZone $timezone ) X-Ref |
| No description |
| prepare_output( array $items, int $total, int $total_pages ) X-Ref |
| Builds the ability output for a page of formatted users. return: array<string, mixed> The ability output. param: array<int, array<string, mixed>> $items The formatted users on the page. param: int $total Total number of users across all pages. param: int $total_pages Total number of pages. |
| invalid_page_number_error() X-Ref |
| Builds the error for a page past the last page of results. A page that does not exist is reported as not found rather than as an empty list, so callers can tell it apart from a request that matches no users. return: WP_Error The invalid page number error. |
| invalid_filter_error( string $param, string $message ) X-Ref |
| Builds the error for a filter that cannot be honored. As in the REST API's `rest_invalid_param` errors, the error data maps the filter's input path to the message under `params`, so callers can tell which filter failed without parsing the translated message. return: WP_Error The invalid filter error. param: string $param The filter's input path, such as `where[ids]`. param: string $message The error message. |
| Generated : Thu Nov 5 08:20:37 2026 | Cross-referenced by PHPXref |