Introduce BuiltInDefinitions for per-schema built-in type isolation

docs/class-reference.md

@@ -178,6 +178,275 @@ static function setDefaultFieldResolver(callable $fn): void
 static function setDefaultArgsMapper(callable $fn): void
 ```
 
+## GraphQL\Type\BuiltInDefinitions
+
+Per-instance container for all built-in GraphQL definitions: scalars, introspection types, meta-fields, and directives.
+
+Each Schema can own its own instance to avoid global state conflicts in multi-schema environments.
+Use {@see BuiltInDefinitions::standard()} for the shared default singleton.
+
+### GraphQL\Type\BuiltInDefinitions Constants
+
+```php
+const SCALAR_TYPE_NAMES = [
+    'Int',
+    'Float',
+    'String',
+    'Boolean',
+    'ID',
+];
+const INTROSPECTION_TYPE_NAMES = [
+    '__Schema',
+    '__Type',
+    '__Directive',
+    '__Field',
+    '__InputValue',
+    '__EnumValue',
+    '__TypeKind',
+    '__DirectiveLocation',
+];
+const BUILT_IN_TYPE_NAMES = [
+    'Int',
+    'Float',
+    'String',
+    'Boolean',
+    'ID',
+    '__Schema',
+    '__Type',
+    '__Directive',
+    '__Field',
+    '__InputValue',
+    '__EnumValue',
+    '__TypeKind',
+    '__DirectiveLocation',
+];
+const BUILT_IN_DIRECTIVE_NAMES = [
+    'include',
+    'skip',
+    'deprecated',
+    'oneOf',
+];
+```
+
+### GraphQL\Type\BuiltInDefinitions Methods
+
+```php
+/**
+ * Returns the shared default singleton instance.
+ *
+ * @api
+ */
+static function standard(): self
+```
+
+```php
+/**
+ * Replaces the standard singleton with one that uses the given scalar overrides.
+ *
+ * @param array<ScalarType> $types
+ *
+ * @api
+ */
+static function overrideScalarTypes(array $types): void
+```
+
+```php
+/**
+ * Checks if the given type is one of the introspection types.
+ *
+ * @api
+ */
+static function isIntrospectionType(GraphQL\Type\Definition\NamedType $type): bool
+```
+
+```php
+/**
+ * Checks if the given directive is one of the built-in directives.
+ *
+ * @api
+ */
+static function isBuiltInDirective(GraphQL\Type\Definition\Directive $directive): bool
+```
+
+```php
+/**
+ * Returns the built-in Int scalar type.
+ *
+ * @api
+ */
+function int(): GraphQL\Type\Definition\ScalarType
+```
+
+```php
+/**
+ * Returns the built-in Float scalar type.
+ *
+ * @api
+ */
+function float(): GraphQL\Type\Definition\ScalarType
+```
+
+```php
+/**
+ * Returns the built-in String scalar type.
+ *
+ * @api
+ */
+function string(): GraphQL\Type\Definition\ScalarType
+```
+
+```php
+/**
+ * Returns the built-in Boolean scalar type.
+ *
+ * @api
+ */
+function boolean(): GraphQL\Type\Definition\ScalarType
+```
+
+```php
+/**
+ * Returns the built-in ID scalar type.
+ *
+ * @api
+ */
+function id(): GraphQL\Type\Definition\ScalarType
+```
+
+```php
+/**
+ * Returns all five standard scalar types keyed by name.
+ *
+ * @return array<string, ScalarType>
+ *
+ * @api
+ */
+function scalarTypes(): array
+```
+
+```php
+/**
+ * Checks if the given name is a built-in type (scalar or introspection).
+ *
+ * @api
+ */
+static function isBuiltInTypeName(string $name): bool
+```
+
+```php
+/**
+ * Checks if the given name is one of the five standard scalar types.
+ *
+ * @api
+ */
+static function isBuiltInScalarName(string $name): bool
+```
+
+```php
+/**
+ * Checks if the given type instance is a built-in type.
+ *
+ * @api
+ */
+static function isBuiltInType(GraphQL\Type\Definition\NamedType $type): bool
+```
+
+```php
+/**
+ * Returns all eight introspection types keyed by name.
+ *
+ * @return array<string, Type&NamedType>
+ *
+ * @api
+ */
+function introspectionTypes(): array
+```
+
+```php
+/**
+ * Returns the __schema meta-field definition.
+ *
+ * @api
+ */
+function schemaMetaFieldDef(): GraphQL\Type\Definition\FieldDefinition
+```
+
+```php
+/**
+ * Returns the __type meta-field definition.
+ *
+ * @api
+ */
+function typeMetaFieldDef(): GraphQL\Type\Definition\FieldDefinition
+```
+
+```php
+/**
+ * Returns the __typename meta-field definition.
+ *
+ * @api
+ */
+function typeNameMetaFieldDef(): GraphQL\Type\Definition\FieldDefinition
+```
+
+```php
+/**
+ * Returns the built-in @include directive.
+ *
+ * @api
+ */
+function includeDirective(): GraphQL\Type\Definition\Directive
+```
+
+```php
+/**
+ * Returns the built-in @skip directive.
+ *
+ * @api
+ */
+function skipDirective(): GraphQL\Type\Definition\Directive
+```
+
+```php
+/**
+ * Returns the built-in @deprecated directive.
+ *
+ * @api
+ */
+function deprecatedDirective(): GraphQL\Type\Definition\Directive
+```
+
+```php
+/**
+ * Returns the built-in @oneOf directive.
+ *
+ * @api
+ */
+function oneOfDirective(): GraphQL\Type\Definition\Directive
+```
+
+```php
+/**
+ * Returns all four built-in directives keyed by name.
+ *
+ * @return array<string, Directive>
+ *
+ * @api
+ */
+function directives(): array
+```
+
+```php
+/**
+ * Returns all built-in types (scalars + introspection types) keyed by name.
+ *
+ * @return array<string, Type&NamedType>
+ *
+ * @api
+ */
+function types(): array
+```
+
 ## GraphQL\Type\Definition\Type
 
 Registry of standard GraphQL types and base class for all other types.
@@ -724,6 +993,7 @@ Usage example:
   types?: Types|null,
   directives?: array<Directive>|null,
   typeLoader?: TypeLoader|null,
+  builtInDefinitions?: BuiltInDefinitions|null,
   assumeValid?: bool|null,
   astNode?: SchemaDefinitionNode|null,
   extensionASTNodes?: array<SchemaExtensionNode>|null,

examples/06-per-schema-scalar-override/example.php

@@ -0,0 +1,84 @@
+<?php declare(strict_types=1);
+
+/**
+ * Per-schema scalar override using BuiltInDefinitions.
+ *
+ * Run: php examples/06-per-schema-scalar-override/example.php
+ *
+ * Register a custom scalar with the same name as a built-in (e.g. "String")
+ * via BuiltInDefinitions, and the schema transparently uses it — even for
+ * fields that reference the global Type::string() singleton.
+ */
+
+require_once __DIR__ . '/../../vendor/autoload.php';
+
+use GraphQL\GraphQL;
+use GraphQL\Type\BuiltInDefinitions;
+use GraphQL\Type\Definition\CustomScalarType;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Schema;
+use GraphQL\Type\SchemaConfig;
+
+$trimmedString = new CustomScalarType([
+    'name' => Type::STRING,
+    'serialize' => static fn ($value): string => trim((string) $value),
+    'parseValue' => static fn ($value): string => trim((string) $value),
+    'parseLiteral' => static fn ($ast): string => trim($ast->value ?? ''),
+]);
+
+$builtInDefs = new BuiltInDefinitions([Type::STRING => $trimmedString]);
+
+$userType = new ObjectType([
+    'name' => 'User',
+    'fields' => [
+        'name' => Type::string(),
+        'email' => Type::string(),
+    ],
+]);
+
+$queryType = new ObjectType([
+    'name' => 'Query',
+    'fields' => [
+        'user' => [
+            'type' => $userType,
+            'resolve' => static fn (): array => [
+                'name' => '  Alice  ',
+                'email' => '  alice@example.com  ',
+            ],
+        ],
+        'greeting' => [
+            'type' => Type::string(),
+            'resolve' => static fn (): string => '  hello world  ',
+        ],
+    ],
+]);
+
+$schema = new Schema(
+    (new SchemaConfig())
+        ->setQuery($queryType)
+        ->setBuiltInDefinitions($builtInDefs)
+);
+
+$schema->assertValid();
+
+$result = GraphQL::executeQuery($schema, '{ greeting user { name email } }');
+
+if ($result->errors !== []) {
+    foreach ($result->errors as $error) {
+        echo "Error: {$error->getMessage()}\n";
+    }
+    exit(1);
+}
+
+$data = $result->toArray()['data'] ?? [];
+echo json_encode($data, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT) . "\n";
+
+// Expected output (whitespace trimmed by the custom scalar):
+// {
+//     "greeting": "hello world",
+//     "user": {
+//         "name": "Alice",
+//         "email": "alice@example.com"
+//     }
+// }

generate-class-reference.php

@@ -10,6 +10,7 @@
 
 const ENTRIES = [
     GraphQL\GraphQL::class => [],
+    GraphQL\Type\BuiltInDefinitions::class => ['constants' => true],
     GraphQL\Type\Definition\Type::class => [],
     GraphQL\Type\Definition\ResolveInfo::class => [],
     GraphQL\Language\DirectiveLocation::class => ['constants' => true],