SchemaHandle.php
291 lines
| 1 | <?php |
| 2 | |
| 3 | declare(strict_types=1); |
| 4 | |
| 5 | namespace Automattic\WooCommerce\Api\Utils; |
| 6 | |
| 7 | use Automattic\WooCommerce\Vendor\GraphQL\Type\Definition\EnumType; |
| 8 | use Automattic\WooCommerce\Vendor\GraphQL\Type\Definition\HasFieldsType; |
| 9 | use Automattic\WooCommerce\Vendor\GraphQL\Type\Definition\InputObjectType; |
| 10 | use Automattic\WooCommerce\Vendor\GraphQL\Type\Definition\Type; |
| 11 | |
| 12 | /** |
| 13 | * Opaque handle to a dual-API GraphQL schema, exposing the runtime inspection |
| 14 | * operations the dual-API surface supports. |
| 15 | * |
| 16 | * The handle wraps the live engine schema but does not expose it. Clients |
| 17 | * therefore depend only on the methods this class declares — never on the |
| 18 | * underlying engine type — which keeps a future engine swap as a non-public |
| 19 | * API change. |
| 20 | * |
| 21 | * Construction is reserved for the dual-API infrastructure. Obtain a handle |
| 22 | * via your dual-API `GraphQLController`'s `get_schema()` method: |
| 23 | * |
| 24 | * $schema = wc_get_container() |
| 25 | * ->get( \Automattic\WooCommerce\Internal\Api\Autogenerated\GraphQLController::class ) |
| 26 | * ->get_schema(); |
| 27 | * |
| 28 | * WooCommerce plugins implementing their own dual API reach a handle through |
| 29 | * their own concrete autogenerated controller the same way. |
| 30 | * |
| 31 | * The current public surface is the discovery channel: {@see self::get_all_metadata()} |
| 32 | * returns every row in the schema that carries either `#[Metadata]`-derived |
| 33 | * entries or authorization attributes, and {@see self::find_metadata()} applies |
| 34 | * filter-narrows semantics (`name`, `type`, `field`, `attribute`) over the same |
| 35 | * set. Authorization descriptors are exposed as a parallel `authorization` |
| 36 | * slice on each row, alongside the existing `entries`. |
| 37 | * |
| 38 | * @phpstan-type MetadataRow array{ |
| 39 | * type: string, |
| 40 | * field: ?string, |
| 41 | * argument: ?string, |
| 42 | * enumValue: ?string, |
| 43 | * entries: array<string, bool|int|float|string|null>, |
| 44 | * authorization: list<array{attribute: string, args: list<mixed>}> |
| 45 | * } |
| 46 | */ |
| 47 | final class SchemaHandle { |
| 48 | |
| 49 | /** |
| 50 | * The wrapped engine schema. Typed as `object` (rather than the engine's |
| 51 | * `Schema` class) so the class signature carries no engine-specific |
| 52 | * symbol; the inspection methods cast to engine APIs internally. |
| 53 | * |
| 54 | * @var object |
| 55 | */ |
| 56 | private object $engine_schema; |
| 57 | |
| 58 | /** |
| 59 | * Wrap an engine schema in a handle. |
| 60 | * |
| 61 | * @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. |
| 62 | * |
| 63 | * @param object $engine_schema Engine-specific schema instance the handle wraps. |
| 64 | */ |
| 65 | public function __construct( object $engine_schema ) { |
| 66 | $this->engine_schema = $engine_schema; |
| 67 | } |
| 68 | |
| 69 | /** |
| 70 | * Return every metadata row in the schema (introspection types excluded). |
| 71 | * |
| 72 | * Each row describes one *target* (a type, a field, an argument, or an |
| 73 | * enum value) and carries the name=>value entries declared on it. The |
| 74 | * same row shape is used for every target kind; the three nullable |
| 75 | * position fields (`field`, `argument`, `enumValue`) discriminate. |
| 76 | * |
| 77 | * @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>}>}> |
| 78 | */ |
| 79 | public function get_all_metadata(): array { |
| 80 | $rows = array(); |
| 81 | $schema = $this->engine_schema; |
| 82 | |
| 83 | foreach ( $schema->getTypeMap() as $type_name => $type ) { |
| 84 | if ( self::is_introspection_name( $type_name ) ) { |
| 85 | continue; |
| 86 | } |
| 87 | |
| 88 | $type_metadata = self::read_type_metadata( $type ); |
| 89 | $type_authorization = self::read_type_authorization( $type ); |
| 90 | if ( ! empty( $type_metadata ) || ! empty( $type_authorization ) ) { |
| 91 | $rows[] = self::make_row( $type_name, null, null, null, $type_metadata, $type_authorization ); |
| 92 | } |
| 93 | |
| 94 | if ( $type instanceof HasFieldsType ) { |
| 95 | foreach ( $type->getFields() as $field_name => $field ) { |
| 96 | $field_metadata = self::read_element_metadata( $field ); |
| 97 | $field_authorization = self::read_element_authorization( $field ); |
| 98 | if ( ! empty( $field_metadata ) || ! empty( $field_authorization ) ) { |
| 99 | $rows[] = self::make_row( $type_name, $field_name, null, null, $field_metadata, $field_authorization ); |
| 100 | } |
| 101 | |
| 102 | foreach ( $field->args as $arg ) { |
| 103 | $arg_metadata = self::read_element_metadata( $arg ); |
| 104 | if ( ! empty( $arg_metadata ) ) { |
| 105 | $rows[] = self::make_row( $type_name, $field_name, $arg->name, null, $arg_metadata, array() ); |
| 106 | } |
| 107 | } |
| 108 | } |
| 109 | continue; |
| 110 | } |
| 111 | |
| 112 | if ( $type instanceof InputObjectType ) { |
| 113 | foreach ( $type->getFields() as $field_name => $field ) { |
| 114 | $field_metadata = self::read_element_metadata( $field ); |
| 115 | $field_authorization = self::read_element_authorization( $field ); |
| 116 | if ( ! empty( $field_metadata ) || ! empty( $field_authorization ) ) { |
| 117 | $rows[] = self::make_row( $type_name, $field_name, null, null, $field_metadata, $field_authorization ); |
| 118 | } |
| 119 | } |
| 120 | continue; |
| 121 | } |
| 122 | |
| 123 | if ( $type instanceof EnumType ) { |
| 124 | foreach ( $type->getValues() as $value ) { |
| 125 | $value_metadata = self::read_element_metadata( $value ); |
| 126 | if ( ! empty( $value_metadata ) ) { |
| 127 | $rows[] = self::make_row( $type_name, null, null, $value->name, $value_metadata, array() ); |
| 128 | } |
| 129 | } |
| 130 | } |
| 131 | } |
| 132 | |
| 133 | return $rows; |
| 134 | } |
| 135 | |
| 136 | /** |
| 137 | * Filter-narrows view over {@see self::get_all_metadata()}. |
| 138 | * |
| 139 | * Each filter argument independently restricts the result set; supplying |
| 140 | * multiple composes as AND. When `$name` is supplied, the surviving rows |
| 141 | * have their `entries` trimmed to the single matching entry; so a caller |
| 142 | * asking "which elements are marked X" gets focused rows back, not the |
| 143 | * full multi-entry shape. |
| 144 | * |
| 145 | * @param ?string $name Optional metadata name to match. When set, only rows containing this entry survive and their `entries` are trimmed to it. |
| 146 | * @param ?string $type Optional GraphQL type name to match. |
| 147 | * @param ?string $field Optional GraphQL field name to match. |
| 148 | * @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. |
| 149 | * |
| 150 | * @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>}>}> |
| 151 | */ |
| 152 | public function find_metadata( ?string $name = null, ?string $type = null, ?string $field = null, ?string $attribute = null ): array { |
| 153 | $rows = $this->get_all_metadata(); |
| 154 | |
| 155 | $result = array(); |
| 156 | foreach ( $rows as $row ) { |
| 157 | if ( null !== $type && $row['type'] !== $type ) { |
| 158 | continue; |
| 159 | } |
| 160 | if ( null !== $field && $row['field'] !== $field ) { |
| 161 | continue; |
| 162 | } |
| 163 | if ( null !== $name ) { |
| 164 | if ( ! array_key_exists( $name, $row['entries'] ) ) { |
| 165 | continue; |
| 166 | } |
| 167 | $row['entries'] = array( $name => $row['entries'][ $name ] ); |
| 168 | } |
| 169 | if ( null !== $attribute ) { |
| 170 | $matching = array_values( |
| 171 | array_filter( |
| 172 | $row['authorization'], |
| 173 | static fn( array $descriptor ): bool => ( $descriptor['attribute'] ?? null ) === $attribute, |
| 174 | ) |
| 175 | ); |
| 176 | if ( empty( $matching ) ) { |
| 177 | continue; |
| 178 | } |
| 179 | $row['authorization'] = $matching; |
| 180 | } |
| 181 | $result[] = $row; |
| 182 | } |
| 183 | |
| 184 | return $result; |
| 185 | } |
| 186 | |
| 187 | /** |
| 188 | * Read type-level metadata from a wrapped engine type. |
| 189 | * |
| 190 | * The wrapper subclasses in `Internal/Api/Schema/` expose `get_metadata()`; |
| 191 | * non-wrapper types (e.g. the built-in scalars, the introspection types we |
| 192 | * already filtered out) don't carry metadata and contribute an empty array. |
| 193 | * |
| 194 | * @param Type $type The GraphQL type to inspect. |
| 195 | * @return array<string, bool|int|float|string|null> |
| 196 | */ |
| 197 | private static function read_type_metadata( Type $type ): array { |
| 198 | if ( method_exists( $type, 'get_metadata' ) ) { |
| 199 | $metadata = $type->get_metadata(); |
| 200 | return is_array( $metadata ) ? $metadata : array(); |
| 201 | } |
| 202 | return array(); |
| 203 | } |
| 204 | |
| 205 | /** |
| 206 | * Read field-/arg-/enum-value-level metadata from the original config array. |
| 207 | * |
| 208 | * FieldDefinition, Argument, InputObjectField and EnumValueDefinition all |
| 209 | * preserve their construction config in a public `$config` property, so |
| 210 | * the `metadata` key emitted by ApiBuilder is reachable here without any |
| 211 | * wrapper-side plumbing. |
| 212 | * |
| 213 | * @param object $element FieldDefinition | Argument | InputObjectField | EnumValueDefinition. |
| 214 | * @return array<string, bool|int|float|string|null> |
| 215 | */ |
| 216 | private static function read_element_metadata( object $element ): array { |
| 217 | if ( ! property_exists( $element, 'config' ) ) { |
| 218 | return array(); |
| 219 | } |
| 220 | $metadata = $element->config['metadata'] ?? array(); |
| 221 | return is_array( $metadata ) ? $metadata : array(); |
| 222 | } |
| 223 | |
| 224 | /** |
| 225 | * Read authorization descriptors attached to a wrapped engine type. |
| 226 | * |
| 227 | * The wrapper subclasses preserve the original config in `$type->config`; |
| 228 | * authorization descriptors emitted by ApiBuilder live under the |
| 229 | * `authorization` key as a list of `{attribute, args}` records. |
| 230 | * |
| 231 | * @param Type $type The GraphQL type to inspect. |
| 232 | * @return list<array{attribute: string, args: list<mixed>}> |
| 233 | */ |
| 234 | private static function read_type_authorization( Type $type ): array { |
| 235 | if ( ! property_exists( $type, 'config' ) ) { |
| 236 | return array(); |
| 237 | } |
| 238 | $authorization = $type->config['authorization'] ?? array(); |
| 239 | return is_array( $authorization ) ? $authorization : array(); |
| 240 | } |
| 241 | |
| 242 | /** |
| 243 | * Read authorization descriptors from a field-/arg-/enum-value-level config. |
| 244 | * |
| 245 | * Mirrors {@see self::read_element_metadata()} but pulls the |
| 246 | * `authorization` key. Returns an empty list when the element carries |
| 247 | * no authorization descriptors. |
| 248 | * |
| 249 | * @param object $element FieldDefinition | Argument | InputObjectField | EnumValueDefinition. |
| 250 | * @return list<array{attribute: string, args: list<mixed>}> |
| 251 | */ |
| 252 | private static function read_element_authorization( object $element ): array { |
| 253 | if ( ! property_exists( $element, 'config' ) ) { |
| 254 | return array(); |
| 255 | } |
| 256 | $authorization = $element->config['authorization'] ?? array(); |
| 257 | return is_array( $authorization ) ? $authorization : array(); |
| 258 | } |
| 259 | |
| 260 | /** |
| 261 | * Build a metadata row in the standard shape. |
| 262 | * |
| 263 | * @param string $type GraphQL type name. |
| 264 | * @param ?string $field Field name when the row describes a field; null otherwise. |
| 265 | * @param ?string $argument Argument name when the row describes a field argument; null otherwise. |
| 266 | * @param ?string $enum_value Enum value name when the row describes an enum value; null otherwise. |
| 267 | * @param array<string, bool|int|float|string|null> $entries Name=>value entries to attach to the row. |
| 268 | * @param list<array{attribute: string, args: list<mixed>}> $authorization Authorization descriptors attached to the row, or an empty list. |
| 269 | * @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>}>} |
| 270 | */ |
| 271 | private static function make_row( string $type, ?string $field, ?string $argument, ?string $enum_value, array $entries, array $authorization ): array { |
| 272 | return array( |
| 273 | 'type' => $type, |
| 274 | 'field' => $field, |
| 275 | 'argument' => $argument, |
| 276 | 'enumValue' => $enum_value, |
| 277 | 'entries' => $entries, |
| 278 | 'authorization' => $authorization, |
| 279 | ); |
| 280 | } |
| 281 | |
| 282 | /** |
| 283 | * Whether a type name belongs to GraphQL's introspection system (and so should be skipped). |
| 284 | * |
| 285 | * @param string $name Type name. |
| 286 | */ |
| 287 | private static function is_introspection_name( string $name ): bool { |
| 288 | return str_starts_with( $name, '__' ); |
| 289 | } |
| 290 | } |
| 291 |