Repository navigation
[Capability] Map PHPDoc pseudo-types to the JSON Schema type of their base type - #643
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved schema-generation defects produce invalid nested-array schemas, mishandle quoted literals and associative key types, and drop shape fields, potentially causing clients to reject schemas or valid inputs.
4 open issues
What changed in this PR
This PR addresses #641 by extending PHPDoc-to-JSON Schema mapping so supported pseudo-types and literals use their base types rather than defaulting to object.
Changes:
- Adds shared mappings for string and integer pseudo-types, literals, and non-empty collections.
- Expands array-shape handling for generic collections, string-keyed maps, and
mixedvalues. - Adds regression coverage and documents the behavior in the changelog.
| File | Description |
|---|---|
| tests/Unit/Capability/Discovery/SchemaGeneratorTest.php | Adds assertions for pseudo-types and collection types within shapes. |
| tests/Unit/Capability/Discovery/SchemaGeneratorFixture.php | Adds a PHPDoc fixture covering the new mappings. |
| src/Capability/Discovery/SchemaGenerator.php | Implements pseudo-type mappings and expands generic and shape parsing. |
| CHANGELOG.md | Documents the schema-generation fixes under 0.10.0. |
Review effort: Balanced
7a9176f to
c3cbbb1
Compare
…d `mixed` schemas
There was a problem hiding this comment.
🟡 Changes recommended
Schema generation misclassifies quoted-literal arrays and rejects valid sparse integer-keyed and empty string-keyed maps, causing valid arguments to fail validation.
3 open issues
4 resolved since last review
Review effort: Balanced
chr-hertel
left a comment
There was a problem hiding this comment.
Thanks @sarankumar1325 - extended it with more test cases and bumped some libs with #657 for better support 👍
Fixes #641
PHPStan/Psalm pseudo-types and literal types in a tool's DocBlock fell through to the
default => 'object'branch of the type mapping, so a tool taking e.g.@param non-empty-string $nameadvertised{"type": "object"}and rejected a valid string argument with-32602.This change maps them to their base type, both for parameters and for keys of an array shape:
non-empty-string,numeric-string,class-string,lowercase-string, …objectstringpositive-int,non-negative-int,negative-int, …objectintegerarray-keyobject["integer", "string"]'asc'|'desc'/1|2/trueobjectstring/integer/boolean?non-empty-string,?positive-int,?list<T>, …["null", "object"]nullnon-empty-list<T>,non-empty-array<T>objectarraywithitemsofTnon-empty-array<string, V>objectobjectnon-empty-array<int, V>,non-empty-array<array-key, V>object["array", "object"]Inside an array shape:
list<T>andnon-empty-list<T>keys become arrays.array<K, V>keys depend onK: string-like keys become objects withadditionalProperties, every other key (int,array-key,int|string) allows both arrays and objects, as sparse int keys arrive as an object.mixedkeys get the empty schema{}, so they accept any value.Splitting a union or a shape now skips quoted literals and tracks
<>, so'a|b','a,b','<'and the comma ofarray<int, T>stay in their key. Nestedmixedencodes asitems: {}instead of[], and the existingint<min, max>handling moved into the same helper.Not covered:
array<string, V>map and{"0": 1}are still rejected, as{}decodes to[]- that's SchemaValidator rejects nested empty JSON objects as arrays #586.array<string, V>andarray<int, V>stayarray, like onmain.value-of<X>orint-mask<…>still becomeobject, there is no native type fallback.Requires
reflection-docblock^6.0from #657, older parsers drop the@paramfor types likenon-empty-array<T>.Tests:
testMapsPhpStanAndPsalmPseudoTypesToTheirBaseTypeplus data-provider tests that check the schema and run valid & invalid arguments throughSchemaValidator. Passes with lowest & highest dependencies. I also added a CHANGELOG entry under 0.10.0.I used an AI assistant to help write this change. I reviewed and tested it.