Allow setting per-schema scalar overrides explicitly via SchemaConfig

[tmoitie]

Fixes the silent loss of lazy type loading introduced with per-schema scalar overrides (#1869, v15.31.0), by allowing overrides to be set explicitly on SchemaConfig so the discovery scan of types can be skipped. Related to #1874.

The problem

The executor and validator resolve built-in scalars (Boolean, String, Int, Float, ID) via Schema::getType() on essentially every operation — including a bare { __typename }.

Since #1869 (and after #1884 moved scalar overrides exclusively to types), the first such lookup goes:

1. getType() calls loadType(), which returns null for built-in scalar names when a typeLoader is set (the TODO referencing After Upgrading from v15.30.2 => v15.31.0 Error: " {"exception":"[object] (GraphQL\\Error\\Error(code: 0): Config element \"String\" is not declared in GraphQL schema at " #1874).
2. getType() falls through to getScalarOverrides(), which calls materializeTypes() — fully resolving the types config to scan it for ScalarType instances shadowing built-in names.

When types is a lazy callable, that scan resolves it entirely. This silently turns the documented lazy schema pattern — typeLoader for per-name loading plus a lazy types callable for types not reachable from the root types — eager on the first executed query, for every schema, including the overwhelming majority that define no scalar overrides at all. The cost lives inside the user's callable, so the library cannot be lazy after invoking it; the only fix is to not invoke it on the hot path.

In PHP-FPM the Schema is rebuilt per request, so this is a per-request cost. Downstream impact observed in a Lighthouse (nuwave/lighthouse) app: every GraphQL operation became 1.5–3.4× slower wall-clock between 15.30.2 and 15.32.3 (~6× more PHP work, xdebug cachegrind 9.1 MB → 57 MB for an authed { __typename } request). Lighthouse's SchemaBuilder::build() is exactly this pattern:

$config->setTypeLoader(fn ($name) => $this->typeRegistry->search($name)); // lazy
$config->setTypes(fn (): array => $this->typeRegistry->possibleTypes());  // builds ALL types from the AST when invoked

Repro

$config = SchemaConfig::create()
    ->setQuery($query)
    ->setTypeLoader($lazyLoader)
    ->setTypes($countingCallableBuilding500Types);

$schema = new Schema($config);
$schema->getType('Boolean'); // per-request hot path

graphql-php	types materialised by one getType('Boolean')
v15.30.2	0 / 500
v15.31.0 … v15.32.3	500 / 500
this PR, default config	500 / 500 (unchanged)
this PR, scalarOverrides set (e.g. [])	0 / 500

The fix

Overrides cannot be discovered from a lazy types callable without resolving it — that is fundamental. So this PR makes explicitness possible instead: a new SchemaConfig option scalarOverrides.

• null (default): discover by scanning types, exactly as before — zero behaviour change for existing users.
• An array (including [] for "none"): use exactly these overrides, never scan. Explicit overrides take precedence in getTypeMap() the same way discovered ones do.

$schema = new Schema([
    'query' => $queryType,
    'typeLoader' => $myTypeLoader,
    'types' => $myLazyTypes,
    'scalarOverrides' => [$uppercaseString], // or [] for none
]);

The setter validates entries are ScalarType instances named after built-in scalars.

This gives lazy-schema users a one-line opt-out while keeping the scalar-overrides feature fully intact. If this lands, Lighthouse's SchemaBuilder::build() could pass its known overrides (usually []) explicitly and restore its pre-15.31 per-request performance — happy to file the companion PR there.

Downstream context: we currently pin 15.30.2 to avoid the regression, which re-exposes GHSA-r7cg-qjjm-xhqq, GHSA-fc86-6rv6-2jpm and the 15.31.5 quadratic-validation fix — this change is what would let us (and others in the same spot) unpin.

🤖 Generated with Claude Code

[spawnia]

Hey, tried to update this branch against master but ran into a GitHub quirk: deskpro/graphql-php is an organization-owned fork, and "Allow edits from maintainers" doesn't actually grant push access for org-owned forks (only personal-account ones), even though the API reports it as enabled.

I already merged master in and validated locally (fix/stan/test all green), so it's ready - could you or someone with access to the org fork pull master in and push? Happy to share the exact diff if useful.

[tmoitie]

Hi @spawnia, looks like your merge made it through. I checked on my end as well and I'm getting "Already up to date"

[Copilot]

Pull request overview

Adds an explicit scalarOverrides option on SchemaConfig/Schema to avoid resolving lazy types during hot-path built-in scalar lookups, addressing the lazy-loading regression introduced by per-schema scalar overrides.

Changes:

• Introduce SchemaConfig::$scalarOverrides plus getScalarOverrides() / setScalarOverrides() with validation for built-in scalar names.
• Update Schema::getScalarOverrides() to use explicit overrides when provided, skipping the types scan.
• Add regression tests and update docs + changelog to document the new option and its lazy-loading implications.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/Type/ScalarOverridesTest.php	Adds coverage for explicit overrides preserving lazy types, precedence in getTypeMap(), and setter validation behavior.
src/Type/SchemaConfig.php	Adds scalarOverrides configuration, API accessors, and validation/normalization into a name-keyed map.
src/Type/Schema.php	Uses explicit scalarOverrides to bypass scanning types for scalar override discovery.
docs/type-definitions/scalars.md	Documents scalarOverrides as an alternative to types for overriding built-ins without resolving lazy types.
docs/schema-definition.md	Updates schema config options table to include scalarOverrides and clarify lazy-resolution behavior.
docs/class-reference.md	Adds scalarOverrides option and new getter/setter to the class reference.
CHANGELOG.md	Notes the new scalarOverrides option under Unreleased additions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tmoitie]

Hi @spawnia, would you like me to action this one?

Feedback from my claude was that as written, it matches existing convention. Docblock documents name-keyed contract.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/Type/Schema.php:381

• getScalarOverrides() returns $this->config->scalarOverrides verbatim when non-null, but the code later assumes it is keyed by scalar name (e.g. isset($scalarOverrides[$name])). Because SchemaConfig::$scalarOverrides is a public property, users can set it directly as a list (e.g. [$uppercaseString]), which would silently skip the discovery scan and fail to apply the override (numeric keys). Consider normalizing/validating the explicit overrides here (or via SchemaConfig::setScalarOverrides()) before caching them.

            $explicitScalarOverrides = $this->config->scalarOverrides;
            if ($explicitScalarOverrides !== null) {
                return $this->scalarOverrides = $explicitScalarOverrides;
            }