Support per-schema scalar overrides

.ai/AGENTS.md

@@ -20,6 +20,12 @@ make bench          # Run PHPBench benchmarks
 make docs           # Generate class reference docs
 ```
 
+## Public API
+
+Elements marked with `@api` in PHPDoc are part of the stable public API.
+
+Constants listed in the [class-reference docs](https://webonyx.github.io/graphql-php/class-reference/) (generated via `generate-class-reference.php` with `'constants' => true`) are also stable public API, even without an `@api` tag.
+
 ## Code and Testing Expectations
 
 - Preserve backward compatibility for public APIs unless explicitly requested.

CHANGELOG.md

@@ -9,6 +9,22 @@ You can find and compare releases at the [GitHub release page](https://github.co
 
 ## Unreleased
 
+## v15.31.0
+
+### Added
+
+- Support per-schema scalar overrides via `types` config or `typeLoader`, without global side effects https://github.com/webonyx/graphql-php/pull/1869
+- Add `Type::builtInScalars()` and `Type::BUILT_IN_SCALAR_NAMES` aligning with GraphQL spec terminology https://github.com/webonyx/graphql-php/pull/1869
+- Add `Directive::builtInDirectives()` and `Directive::isBuiltInDirective()` aligning with GraphQL spec terminology https://github.com/webonyx/graphql-php/pull/1869
+
+### Deprecated
+
+- Deprecate `Type::overrideStandardTypes()` in favor of per-schema scalar overrides https://github.com/webonyx/graphql-php/pull/1869
+- Deprecate `Type::getStandardTypes()` in favor of `Type::builtInScalars()` https://github.com/webonyx/graphql-php/pull/1869
+- Deprecate `Type::STANDARD_TYPE_NAMES` in favor of `Type::BUILT_IN_SCALAR_NAMES` https://github.com/webonyx/graphql-php/pull/1869
+- Deprecate `Directive::getInternalDirectives()` in favor of `Directive::builtInDirectives()` https://github.com/webonyx/graphql-php/pull/1869
+- Deprecate `Directive::isSpecifiedDirective()` in favor of `Directive::isBuiltInDirective()` https://github.com/webonyx/graphql-php/pull/1869
+
 ## v15.30.2
 
 ### Fixed

README.md

@@ -31,8 +31,9 @@ with a specific README file per example.
 This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
 
 Elements that belong to the public API of this package are marked with the `@api` PHPDoc tag.
-Those elements are thus guaranteed to be stable within major versions. All other elements are
-not part of this backwards compatibility guarantee and may change between minor or patch versions.
+Constants included in the [class-reference docs](https://webonyx.github.io/graphql-php/class-reference) are also part of the public API.
+Those elements are thus guaranteed to be stable within major versions.
+All other elements are not part of this backwards compatibility guarantee and may change between minor or patch versions.
 
 The most recent version is actively developed on [`master`](https://github.com/webonyx/graphql-php/tree/master).
 Older versions are generally no longer supported, although exceptions may be made for [sponsors](#sponsors).

benchmarks/BuildSchemaBench.php

@@ -11,9 +11,11 @@
  *
  * @Warmup(2)
  *
+ * @Sleep(500000)
+ *
  * @Revs(10)
  *
- * @Iterations(2)
+ * @Iterations(5)
  */
 class BuildSchemaBench
 {

benchmarks/HugeSchemaBench.php

@@ -16,9 +16,11 @@
  *
  * @Warmup(2)
  *
+ * @Sleep(500000)
+ *
  * @Revs(10)
  *
- * @Iterations(3)
+ * @Iterations(5)
  */
 class HugeSchemaBench
 {

benchmarks/ScalarOverrideBench.php

@@ -0,0 +1,109 @@
+<?php declare(strict_types=1);
+
+namespace GraphQL\Benchmarks;
+
+use GraphQL\GraphQL;
+use GraphQL\Type\Definition\CustomScalarType;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Schema;
+
+/**
+ * @BeforeMethods({"setUp"})
+ *
+ * @OutputTimeUnit("milliseconds", precision=3)
+ *
+ * @Warmup(2)
+ *
+ * @Revs(100)
+ *
+ * @Iterations(5)
+ */
+class ScalarOverrideBench
+{
+    private Schema $schemaBaseline;
+
+    private Schema $schemaTypeLoader;
+
+    private Schema $schemaTypes;
+
+    public function setUp(): void
+    {
+        $uppercaseString = new CustomScalarType([
+            'name' => Type::STRING,
+            'serialize' => static fn ($value): string => strtoupper((string) $value),
+        ]);
+
+        $queryTypeBaseline = new ObjectType([
+            'name' => 'Query',
+            'fields' => [
+                'greeting' => [
+                    'type' => Type::string(),
+                    'resolve' => static fn (): string => 'hello world',
+                ],
+            ],
+        ]);
+        $this->schemaBaseline = new Schema([
+            'query' => $queryTypeBaseline,
+        ]);
+
+        $queryTypeLoader = new ObjectType([
+            'name' => 'Query',
+            'fields' => [
+                'greeting' => [
+                    'type' => Type::string(),
+                    'resolve' => static fn (): string => 'hello world',
+                ],
+            ],
+        ]);
+        $typesForLoader = ['Query' => $queryTypeLoader, 'String' => $uppercaseString];
+        $this->schemaTypeLoader = new Schema([
+            'query' => $queryTypeLoader,
+            'typeLoader' => static fn (string $name): ?Type => $typesForLoader[$name] ?? null,
+        ]);
+
+        $queryTypeTypes = new ObjectType([
+            'name' => 'Query',
+            'fields' => [
+                'greeting' => [
+                    'type' => Type::string(),
+                    'resolve' => static fn (): string => 'hello world',
+                ],
+            ],
+        ]);
+        $this->schemaTypes = new Schema([
+            'query' => $queryTypeTypes,
+            'types' => [$uppercaseString],
+        ]);
+    }
+
+    public function benchGetTypeWithoutOverride(): void
+    {
+        $this->schemaBaseline->getType('String');
+    }
+
+    public function benchGetTypeWithTypeLoaderOverride(): void
+    {
+        $this->schemaTypeLoader->getType('String');
+    }
+
+    public function benchGetTypeWithTypesOverride(): void
+    {
+        $this->schemaTypes->getType('String');
+    }
+
+    public function benchExecuteWithoutOverride(): void
+    {
+        GraphQL::executeQuery($this->schemaBaseline, '{ greeting }');
+    }
+
+    public function benchExecuteWithTypeLoaderOverride(): void
+    {
+        GraphQL::executeQuery($this->schemaTypeLoader, '{ greeting }');
+    }
+
+    public function benchExecuteWithTypesOverride(): void
+    {
+        GraphQL::executeQuery($this->schemaTypes, '{ greeting }');
+    }
+}

docs/class-reference.md

@@ -108,6 +108,8 @@ static function promiseToExecute(
 /**
  * Returns directives defined in GraphQL spec.
  *
+ * @deprecated use {@see Directive::builtInDirectives()}
+ *
  * @throws InvariantViolation
  *
  * @return array<string, Directive>
@@ -119,7 +121,9 @@ static function getStandardDirectives(): array
 
 ```php
 /**
- * Returns types defined in GraphQL spec.
+ * Returns built-in scalar types defined in GraphQL spec.
+ *
+ * @deprecated use {@see Type::builtInScalars()}
  *
  * @throws InvariantViolation
  *
@@ -136,6 +140,8 @@ static function getStandardTypes(): array
  *
  * Standard types not listed here remain untouched.
  *
+ * @deprecated prefer per-schema scalar overrides via {@see \GraphQL\Type\SchemaConfig::$types} or {@see \GraphQL\Type\SchemaConfig::$typeLoader}
+ *
  * @param array<string, ScalarType> $types
  *
  * @api
@@ -180,13 +186,52 @@ static function setDefaultArgsMapper(callable $fn): void
 
 ## GraphQL\Type\Definition\Type
 
-Registry of standard GraphQL types and base class for all other types.
+Registry of built-in GraphQL types and base class for all other types.
+
+### GraphQL\Type\Definition\Type Constants
+
+```php
+const INT = 'Int';
+const FLOAT = 'Float';
+const STRING = 'String';
+const BOOLEAN = 'Boolean';
+const ID = 'ID';
+const BUILT_IN_SCALAR_NAMES = [
+    'Int',
+    'Float',
+    'String',
+    'Boolean',
+    'ID',
+];
+const STANDARD_TYPE_NAMES = [
+    'Int',
+    'Float',
+    'String',
+    'Boolean',
+    'ID',
+];
+const BUILT_IN_TYPE_NAMES = [
+    'Int',
+    'Float',
+    'String',
+    'Boolean',
+    'ID',
+    '__Schema',
+    '__Type',
+    '__Directive',
+    '__Field',
+    '__InputValue',
+    '__EnumValue',
+    '__TypeKind',
+    '__DirectiveLocation',
+];
+```
 
 ### GraphQL\Type\Definition\Type Methods
 
 ```php
 /**
- * Returns the registered or default standard Int type.
+ * Returns the built-in Int scalar type.
  *
  * @api
  */
