jane-php/json-schema-runtime

fix: audit category A — bugs & correctness fixes (+ redirect option &…

fix: audit category A — bugs & correctness fixes (+ redirect option &…

• Runtime quality & PHP modernization (cleanup-d-runtime) (#1060)

• runtime(json-schema): add reference exception hierarchy and wrap foreign failures

Introduce domain exceptions under JsonSchemaRuntime\Exception, all extending
the existing ReferenceResolveException (itself a RuntimeException implementing
JaneExceptionInterface) so \RuntimeException catch blocks keep working:

• ReferenceFetchException: unreadable document, refused redirect
• ReferenceDecodeException: content neither JSON nor YAML, re-encode failure
• ReferencePointerException: Rs\Json\Pointer construction or resolution
• InvalidReferenceException: scheme / containment / external-ref / host policy

Replace the remaining generic \RuntimeException throws in Reference with the
specific classes, and wrap the foreign exceptions (league/uri constructor,
Rs\Json\Pointer) with informative messages and previous-exception chaining.

Also cache the league/uri v6-vs-v7 method_exists() capability sniff once per
process instead of running it on every Reference construction.

• runtime(json-schema): drop error suppression and identity closure in Reference

Replace the three @realpath() calls with explicit existence guards (is_dir /
file_exists) before resolving, keeping the existing false-return fallbacks
so no warnings are emitted and behavior is unchanged.

resolve() now invokes-through when the deserializeCallback is null instead of
allocating an identity closure on every call; PHP passes scalars and arrays
by value anyway, so returning the resolved value directly is equivalent.

• cs: restore runtime template exclusions and fix pre-existing violations

PR #1049 moved the runtime templates from Generator/Runtime/data to
Generator/Runtime, leaving the php-cs-fixer exclusions pointing at the old
paths: the templates (which are emitted verbatim into generated code and
deliberately use fully-qualified names) fell back into the fixer scope and
failed the cs:check gate.

Restore the exclusions to the moved directories, and reorder the trait uses
in the three NonBodyParameterGenerator variants that were already failing
cs:check on the base branch (unrelated to the runtime work but required for
the gate to pass).

• runtime: type and modernize emitted client templates

Type the shipped runtime surface conservatively:

• CustomQueryResolver::__invoke takes mixed $value (both the dedicated
  OpenApiRuntime copy and the emitted runtime template)
• Endpoint::getBody and BaseEndpoint's abstract declaration accept an
  optional ?StreamFactoryInterface instead of an untyped $streamFactory
  parameter (widening only: untyped callers and generated endpoints still
  work), getMultipartBody is typed the same way
• BaseEndpoint / EndpointTrait document @return mixed on the abstract
  transformResponseBody, shared between the two declarations
• ServerPluginGenerator's discoverServer / needsServerPlugins /
  getServerPluginsStatements typed with mixed $openApi plus an @PARAM object
  docblock (the three per-component implementations receive their own parsed
  OpenAPI model, so mixed is the safe in-repo widest type)

Modernize the emitted templates:

• Runtime/Client/Client: promote the four constructor-injected properties to
  protected readonly (they are never reassigned), and replace the scope-copy
  loop over getAuthenticationScopes() with a direct reuse of the array
• Runtime/Client/BaseEndpoint: drop a redundant pair of parentheses in the
  multipart boundary concatenation
• Normalizer/CheckArray: arrow-fn version of the numeric-key filter callback
• OpenAPI3 + OpenAPI31 GetTransformResponseBodyTrait: emit
  $contentType !== null instead of is_null($contentType) === false

Add a comment documenting the by-design mapping of null query options to
empty values in BaseEndpoint::getQueryString (item: document-current).

Update Issue588RegressionTest: containment violations now implement
JaneExceptionInterface and are rendered as a console [ERROR] block by the
generate command (ADR 0002) instead of being thrown, so the test asserts on
the command exit code and the rendered message.

• test: regenerate fixtures for runtime template modernization

Regenerate every component's expected fixtures to match the updated shipped
runtime templates (typed Client constructor with promoted readonly properties,
collapsed authentication scope reuse, arrow-fn CheckArray, null-safe multipart
boundary) and the shorter $contentType !== null emission from the OpenAPI3 /
OpenAPI31 transformResponseBody generators. Runtime boilerplate in functional
(.full-compare) fixtures is refreshed in lockstep; manifest fixtures
(github, twitter, api-platform-demo) are re-hashed.

• runtime: add return type on executeEndpoint and type Client::create httpClient

Soft-BC-risky generated-code contract changes (flagged for maintainer review):

• The emitted Runtime\Client\Client::executeEndpoint() now declares a mixed
  return type. The method returns either a ResponseInterface (response fetch
  mode) or the parsed object/array (object mode), so mixed is the honest
  widest signature. Userland code overriding executeEndpoint without a return
  type would now trigger a fatal error, which is why this is flagged.
• The generated Client::create() factory types its first parameter as
  ?Psr\Http\Client\ClientInterface instead of leaving it untyped, so callers
  passing a non-PSR-18 client get a TypeError instead of a downstream failure.

Regenerated the OpenAPI fixtures (expected Client.php files) and the github /
twitter / api-platform-demo snapshot manifests to match.

• docs: note runtime exception hierarchy, typed client contract, template modernization

CHANGELOG entries for items 1-6 of the runtime quality pass: the reference
exception hierarchy, the removed identity closure / cached league-uri sniff,
the conservatively typed shipped interface surface, the (flagged) generated
client contract changes, the emitted-template modernization, the documented
null-query-option behavior (document-current) and the @realpath removal.

• runtime: drop redundant phpdoc on typed resolver methods

cs:check considers @PARAM mixed redundant on a native mixed parameter and
@return array redundant on a native array return, so remove them from the
CustomQueryResolver interface (shipped + emitted copies) and from
ServerPluginGenerator::getServerPluginsStatements. The @PARAM object
docblock on the mixed $openApi parameters is kept: it conveys the actual
per-component model that mixed erases.

• feat(json-schema)!: generate models with public typed properties (#1028)

• feat(json-schema)!: generate models with public typed properties

• fix(open-api): migrate leftover Schema accessor calls in BodyParameterGenerator

The public typed properties migration (37003b743) rewrote most document
model reads but missed getAllOf() / getType() / getFormat() on the
resolved body parameter schema, crashing generation for any Swagger 2
spec with an allOf body parameter reference (regression caught by the
issue-770 fixture, whose expected baseline had been deleted in the
fixture sweep for exactly this reason).

Reads now use null-coalesced property access, matching the idiom used
across the migrated guessers: uninitialized (unassigned) properties
behave like the former implicit nulls.

Restores the issue-770 expected baseline (6875 files) regenerated with
the fixed generator.

• test(open-api): migrate prism client tests to public property models

Generated models no longer ship getters/setters, so testClient()
exercised removed accessors and errored in every CI job:

• $thing->getKind() / getCreatedAt() / getTags()
• $thingInput->setName() / setKind()
• $thingDetails->getDescription()

Replaced with direct property access and regenerated the committed
client baselines for OpenApi2 / OpenApi3 / OpenApi31, which still held
the old accessor-based output.

• refactor: architecture & design-pattern cleanup (category B) for 8.x (#1061)

• refactor: eliminate global static state from reference resolution, validator factory, schema parser

Extract resolution config and fetch caches out of JsonSchemaRuntime\Reference
into a dedicated ReferenceResolver instance threaded through the generation
pipeline (generated code keeps binding to a shared default resolver). Convert
ChainValidatorFactory to an instance factory (custom validators + date
formats become constructor state) wired through Jane, JaneOpenApi and the
guesser factories. Drop the static SchemaParser cache. In OpenApiCommon's
ExceptionGenerator, move status-text lookup to a private const and split the
base exception file generation into a dedicated BaseExceptionsGenerator that
implements GeneratorInterface, fixing the memoization precedence bugs that
triggered 'undefined array key' warnings.

• refactor: decompose generator god methods

Split the oversized generator entry points into small focused collaborators,
keeping every emitted AST byte-for-byte identical:

• DenormalizerGenerator::createDenormalizeMethod into reference short-circuit,
  scalar cast, validation, property and pattern-property statement builders
• NormalizerGenerator::createNormalizeMethod into property normalization
  (honouring the skip-null/skip-required/include-null matrix), pattern
  extension folding and validation statement builders
• ValidatorGenerator::generate into a createConstraints() collaborator, also
  removing the local shadowing
• ClientGenerator::getFactoryMethod into per-statement builders
• AuthenticationGenerator::createAuthentication into a match() dispatch with a
  helper per HTTP/apiKey/header/query case instead of triple-nested switches

• feat: frozen generation Options DTO as single source of defaults

Introduce Jane\JsonSchema\Generator\Options, an immutable value object
carrying every generation option with one canonical default each. The raw
array entry points (JsonSchema/OAI2/OAI3/OAI31 build(), the three guesser
factories and the console ConfigLoaders) keep accepting arrays and hydrate the
DTO via fromArray()/toArray(), so a new option only needs a default declared
in one place.

Behavioral cleanup folded in:

• programmatic JsonSchema build() no longer requires a bare 'reference' key
  (defaults to false instead of fatally missing)
• OpenAPI generators() no longer emits a notice for a missing
  'endpoint-generator' key ('?? EndpointGenerator::class' replaces '?:')
• console JsonSchema configs keep the historical 'reference' => true override
  while their remaining defaults now come from the DTO

• refactor: consolidate anyOf/oneOf reference guessers into a parameterized base

Introduce OpenApiCommon\Guesser\OpenApiSchema\AbstractXOfReferenceGuesser
carrying the shared union guessing logic, parameterized by the union keyword,
the version schema class and small behavioral hooks (OpenAPI 3.1 allOf-wrapped
references, richer has-content detection, optional class-guessing recursion for
oneOf). The mis-spelled version-local class names (AnyOfReferencefGuesser,
OneOfReferencefGuesser) are removed; OpenApi3\AnyOfReferenceGuesser,
OpenApi31\AnyOfReferenceGuesser and OpenApi31\OneOfReferenceGuesser replace
them and are wired in both guesser factories.

• refactor: consolidate OpenAPI 3/3.1 generator clones

Move the 100% identical request body content generators (interface, default
and JSON payload generators plus their shared abstract) into
OpenApiCommon\Generator\RequestBodyContent, parameterized by the version
schema class; the version-local FormBodyContentGenerator and
RequestBodyGenerator stay (real per-version drift) but now extend the common
bases. EndpointGenerators (book marker: version flows)

Also move GetTransformResponseBodyTrait to OpenApiCommon\Generator\Endpoint
with three abstract hooks (schemaClassName / responseClassName /
responseNormalizerClassName) replacing the version imports, folding the
OpenAPI 3.1 array-type response handling into the shared convertResponseType
guard, and move the comment-only GetGetExtraHeadersTrait there too. Both
version-local copies are deleted (8.x, no BC aliases). GeneratorFactory and
the GuessClass forks stay version-local: they parameterize NonBodyParameter,
request-body and client generators and the version Parameter models.

• refactor: remove version-model imports from shared components

Replace version-specific lookups with duck-typed / guarded accessors so
OpenApiCommon no longer imports OpenApi2/3/31 model classes:

• OperationUrlNaming drops the OA2/3/31 Response & Schema imports and the
  class_exists guards: response shapes are recognized through getSchema() /
  getContent() accessors and schema nullability through getType() with guards
  against still-unresolved Reference payloads
• ExceptionGenerator-adjacent ConstructGenerator no longer imports the OA3
  HTTPSecurityScheme model (guarded getScheme() accessor)
• HttpClientCreateGenerator drops the OA3 OpenApi import: the parsed document
  is opaque to the shared client-builder trait
• ObjectCheckTrait / CheckNullableTrait (and the nullable shortcut in the
  string validators) detect nullability and schema-ness through the schema
  accessors instead of hard-coded version FQCN strings, so the JsonSchema
  component stops knowing about OpenAPI model class names

• refactor: make ChainGuesser dispatch semantics explicit

Route guessers into typed buckets at registration time (class / type /
property guessers) instead of re-filtering a single list with instanceof on
every dispatch. Broadcast semantics for guessClass/guessProperties and
first-match semantics for guessType are now documented and enforced per role,
with registration order preserved so dispatch stays deterministic and
identical to the previous single-list behavior.

• chore: remove dead code and document recursion guard

• ArrayGuesser: drop the never-matching guessClass()/getSchemaClass() pair
  (its is_a(Schema::class) check could never fire, making the method a no-op)
  and the ClassGuesserInterface role; the recursion guard cap becomes a named
  MAX_REF_GUESS_LEVEL constant with a docblock
• Registry::getOptionsHash(): document the constant baseline (no options are
  tracked at this layer; OpenAPI registries override it)

• fix: keep ArrayGuesser class-guessing for OpenAPI, type role interfaces

The preceding dead-code removal dropped guessClass()/getSchemaClass() from the
JsonSchema ArrayGuesser, but the OpenAPI ArrayGuesser relies on them (its
SchemaClassTrait override targets the version Schema model), silently breaking
array item model guessing. Restore the base methods with an explanatory
docblock; the plain JsonSchema component's guessClass stays inert (items are
never Registry\Schema containers).

Also make ClassGuesserInterface / TypeGuesserInterface /
PropertiesGuesserInterface extend GuesserInterface (every implementation
already provides supportObject) and give ChainGuesser the inherited
supportObject() stub so its typed dispatch buckets type-check.

• feat: modernize emitted exception code and remove 8.x deprecations

Emitted-code modernization (regenerated fixtures):

• Generated status-level exception classes now use constructor property
  promotion (private readonly) instead of a property block plus constructor
  assignments, for both the response-only and response+body variants

Deprecation removal (8.x major):

• Runtime client no longer ships FETCH_RESPONSE / the deprecated $fetch
  'response' branch and trigger_deprecation; executeEndpoint always parses the
  response (executeRawEndpoint remains for raw access)
• Remove the deprecated Jane\Component\JsonSchema\Exception\JaneExceptionInterface
  alias; JsonSchema/OpenApi exceptions now implement the runtime marker
  directly, and the alias-specific test is deleted

Regenerated every component's expected fixtures (Exception promotion +
Runtime/Client cleanup); no Model/Normalizer/Endpoint drift.

• docs: record architecture decisions and 8.x deprecation removals

Add ADR 0008 (instance-owned reference resolution), ADR 0009 (frozen
generation Options value object) and ADR 0010 (OpenAPI 3/3.1 generator
consolidation), and index them. Add an Unreleased 'Removed' / 'Changed'
section to the CHANGELOG documenting the 8.x deprecation removals (Reference
static state, JaneExceptionInterface alias, generated-client FETCH_RESPONSE
mode, mis-spelled guesser names) and the behavioral consolidations.

• test: refresh github snapshot manifest after upstream runtime merge

The github fixture uses a snapshot manifest; upstream cleanup-d-runtime (#1060)
changed generated runtime output, so the hashes are regenerated from the
current generator. Emitted-code changes from this branch are included.

• fix: reconcile with public-typed-property models after rebase

Rebase onto c547f1909 (upstream merged cleanup-d-runtime #1060 which
regenerated document models with public typed properties and dropped getters)
required folding upstream's property-access style into the consolidated code:

• NormalizerGenerator: keep the decomposed collaborators but read properties
  through the coalesced backing property and isPropertyInitialized() (array_key_exists
  on get_object_vars) instead of the removed getters/isInitialized calls
• GetTransformResponseBodyTrait / AbstractBodyContentGenerator /
  AbstractXOfReferenceGuesser + anyOf/oneOf subclasses: switch from getter
  calls to public-property access (content/type/format/schema/enum/allOf/…)
• OperationUrlNaming / ConstructGenerator / CheckNullableTrait /
  ObjectCheckTrait: property-based duck-typing replaces both the version FQCN
  checks and the obsolete getter checks
• ArrayGuesser keeps guessClass/getSchemaClass (OpenAPI override relies on
  them) using items property access; recursion cap stays MAX_REF_GUESS_LEVEL
• Regenerate the 3 fixture Runtime AdditionalAndPatternProperties files that
  got mangled by the 3-way merge, and drop the now-stale phpstan suppression
  for FilePostBody::$item (the model exposes the property publicly)

• fix(phpstan): restore FilePostBody suppression and tolerate unmatched ignores

The OpenAPI3 fixtures issue-737 and multipart-nested-object both generate a
FilePostBody model in the same Tests\Expected\Model namespace. phpstan scans
fixtures and whichever FilePostBody definition it discovers first wins; the
scan order differs between environments, so CI resolves the issue-737 model
(no $item property) and reports property.notFound in
MultipartNestedObjectRuntimeTest while local resolves the multipart one.

Restore the suppression for that environment-dependent error and set
reportUnmatchedIgnoredErrors: false (the documented PHPStan 2.x remedy for
ignore patterns that may not match in every environment), so the build stays
green both where the error is reported and where the scan happens to resolve
the correct model.

fix: audit category A — bugs & correctness fixes (+ redirect option &…

Validate $ref resolution to prevent SSRF, LFI, and path traversal (#961)

Validate $ref resolution to prevent SSRF, LFI, and path traversal (#961)

Remove all ext-json from composer.json (#931)

Remove all ext-json from composer.json (#931)

Remove all ext-json from composer.json (#931)

Updates project to the new documentation site and records related tooling changes.

• Replace readthedocs links with https://jane.jolicode.com/ in root and component README
• Add Unreleased changelog entries: new docs using MkDocs & Mike; tooling updated to use castor

Fix version constraint for symfony 8 (#886)

Fix version constraint for symfony 8 (#886)

Fix version constraint for symfony 8 (#886)

• Add SF8 support

• Try workflow with SF 8

• Try

• Try

• Try

• Add fixtures

• Update matrix

• Fix

• Try