WooCommerce Code Reference

SchemaHandle
in package

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} returns every row in the schema that carries either #[Metadata]-derived entries or authorization attributes, and {@see} 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.

Tags
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}> }

Table of Contents

$engine_schema  : object
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.
find_metadata()  : array<int, array{type: string, field: ?string, argument: ?string, enumValue: ?string, entries: array, authorization: list}>
Filter-narrows view over {@see self::get_all_metadata()}.
get_all_metadata()  : array<int, array{type: string, field: ?string, argument: ?string, enumValue: ?string, entries: array, authorization: list}>
Return every metadata row in the schema (introspection types excluded).
is_introspection_name()  : bool
Whether a type name belongs to GraphQL's introspection system (and so should be skipped).
make_row()  : array{type: string, field: ?string, argument: ?string, enumValue: ?string, entries: array, authorization: list}
Build a metadata row in the standard shape.
read_element_authorization()  : array<int, array{attribute: string, args: list}>
Read authorization descriptors from a field-/arg-/enum-value-level config.
read_element_metadata()  : array<string, bool|int|float|string|null>
Read field-/arg-/enum-value-level metadata from the original config array.
read_type_authorization()  : array<int, array{attribute: string, args: list}>
Read authorization descriptors attached to a wrapped engine type.
read_type_metadata()  : array<string, bool|int|float|string|null>
Read type-level metadata from a wrapped engine type.

Properties

$engine_schema

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.

private object $engine_schema

Methods

find_metadata()

Filter-narrows view over {@see self::get_all_metadata()}.

public find_metadata([string|null $name = null ][, string|null $type = null ][, string|null $field = null ][, string|null $attribute = null ]) : array<int, array{type: string, field: ?string, argument: ?string, enumValue: ?string, entries: array, authorization: list}>

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.

Parameters
$name : string|null = null

Optional metadata name to match. When set, only rows containing this entry survive and their entries are trimmed to it.

$type : string|null = null

Optional GraphQL type name to match.

$field : string|null = null

Optional GraphQL field name to match.

$attribute : string|null = null

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 values
array<int, array{type: string, field: ?string, argument: ?string, enumValue: ?string, entries: array, authorization: list}> —

get_all_metadata()

Return every metadata row in the schema (introspection types excluded).

public get_all_metadata() : array<int, array{type: string, field: ?string, argument: ?string, enumValue: ?string, entries: array, authorization: list}>

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 values
array<int, array{type: string, field: ?string, argument: ?string, enumValue: ?string, entries: array, authorization: list}> —

is_introspection_name()

Whether a type name belongs to GraphQL's introspection system (and so should be skipped).

private static is_introspection_name(string $name) : bool
Parameters
$name : string

Type name.

Return values
bool —

make_row()

Build a metadata row in the standard shape.

private static make_row(string $type, string|null $field, string|null $argument, string|null $enum_value, array<string, bool|int|float|string|null> $entries, array<int, array{attribute: string, args: list}> $authorization) : array{type: string, field: ?string, argument: ?string, enumValue: ?string, entries: array, authorization: list}
Parameters
$type : string

GraphQL type name.

$field : string|null

Field name when the row describes a field; null otherwise.

$argument : string|null

Argument name when the row describes a field argument; null otherwise.

$enum_value : string|null

Enum value name when the row describes an enum value; null otherwise.

$entries : array<string, bool|int|float|string|null>

Name=>value entries to attach to the row.

$authorization : array<int, array{attribute: string, args: list}>

Authorization descriptors attached to the row, or an empty list.

Return values
array{type: string, field: ?string, argument: ?string, enumValue: ?string, entries: array, authorization: list} —

read_element_authorization()

Read authorization descriptors from a field-/arg-/enum-value-level config.

private static read_element_authorization(object $element) : array<int, array{attribute: string, args: list}>

Mirrors {@see} but pulls the authorization key. Returns an empty list when the element carries no authorization descriptors.

Parameters
$element : object

FieldDefinition | Argument | InputObjectField | EnumValueDefinition.

Return values
array<int, array{attribute: string, args: list}> —

read_element_metadata()

Read field-/arg-/enum-value-level metadata from the original config array.

private static read_element_metadata(object $element) : array<string, bool|int|float|string|null>

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.

Parameters
$element : object

FieldDefinition | Argument | InputObjectField | EnumValueDefinition.

Return values
array<string, bool|int|float|string|null> —

read_type_authorization()

Read authorization descriptors attached to a wrapped engine type.

private static read_type_authorization(Type $type) : array<int, array{attribute: string, args: list}>

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.

Parameters
$type : Type

The GraphQL type to inspect.

Return values
array<int, array{attribute: string, args: list}> —

read_type_metadata()

Read type-level metadata from a wrapped engine type.

private static read_type_metadata(Type $type) : array<string, bool|int|float|string|null>

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.

Parameters
$type : Type

The GraphQL type to inspect.

Return values
array<string, bool|int|float|string|null> —