@@ -195,7 +240,7 @@ static function int(): GraphQL\Type\Definition\ScalarType
 
 ```php
 /**
- * Returns the registered or default standard Float type.
+ * Returns the built-in Float scalar type.
  *
  * @api
  */
@@ -204,7 +249,7 @@ static function float(): GraphQL\Type\Definition\ScalarType
 
 ```php
 /**
- * Returns the registered or default standard String type.
+ * Returns the built-in String scalar type.
  *
  * @api
  */
@@ -213,7 +258,7 @@ static function string(): GraphQL\Type\Definition\ScalarType
 
 ```php
 /**
- * Returns the registered or default standard Boolean type.
+ * Returns the built-in Boolean scalar type.
  *
  * @api
  */
@@ -222,7 +267,7 @@ static function boolean(): GraphQL\Type\Definition\ScalarType
 
 ```php
 /**
- * Returns the registered or default standard ID type.
+ * Returns the built-in ID scalar type.
  *
  * @api
  */
@@ -255,6 +300,28 @@ static function listOf($type): GraphQL\Type\Definition\ListOfType
 static function nonNull($type): GraphQL\Type\Definition\NonNull
 ```
 
+```php
+/**
+ * Returns all built-in types: built-in scalars and introspection types.
+ *
+ * @api
+ *
+ * @return array<string, Type&NamedType>
+ */
+static function builtInTypes(): array
+```
+
+```php
+/**
+ * Returns all built-in scalar types.
+ *
+ * @api
+ *
+ * @return array<string, ScalarType>
+ */
+static function builtInScalars(): array
+```
+
 ```php
 /**
  * Determines if the given type is an input type.