✏️ Editing: 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, '__' );
	}
}

Gifari Industries - BD Cyber Security Team