Repository navigation
[Capability] Map PHPDoc pseudo-types to the JSON Schema type of their base type - #643
Open
sarankumar1325 wants to merge 3 commits into
Open
sarankumar1325 wants to merge 3 commits into
sarankumar1325 wants to merge 3 commits into
Conversation
sarankumar1325
requested review from
CodeWithKyrian,
Nyholm,
chr-hertel and
soyuka
as code owners
October 31, 2026 00:55
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. |
Contributor
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
Comment on lines
+833
to
+834
| if (preg_match('/^(\'[^\']*\'|"[^"]*")$/', $type)) { | ||
| return ['string']; |
Comment on lines
+880
to
+882
| if (!isset($itemSchema['type'])) { | ||
| return 'any'; | ||
| } |
Comment on lines
+929
to
+932
| if ('{' === $char || '<' === $char) { | ||
| ++$depth; | ||
| $buffer .= $char; | ||
| } elseif ('}' === $char) { | ||
| } elseif ('}' === $char || '>' === $char) { |
Comment on lines
+1018
to
+1020
| if (preg_match('/^(?:non-empty-)?array\s*<\s*(?:string|non-empty-string|class-string)\s*,\s*(.+?)\s*>$/is', $type, $matches)) { | ||
| return ['type' => 'object', 'additionalProperties' => $this->mapTypeToSchema($matches[1]) ?: true]; | ||
| } |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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/booleannon-empty-list<T>,non-empty-array<T>objectarraywithitemsofTInside an array shape:
list<T>,non-empty-list<T>andarray<int, T>keys become arrays. The comma ofarray<int, T>no longer splits the shape key in two, becauseparseObjectLikeArray()now tracks<>depth as well as{}.array<string, T>keys become objects withadditionalProperties.mixedkeys get the empty schema{}, so they accept any value.The existing
int<min, max>handling moved into the same helper.Tests: added
testMapsPhpStanAndPsalmPseudoTypesToTheirBaseTypewith apseudoTypesfixture. It fails before this change and passes after.vendor/bin/phpunit --testsuite unit(2696 tests) passes, as dophp-cs-fixer fix --dry-runandphpstan. 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.