SchemaHandle.php
<?php
declare(strict_types=1);
namespace Automattic\WooCommerce\Api\Utils;
use Automattic\WooCommerce\Vendor\GraphQL\Type\Definition\EnumType;
use Automattic\WooCommerce\Vendor\GraphQL\Type\Definition\HasFieldsType;
use Automattic\WooCommerce\Vendor\GraphQL\Type\Definition\InputObjectType;
use Automattic\WooCommerce\Vendor\GraphQL\Type\Definition\Type;
/**
* Opaque handle to a dual-API GraphQL schema, exposing the runtime inspection
* operations the dual-API surface supports.
*
* The handle wraps the live engine schema but does not expose it. Clients
* therefore depend only on the methods this class declares — never on the
* underlying engine type — which keeps a future engine swap as a non-public
* API change.
*
* Construction is reserved for the dual-API infrastructure. Obtain a handle
* via your dual-API `GraphQLController`'s `get_schema()` method:
*
* $schema = wc_get_container()
* ->get( \Automattic\WooCommerce\Internal\Api\Autogenerated\GraphQLController::class )
* ->get_schema();
*
* WooCommerce plugins implementing their own dual API reach a handle through
* their own concrete autogenerated controller the same way.
*
* The current public surface is the discovery channel: {@see self::get_all_metadata()}
* returns every row in the schema that carries either `#[Metadata]`-derived
* entries or authorization attributes, and {@see self::find_metadata()} applies
* filter-narrows semantics (`name`, `type`, `field`, `attribute`) over the same
* set. Authorization descriptors are exposed as a parallel `authorization`
* slice on each row, alongside the existing `entries`.
*
* @phpstan-type MetadataRow array{
* type: string,
* field: ?string,
* argument: ?string,
* enumValue: ?string,
* entries: array<string, bool|int|float|string|null>,
* authorization: list<array{attribute: string, args: list<mixed>}>
* }
*/
final class SchemaHandle {
/**
* The wrapped engine schema. Typed as `object` (rather than the engine's
* `Schema` class) so the class signature carries no engine-specific
* symbol; the inspection methods cast to engine APIs internally.
*
* @var object
*/
private object $engine_schema;
/**
* Wrap an engine schema in a handle.
*
* @internal Reserved for dual-API infrastructure (the controller's `get_schema()` accessor and similarly placed code). Plugins obtain a handle through their own controller, not by instantiating directly.
*
* @param object $engine_schema Engine-specific schema instance the handle wraps.
*/
public function __construct( object $engine_schema ) {
$this->engine_schema = $engine_schema;
}
/**
* Return every metadata row in the schema (introspection types excluded).
*
* Each row describes one *target* (a type, a field, an argument, or an
* enum value) and carries the name=>value entries declared on it. The
* same row shape is used for every target kind; the three nullable
* position fields (`field`, `argument`, `enumValue`) discriminate.
*
* @return list<array{type: string, field: ?string, argument: ?string, enumValue: ?string, entries: array<string, bool|int|float|string|null>, authorization: list<array{attribute: string, args: list<mixed>}>}>
*/
public function get_all_metadata(): array {
$rows = array();
$schema = $this->engine_schema;
foreach ( $schema->getTypeMap() as $type_name => $type ) {
if ( self::is_introspection_name( $type_name ) ) {
continue;
}
$type_metadata = self::read_type_metadata( $type );
$type_authorization = self::read_type_authorization( $type );
if ( ! empty( $type_metadata ) || ! empty( $type_authorization ) ) {
$rows[] = self::make_row( $type_name, null, null, null, $type_metadata, $type_authorization );
}
if ( $type instanceof HasFieldsType ) {
foreach ( $type->getFields() as $field_name => $field ) {
$field_metadata = self::read_element_metadata( $field );
$field_authorization = self::read_element_authorization( $field );
if ( ! empty( $field_metadata ) || ! empty( $field_authorization ) ) {
$rows[] = self::make_row( $type_name, $field_name, null, null, $field_metadata, $field_authorization );
}
foreach ( $field->args as $arg ) {
$arg_metadata = self::read_element_metadata( $arg );
if ( ! empty( $arg_metadata ) ) {
$rows[] = self::make_row( $type_name, $field_name, $arg->name, null, $arg_metadata, array() );
}
}
}
continue;
}
if ( $type instanceof InputObjectType ) {
foreach ( $type->getFields() as $field_name => $field ) {
$field_metadata = self::read_element_metadata( $field );
$field_authorization = self::read_element_authorization( $field );
if ( ! empty( $field_metadata ) || ! empty( $field_authorization ) ) {
$rows[] = self::make_row( $type_name, $field_name, null, null, $field_metadata, $field_authorization );
}
}
continue;
}
if ( $type instanceof EnumType ) {
foreach ( $type->getValues() as $value ) {
$value_metadata = self::read_element_metadata( $value );
if ( ! empty( $value_metadata ) ) {
$rows[] = self::make_row( $type_name, null, null, $value->name, $value_metadata, array() );
}
}
}
}
return $rows;
}
/**
* Filter-narrows view over {@see self::get_all_metadata()}.
*
* Each filter argument independently restricts the result set; supplying
* multiple composes as AND. When `$name` is supplied, the surviving rows
* have their `entries` trimmed to the single matching entry; so a caller
* asking "which elements are marked X" gets focused rows back, not the
* full multi-entry shape.
*
* @param ?string $name Optional metadata name to match. When set, only rows containing this entry survive and their `entries` are trimmed to it.
* @param ?string $type Optional GraphQL type name to match.
* @param ?string $field Optional GraphQL field name to match.
* @param ?string $attribute Optional authorization-attribute short name to match. When set, only rows carrying this attribute survive and their `authorization` is trimmed to the matching descriptors.
*
* @return list<array{type: string, field: ?string, argument: ?string, enumValue: ?string, entries: array<string, bool|int|float|string|null>, authorization: list<array{attribute: string, args: list<mixed>}>}>
*/
public function find_metadata( ?string $name = null, ?string $type = null, ?string $field = null, ?string $attribute = null ): array {
$rows = $this->get_all_metadata();
$result = array();
foreach ( $rows as $row ) {
if ( null !== $type && $row['type'] !== $type ) {
continue;
}
if ( null !== $field && $row['field'] !== $field ) {
continue;
}
if ( null !== $name ) {
if ( ! array_key_exists( $name, $row['entries'] ) ) {
continue;
}
$row['entries'] = array( $name => $row['entries'][ $name ] );
}
if ( null !== $attribute ) {
$matching = array_values(
array_filter(
$row['authorization'],
static fn( array $descriptor ): bool => ( $descriptor['attribute'] ?? null ) === $attribute,
)
);
if ( empty( $matching ) ) {
continue;
}
$row['authorization'] = $matching;
}
$result[] = $row;
}
return $result;
}
/**
* Read type-level metadata from a wrapped engine type.
*
* The wrapper subclasses in `Internal/Api/Schema/` expose `get_metadata()`;
* non-wrapper types (e.g. the built-in scalars, the introspection types we
* already filtered out) don't carry metadata and contribute an empty array.
*
* @param Type $type The GraphQL type to inspect.
* @return array<string, bool|int|float|string|null>
*/
private static function read_type_metadata( Type $type ): array {
if ( method_exists( $type, 'get_metadata' ) ) {
$metadata = $type->get_metadata();
return is_array( $metadata ) ? $metadata : array();
}
return array();
}
/**
* Read field-/arg-/enum-value-level metadata from the original config array.
*
* FieldDefinition, Argument, InputObjectField and EnumValueDefinition all
* preserve their construction config in a public `$config` property, so
* the `metadata` key emitted by ApiBuilder is reachable here without any
* wrapper-side plumbing.
*
* @param object $element FieldDefinition | Argument | InputObjectField | EnumValueDefinition.
* @return array<string, bool|int|float|string|null>
*/
private static function read_element_metadata( object $element ): array {
if ( ! property_exists( $element, 'config' ) ) {
return array();
}
$metadata = $element->config['metadata'] ?? array();
return is_array( $metadata ) ? $metadata : array();
}
/**
* Read authorization descriptors attached to a wrapped engine type.
*
* The wrapper subclasses preserve the original config in `$type->config`;
* authorization descriptors emitted by ApiBuilder live under the
* `authorization` key as a list of `{attribute, args}` records.
*
* @param Type $type The GraphQL type to inspect.
* @return list<array{attribute: string, args: list<mixed>}>
*/
private static function read_type_authorization( Type $type ): array {
if ( ! property_exists( $type, 'config' ) ) {
return array();
}
$authorization = $type->config['authorization'] ?? array();
return is_array( $authorization ) ? $authorization : array();
}
/**
* Read authorization descriptors from a field-/arg-/enum-value-level config.
*
* Mirrors {@see self::read_element_metadata()} but pulls the
* `authorization` key. Returns an empty list when the element carries
* no authorization descriptors.
*
* @param object $element FieldDefinition | Argument | InputObjectField | EnumValueDefinition.
* @return list<array{attribute: string, args: list<mixed>}>
*/
private static function read_element_authorization( object $element ): array {
if ( ! property_exists( $element, 'config' ) ) {
return array();
}
$authorization = $element->config['authorization'] ?? array();
return is_array( $authorization ) ? $authorization : array();
}
/**
* Build a metadata row in the standard shape.
*
* @param string $type GraphQL type name.
* @param ?string $field Field name when the row describes a field; null otherwise.
* @param ?string $argument Argument name when the row describes a field argument; null otherwise.
* @param ?string $enum_value Enum value name when the row describes an enum value; null otherwise.
* @param array<string, bool|int|float|string|null> $entries Name=>value entries to attach to the row.
* @param list<array{attribute: string, args: list<mixed>}> $authorization Authorization descriptors attached to the row, or an empty list.
* @return array{type: string, field: ?string, argument: ?string, enumValue: ?string, entries: array<string, bool|int|float|string|null>, authorization: list<array{attribute: string, args: list<mixed>}>}
*/
private static function make_row( string $type, ?string $field, ?string $argument, ?string $enum_value, array $entries, array $authorization ): array {
return array(
'type' => $type,
'field' => $field,
'argument' => $argument,
'enumValue' => $enum_value,
'entries' => $entries,
'authorization' => $authorization,
);
}
/**
* Whether a type name belongs to GraphQL's introspection system (and so should be skipped).
*
* @param string $name Type name.
*/
private static function is_introspection_name( string $name ): bool {
return str_starts_with( $name, '__' );
}
}
