Create New Item
Item Type
File
Folder
Item Name
Search file in folder and subfolders...
Are you sure want to rename?
File Manager
/
wp-content
/
plugins
/
woocommerce
/
src
/
Abilities
:
ExtensibleAbilities.php
Advanced Search
Upload
New Item
Settings
Back
Back Up
Advanced Editor
Save
<?php /** * Extensible abilities class file. */ declare( strict_types=1 ); namespace Automattic\WooCommerce\Abilities; use Automattic\WooCommerce\Utilities\FeaturesUtil; defined( 'ABSPATH' ) || exit; /** * The entry point for extensions in WooCommerce's abilities. * * An extension registers a resource inside the `woocommerce_extensible_abilities_resources_init` * action. It registers a field on a resource, such as `product`, inside the * `woocommerce_extensible_abilities_init` action, which fires after. An ability that formats an * object of that resource returns the field values under * `extensions.<namespace>.<field>`, and lists the fields in its output schema. * An ActionableAbility writes the same `extensions` input to the fields that * have an `update_callback`, runs the validators of the resource, and saves * the object one time. * An extension also registers a query filter, which the list ability of the * resource accepts under `filters.extensions.<namespace>.<filter>`. * * The API is experimental while the `extensible_abilities` feature exists. * * @since 11.3.0 */ class ExtensibleAbilities { public const FEATURE_ID = 'extensible_abilities'; /** * Fields keyed by resource, then namespace, then field name. * * @var array<string, array<string, array<string, array<string, mixed>>>> */ private static array $fields = array(); /** * Registered resources, keyed by resource name. * * @var array<string, bool> */ private static array $resources = array(); /** * Validators keyed by resource. * * @var array<string, array<int, array<string, mixed>>> */ private static array $validators = array(); /** * Fields already reported for a value that does not match the schema, keyed by resource, namespace and field. * * @var array<string, bool> */ private static array $reported = array(); /** * Whether the store enabled the experimental feature. * * @since 11.3.0 * * @return bool */ public static function is_enabled(): bool { return FeaturesUtil::feature_is_enabled( self::FEATURE_ID ); } /** * Query filters keyed by resource, then namespace, then filter name. * * @var array<string, array<string, array<string, array<string, mixed>>>> */ private static array $filters = array(); /** * Query arguments that a filter callback can return. */ private const QUERY_ARG_KEYS = array( 'meta_query', 'tax_query', 'include_ids', 'exclude_ids' ); /** * Register a resource that abilities format, so extensions can register fields on it. * * Call it inside the `woocommerce_extensible_abilities_resources_init` action. A call after that action is refused. * Core registers `product`, `order` and `order_item` there. An * extension registers a resource that its own abilities format, and then calls `add_fields_to_object()` * and `add_fields_schema()` from those abilities, exactly as Core's abilities do. * Registering the same resource again does nothing. * * @since 11.3.0 * * @param string $resource_name Slug of the resource, such as `ticket`. */ public static function register_resource( string $resource_name ): void { if ( did_action( 'woocommerce_extensible_abilities_resources_init' ) && ! doing_action( 'woocommerce_extensible_abilities_resources_init' ) ) { wc_doing_it_wrong( __METHOD__, __( 'Register a resource inside the woocommerce_extensible_abilities_resources_init action, before the fields are registered.', 'woocommerce' ), '11.3.0' ); return; } if ( '' === $resource_name || sanitize_key( $resource_name ) !== $resource_name || ctype_digit( $resource_name ) ) { wc_doing_it_wrong( __METHOD__, __( 'The resource name must be a slug of lowercase letters, numbers, dashes and underscores, not only numbers.', 'woocommerce' ), '11.3.0' ); return; } self::$resources[ $resource_name ] = true; } /** * Register a field that the abilities of a resource return under `extensions.<namespace>.<field>`. * * Call it inside the `woocommerce_extensible_abilities_init` action. A call after that action is refused. * The resource must be registered with `register_resource()` in the earlier `woocommerce_extensible_abilities_resources_init` action. * * @since 11.3.0 * * @param array $args { * Field arguments. * * @type string $resource Resource that an ability formats, for example `product`, `order` or `order_item`. * @type string $namespace Slug of the extension that owns the field, such as `subscriptions`. * @type string $field Field name inside the namespace, such as `trial_length`. * @type array $schema JSON schema of the value. It needs a `type`. Its `title` is the label clients show. * It cannot set `required`, because a value that fails its schema is * left out. For a field that is always present, allow null and return null. * @type callable $get_callback Receives the object and returns the value. A value that the schema * does not allow is left out, so return null when the object has no * value. A schema that allows null, such as `array( 'integer', 'null' )`, * keeps it. It reads the object it is given, not the database, * because an ability can format an object before it is saved. * @type callable $update_callback Optional. Receives the object and the value, and changes the object * in memory. It returns a WP_Error to reject the value, and then * nothing is saved. A field without it cannot be written. Rules: * 1. It only sets values in memory. It does not save, send email * or make HTTP requests. * 2. It receives the value already cast to the field schema. * 3. A null value deletes the value of the field. * } */ public static function register_field( array $args ): void { if ( did_action( 'woocommerce_extensible_abilities_init' ) && ! doing_action( 'woocommerce_extensible_abilities_init' ) ) { wc_doing_it_wrong( __METHOD__, __( 'Register a field inside the woocommerce_extensible_abilities_init action, before the abilities build their schemas.', 'woocommerce' ), '11.3.0' ); return; } foreach ( array( 'resource', 'namespace', 'field' ) as $key ) { if ( ! is_string( $args[ $key ] ?? null ) || '' === $args[ $key ] || sanitize_key( $args[ $key ] ) !== $args[ $key ] || ctype_digit( $args[ $key ] ) ) { wc_doing_it_wrong( __METHOD__, sprintf( /* translators: %s: argument name. */ __( 'The "%s" argument must be a slug of lowercase letters, numbers, dashes and underscores, not only numbers.', 'woocommerce' ), $key ), '11.3.0' ); return; } } if ( ! isset( self::$resources[ $args['resource'] ] ) && ! did_action( 'woocommerce_extensible_abilities_resources_init' ) ) { wc_doing_it_wrong( __METHOD__, __( 'Register a field inside the woocommerce_extensible_abilities_init action. The resources are not registered yet.', 'woocommerce' ), '11.3.0' ); return; } if ( ! isset( self::$resources[ $args['resource'] ] ) ) { wc_doing_it_wrong( __METHOD__, sprintf( /* translators: %s: resource name. */ __( 'The "%s" resource is not registered. Call ExtensibleAbilities::register_resource() first.', 'woocommerce' ), $args['resource'] ), '11.3.0' ); return; } if ( ! is_array( $args['schema'] ?? null ) || ! isset( $args['schema']['type'] ) ) { wc_doing_it_wrong( __METHOD__, __( 'The "schema" argument must be an array with a "type".', 'woocommerce' ), '11.3.0' ); return; } if ( true === ( $args['schema']['required'] ?? null ) ) { wc_doing_it_wrong( __METHOD__, __( 'The "schema" argument cannot set "required". A value that fails its schema is left out, so allow null for a field that is always present.', 'woocommerce' ), '11.3.0' ); return; } if ( ! is_callable( $args['get_callback'] ?? null ) ) { wc_doing_it_wrong( __METHOD__, __( 'The "get_callback" argument must be callable.', 'woocommerce' ), '11.3.0' ); return; } if ( isset( $args['update_callback'] ) && ! is_callable( $args['update_callback'] ) ) { wc_doing_it_wrong( __METHOD__, __( 'The "update_callback" argument must be callable.', 'woocommerce' ), '11.3.0' ); return; } if ( isset( self::$fields[ $args['resource'] ][ $args['namespace'] ][ $args['field'] ] ) ) { wc_doing_it_wrong( __METHOD__, sprintf( /* translators: 1: extension namespace, 2: field name, 3: resource name. */ __( 'The field "%1$s.%2$s" of "%3$s" is already registered.', 'woocommerce' ), $args['namespace'], $args['field'], $args['resource'] ), '11.3.0' ); return; } self::$fields[ $args['resource'] ][ $args['namespace'] ][ $args['field'] ] = $args; } /** * Register a filter that the list ability of a resource accepts under `filters.extensions.<namespace>.<filter>`. * * Call it inside the `woocommerce_extensible_abilities_init` action. A call after that action is refused. * The resource must be registered with `register_resource()`. * * @since 11.3.0 * * @param array $args { * Filter arguments. * * @type string $resource Resource whose list ability applies the filters. Core's `products-query` and * `orders-query` apply the filters of `product` and `order`. The list ability * of another resource must call `get_query_args()` and `add_query_filters_schema()` itself. * @type string $namespace Slug of the extension that owns the filter, such as `subscriptions`. * @type string $filter Filter name inside the namespace, such as `subscribable`. * @type array $schema JSON schema of the value. Its `description` tells agents how to use the filter. * @type callable $callback Receives the value, sanitized with the schema, and returns query arguments: * a `meta_query`, for products also a `tax_query`, `include_ids` or * `exclude_ids`. Core adds each one to the query with AND. Return a * WP_Error to refuse the value. A `tax_query` is accepted only for * `product`. Any other key, or a `tax_query` for another resource, fails the call. * `include_ids` and `exclude_ids` are lists of object IDs. Use them for * data that is not meta, such as order items or a table of the extension: * query that data and return the IDs that match. Core keeps the IDs that * every `include_ids` filter returns, then drops the IDs that any * `exclude_ids` filter returns. An empty `include_ids` matches nothing. * } */ public static function register_query_filter( array $args ): void { if ( did_action( 'woocommerce_extensible_abilities_init' ) && ! doing_action( 'woocommerce_extensible_abilities_init' ) ) { wc_doing_it_wrong( __METHOD__, __( 'Register a filter inside the woocommerce_extensible_abilities_init action, before the abilities build their schemas.', 'woocommerce' ), '11.3.0' ); return; } foreach ( array( 'resource', 'namespace', 'filter' ) as $key ) { if ( ! is_string( $args[ $key ] ?? null ) || '' === $args[ $key ] || sanitize_key( $args[ $key ] ) !== $args[ $key ] || ctype_digit( $args[ $key ] ) ) { wc_doing_it_wrong( __METHOD__, sprintf( /* translators: %s: argument name. */ __( 'The "%s" argument must be a slug of lowercase letters, numbers, dashes and underscores, not only numbers.', 'woocommerce' ), $key ), '11.3.0' ); return; } } if ( ! isset( self::$resources[ $args['resource'] ] ) ) { wc_doing_it_wrong( __METHOD__, sprintf( /* translators: %s: resource name. */ __( 'The "%s" resource is not registered. Call ExtensibleAbilities::register_resource() first.', 'woocommerce' ), $args['resource'] ), '11.3.0' ); return; } if ( ! is_array( $args['schema'] ?? null ) || ! isset( $args['schema']['type'] ) ) { wc_doing_it_wrong( __METHOD__, __( 'The "schema" argument must be an array with a "type".', 'woocommerce' ), '11.3.0' ); return; } if ( ! is_callable( $args['callback'] ?? null ) ) { wc_doing_it_wrong( __METHOD__, __( 'The "callback" argument must be callable.', 'woocommerce' ), '11.3.0' ); return; } if ( isset( self::$filters[ $args['resource'] ][ $args['namespace'] ][ $args['filter'] ] ) ) { wc_doing_it_wrong( __METHOD__, sprintf( /* translators: 1: extension namespace, 2: filter name, 3: resource name. */ __( 'The filter "%1$s.%2$s" of "%3$s" is already registered.', 'woocommerce' ), $args['namespace'], $args['filter'], $args['resource'] ), '11.3.0' ); return; } self::$filters[ $args['resource'] ][ $args['namespace'] ][ $args['filter'] ] = $args; } /** * Add the `filters.extensions` property to the input schema of a list * ability, when the feature is on and the resource has filters. It does * not allow other filters, because a filter that the query ignores * returns wrong results. * * @since 11.3.0 * * @param array<string, mixed> $schema Input schema. * @param string $resource_name Resource. * @return array<string, mixed> */ public static function add_query_filters_schema( array $schema, string $resource_name ): array { if ( empty( self::$filters[ $resource_name ] ) || ! self::is_enabled() ) { return $schema; } $extensions = array( 'type' => 'object', 'description' => __( 'Filters that extensions add, keyed by extension namespace, then filter.', 'woocommerce' ), 'properties' => array(), 'additionalProperties' => false, ); foreach ( self::$filters[ $resource_name ] as $namespace => $filters ) { $extensions['properties'][ $namespace ] = array( 'type' => 'object', 'properties' => array_map( static function ( array $args ): array { return $args['schema']; }, $filters ), 'additionalProperties' => false, ); } $schema['properties']['filters'] = array( 'type' => 'object', 'properties' => array( 'extensions' => $extensions ), 'additionalProperties' => false, ); return $schema; } /** * Get the query arguments of the filters in the input of a list ability. * Each key holds one clause for each filter, so `array_merge_recursive()` * adds them to WP_Query or wc_get_orders() arguments with AND. `post__in` * holds the IDs that every `include_ids` filter returned, without the IDs * that any `exclude_ids` filter returned, or `0` when none remain, because * an empty `post__in` does not filter. Without `include_ids`, the excluded * IDs go to `post__not_in`, which WP_Query ignores next to `post__in`. * * @since 11.3.0 * * @param string $resource_name Resource. * @param array<string, mixed> $input Ability input. * @return array<string, array>|\WP_Error The error of a value that fails its schema, or of a filter that refused its value or failed. */ public static function get_query_args( string $resource_name, array $input ) { $query_args = array(); $include = null; $exclude = array(); if ( ! self::is_enabled() ) { return $query_args; } foreach ( self::$filters[ $resource_name ] ?? array() as $namespace => $filters ) { foreach ( $filters as $filter => $args ) { if ( ! is_array( $input['filters']['extensions'][ $namespace ] ?? null ) || ! array_key_exists( $filter, $input['filters']['extensions'][ $namespace ] ) ) { continue; } $value = rest_sanitize_value_from_schema( $input['filters']['extensions'][ $namespace ][ $filter ], $args['schema'], $filter ); if ( is_wp_error( $value ) ) { $value->add_data( array( 'status' => 400 ) ); return $value; } try { $clauses = call_user_func( $args['callback'], $value ); } catch ( \Throwable $e ) { wc_get_logger()->error( sprintf( 'Ability filter "%s.%s" of "%s" failed: %s', $namespace, $filter, $resource_name, $e->getMessage() ), array( 'source' => 'extensible-abilities' ) ); $clauses = null; } if ( is_wp_error( $clauses ) ) { return $clauses; } if ( ! is_array( $clauses ) || ! empty( array_diff_key( $clauses, array_flip( self::QUERY_ARG_KEYS ) ) ) || ( 'product' !== $resource_name && isset( $clauses['tax_query'] ) ) || in_array( false, array_map( 'is_array', $clauses ), true ) ) { return new \WP_Error( 'woocommerce_ability_extension_filter_failed', /* translators: %s: filter name, such as subscriptions.subscribable. */ sprintf( __( 'The "%s" filter failed.', 'woocommerce' ), $namespace . '.' . $filter ), array( 'status' => 500 ) ); } if ( isset( $clauses['include_ids'] ) ) { $filter_ids = self::get_filter_ids( $clauses['include_ids'], $namespace . '.' . $filter ); if ( is_wp_error( $filter_ids ) ) { return $filter_ids; } $include = null === $include ? $filter_ids : array_values( array_intersect( $include, $filter_ids ) ); unset( $clauses['include_ids'] ); } if ( isset( $clauses['exclude_ids'] ) ) { $filter_ids = self::get_filter_ids( $clauses['exclude_ids'], $namespace . '.' . $filter ); if ( is_wp_error( $filter_ids ) ) { return $filter_ids; } $exclude = array_merge( $exclude, $filter_ids ); unset( $clauses['exclude_ids'] ); } foreach ( $clauses as $key => $clause ) { if ( empty( $clause ) ) { continue; } $query_args[ $key ][] = $clause; } } } if ( null !== $include ) { $include = array_values( array_diff( $include, $exclude ) ); $query_args['post__in'] = empty( $include ) ? array( 0 ) : $include; } elseif ( ! empty( $exclude ) ) { $query_args['post__not_in'] = array_values( array_unique( $exclude ) ); } return $query_args; } /** * The IDs that a filter returned, as integers. * * @param array $ids IDs from the filter callback. * @param string $filter Filter name, such as `subscriptions.related_to`. * @return int[]|\WP_Error An error when an ID is not a positive integer. */ private static function get_filter_ids( array $ids, string $filter ) { $valid = array_filter( array_map( static fn( $id ) => filter_var( $id, FILTER_VALIDATE_INT, array( 'options' => array( 'min_range' => 1 ) ) ), $ids ) ); if ( count( $valid ) !== count( $ids ) ) { return new \WP_Error( 'woocommerce_ability_extension_filter_failed', /* translators: %s: filter name, such as subscriptions.subscribable. */ sprintf( __( 'The "%s" filter failed.', 'woocommerce' ), $filter ), array( 'status' => 500 ) ); } return array_values( array_unique( $valid ) ); } /** * Register a validator that can refuse a change to an object of a resource. * * Call it inside the `woocommerce_extensible_abilities_init` action. Validators * run only when the `extensible_abilities` feature is on. * * Use a field `update_callback` to refuse a bad value of one field. It runs * only when the input sends that field. Use a validator to refuse a change as * a whole. It runs on every change of the resource, also when the input sends * no extension fields. For example, a validator refuses a product change that * would break a subscription plan. * * Core's product abilities run validators. Core's order abilities keep their * trunk write for now, so validators for `order` run only in the * ActionableAbility classes of extensions. * * @since 11.3.0 * * @param array $args { * Validator arguments. * * @type string $resource Resource that an ActionableAbility changes, such as `product`. * @type string $namespace Slug of the extension that owns the validator, such as `subscriptions`. * @type callable $callback Receives the changed object and the ability, after Core's changes and the * field callbacks, before the one save. It returns a WP_Error to refuse the * change, and then nothing is saved. The error gets the namespace in its * data, and the 400 status when it has no status. Its message can name the * ability or screen to use instead. Rules: * 1. It only reads. It does not change the object, save, send email or * make HTTP requests. * 2. It checks the ability name when the extension's own abilities * change the same resource. * } */ public static function register_validator( array $args ): void { if ( did_action( 'woocommerce_extensible_abilities_init' ) && ! doing_action( 'woocommerce_extensible_abilities_init' ) ) { wc_doing_it_wrong( __METHOD__, __( 'Register a validator inside the woocommerce_extensible_abilities_init action.', 'woocommerce' ), '11.3.0' ); return; } foreach ( array( 'resource', 'namespace' ) as $key ) { if ( ! is_string( $args[ $key ] ?? null ) || '' === $args[ $key ] || sanitize_key( $args[ $key ] ) !== $args[ $key ] ) { wc_doing_it_wrong( __METHOD__, sprintf( /* translators: %s: argument name. */ __( 'The "%s" argument must be a slug of lowercase letters, numbers, dashes and underscores.', 'woocommerce' ), $key ), '11.3.0' ); return; } } if ( ! is_callable( $args['callback'] ?? null ) ) { wc_doing_it_wrong( __METHOD__, __( 'The "callback" argument must be callable.', 'woocommerce' ), '11.3.0' ); return; } if ( ! isset( self::$resources[ $args['resource'] ] ) ) { wc_doing_it_wrong( __METHOD__, sprintf( /* translators: %s: resource name. */ __( 'The "%s" resource is not registered. Call ExtensibleAbilities::register_resource() first.', 'woocommerce' ), $args['resource'] ), '11.3.0' ); return; } self::$validators[ $args['resource'] ][] = $args; } /** * Add the field values of an object to its formatted output, under * `extensions.<namespace>.<field>`. A value is cast to its schema type, so * `'12'` becomes `12` for an integer field. A field that throws or returns a * value that its schema does not allow is left out. A namespace with no * values is left out, and `extensions` is left out when no namespace has * values or the feature is off. * * @since 11.3.0 * * @param array<string, mixed> $output Formatted object. * @param string $resource_name Resource. * @param object $subject Object to read. * @return array<string, mixed> */ public static function add_fields_to_object( array $output, string $resource_name, $subject ): array { if ( empty( self::$fields[ $resource_name ] ) || ! self::is_enabled() ) { return $output; } $extensions = array(); foreach ( self::$fields[ $resource_name ] as $namespace => $fields ) { foreach ( $fields as $field => $args ) { try { $value = call_user_func( $args['get_callback'], $subject ); } catch ( \Throwable $e ) { wc_get_logger()->error( sprintf( 'Ability field "%s.%s" of "%s" failed: %s', $namespace, $field, $resource_name, $e->getMessage() ), array( 'source' => 'extensible-abilities' ) ); continue; } if ( ! self::matches_schema( $args, $value ) ) { continue; } $sanitized = rest_sanitize_value_from_schema( $value, $args['schema'], $field ); if ( ! is_wp_error( $sanitized ) ) { $extensions[ $namespace ][ $field ] = $sanitized; } } } if ( ! empty( $extensions ) ) { $output['extensions'] = $extensions; } return $output; } /** * Add the `extensions` property to an object schema when the feature is on. * It lists each namespace with its fields. Call it after the * `woocommerce_extensible_abilities_init` action, when the ability builds its * schema. The schema stays unchanged when no field is registered for the resource. * * @since 11.3.0 * * @param array<string, mixed> $schema Object schema. * @param string $resource_name Resource. * @return array<string, mixed> */ public static function add_fields_schema( array $schema, string $resource_name ): array { if ( ! self::is_enabled() || empty( self::$fields[ $resource_name ] ) ) { return $schema; } $extensions = array( 'type' => 'object', 'description' => __( 'Values that extensions add, keyed by extension namespace, then field.', 'woocommerce' ), 'additionalProperties' => false, ); foreach ( self::$fields[ $resource_name ] ?? array() as $namespace => $fields ) { $extensions['properties'][ $namespace ] = array( 'type' => 'object', 'properties' => array_map( static function ( array $args ): array { return $args['schema']; }, $fields ), 'additionalProperties' => false, ); } $schema['properties']['extensions'] = $extensions; return $schema; } /** * Fields of a resource, keyed by namespace, then field. * * @internal * * @since 11.3.0 * * @param string $resource_name Resource. * @return array<string, array<string, array<string, mixed>>> */ public static function get_fields( string $resource_name ): array { return self::$fields[ $resource_name ] ?? array(); } /** * Validators of a resource. * * @internal * * @param string $resource_name Resource. * @return array<int, array<string, mixed>> */ public static function get_validators( string $resource_name ): array { return self::$validators[ $resource_name ] ?? array(); } /** * Whether a value matches its field schema. A value other than null that * does not match is logged and reported one time for each field. * * @param array<string, mixed> $args Field arguments. * @param mixed $value Value that the get_callback returned. * @return bool */ private static function matches_schema( array $args, $value ): bool { $valid = rest_validate_value_from_schema( $value, $args['schema'], $args['field'] ); if ( true === $valid ) { return true; } $key = $args['resource'] . '.' . $args['namespace'] . '.' . $args['field']; if ( null === $value || isset( self::$reported[ $key ] ) ) { return false; } self::$reported[ $key ] = true; wc_get_logger()->error( sprintf( 'Ability field "%s.%s" of "%s" was left out because its value does not match its schema: %s', $args['namespace'], $args['field'], $args['resource'], $valid->get_error_message() ), array( 'source' => 'extensible-abilities' ) ); wc_doing_it_wrong( __CLASS__ . '::register_field', sprintf( /* translators: 1: extension namespace, 2: field name, 3: resource name, 4: validation error. */ __( 'Ability field "%1$s.%2$s" of "%3$s" was left out because its value does not match its schema: %4$s', 'woocommerce' ), $args['namespace'], $args['field'], $args['resource'], $valid->get_error_message() ), '11.3.0' ); return false; } }