SchemaGenerator implements SchemaGeneratorInterface
Generates JSON Schema for method parameters with intelligent Schema attribute handling.
Priority system:
- Schema attributes (method-level and parameter-level)
- Reflection type information
- DocBlock type information
Tags
Table of Contents
Interfaces
- SchemaGeneratorInterface
- Provides JSON Schema generation for reflected elements.
Properties
Methods
- __construct() : mixed
- generate() : array<string, mixed>
- Generates a JSON Schema object (as a PHP array) for parameters.
- generateOutputSchema() : array<string, mixed>|null
- Generates a JSON Schema object (as a PHP array) for a method's or function's return type.
- splitUnion() : array<int, string>
- Splits a type string on its top-level `|`, leaving generics and shapes intact.
- applyArrayConstraints() : array<string|int, mixed>
- Applies array-specific constraints to parameter schema.
- applyEnumConstraints() : array<string|int, mixed>
- Applies enum constraints to parameter schema.
- buildInferredParameterSchema() : InferredParameterSchema
- Builds parameter schema from inferred type and docblock information only.
- buildParameterSchema() : array<string|int, mixed>
- Builds the final schema for a single parameter by merging all three levels.
- buildSchemaFromParameters() : array<string, mixed>
- Builds the final schema from parameter information and method-level schema.
- buildVariadicParameterSchema() : array<string, mixed>
- Builds schema for variadic parameters.
- ensureArrayItems() : array<string, mixed>
- Guarantees an array-typed schema always declares `items`.
- ensureObjectDefault() : array<string, mixed>
- An empty PHP array encodes as `[]`, which a client could not send back to an object-only parameter.
- extractMethodLevelSchema() : SchemaAttributeData
- Extracts method-level or function-level Schema attribute.
- extractParameterLevelSchema() : SchemaAttributeData
- Extracts parameter-level Schema attribute.
- getParameterTypeString() : string
- Determines the type string for a parameter, prioritizing DocBlock.
- getTypeStringFromReflection() : string
- Converts a ReflectionType object into a type string representation.
- hasNullBranch() : bool
- Whether `null` is one of the top-level alternatives of a type, as in `string|null`. A `null` inside a generic or a shape, as in `array{name: string|null}`, belongs to that inner type and does not make the whole type nullable.
- inferArrayItemsType() : string|array<string, mixed>
- Infers the 'items' schema type for an array based on DocBlock type hints.
- inferParameterTypes() : array<string|int, mixed>
- Infers JSON Schema types for a parameter.
- mapPhpTypeToJsonSchemaType() : array<string|int, string>
- Maps a PHP type string (potentially a union) to an array of JSON Schema type names.
- mapPseudoTypeToJsonSchemaTypes() : array<int, string>|null
- Maps a PHPStan/Psalm pseudo-type or a literal type to the JSON Schema types of its base type, e.g. `non-empty-string` to `string`, `positive-int` or `int<0, max>` to `integer` and `'a'` to `string`.
- mapSimpleTypeToJsonSchema() : string
- Helper method to map basic PHP types to JSON Schema types.
- mapTypeToSchema() : array<string, mixed>
- Maps a type inside a shape or generic, e.g. `string`, `int[]|null` or `array{x: int}`, to a JSON Schema.
-
parseObjectLikeArray()
: array{type: "object", properties?: array
, required?: string[]} - Parses object-like array syntax into a JSON Schema object.
- parseParametersInfo() : array<string|int, ParameterInfo>
- Parses detailed information about a method's parameters.
- parsePropertyDefinition() : void
- Parses a single property definition from an object-like array syntax.
- splitTopLevel() : array<int, string>
- Splits a type string on a separator outside of generics, shapes, parentheses and quoted literals.
Properties
$docBlockParser read-only
private
DocBlockParser
$docBlockParser
Methods
__construct()
public
__construct(DocBlockParser $docBlockParser) : mixed
Parameters
- $docBlockParser : DocBlockParser
generate()
Generates a JSON Schema object (as a PHP array) for parameters.
public
generate(Reflector $reflection) : array<string, mixed>
Parameters
- $reflection : Reflector
Return values
array<string, mixed>generateOutputSchema()
Generates a JSON Schema object (as a PHP array) for a method's or function's return type.
public
generateOutputSchema(Reflector $reflection) : array<string, mixed>|null
Only returns an outputSchema if explicitly provided in the McpTool attribute. Per MCP spec, outputSchema should only be present when explicitly provided.
Parameters
- $reflection : Reflector
Return values
array<string, mixed>|nullsplitUnion()
Splits a type string on its top-level `|`, leaving generics and shapes intact.
public
static splitUnion(string $type) : array<int, string>
int|string splits; array<int|string> and array{a: int|string} do
not, because the | there is a parameter of the outer type rather than
an alternative to it.
Parameters
- $type : string
Return values
array<int, string>applyArrayConstraints()
Applies array-specific constraints to parameter schema.
private
applyArrayConstraints(array<string|int, mixed> $paramSchema, array<string|int, mixed> $paramInfo) : array<string|int, mixed>
Parameters
- $paramSchema : array<string|int, mixed>
- $paramInfo : array<string|int, mixed>
Return values
array<string|int, mixed>applyEnumConstraints()
Applies enum constraints to parameter schema.
private
applyEnumConstraints(array<string|int, mixed> $paramSchema, array<string|int, mixed> $paramInfo) : array<string|int, mixed>
Parameters
- $paramSchema : array<string|int, mixed>
- $paramInfo : array<string|int, mixed>
Return values
array<string|int, mixed>buildInferredParameterSchema()
Builds parameter schema from inferred type and docblock information only.
private
buildInferredParameterSchema(ParameterInfo $paramInfo) : InferredParameterSchema
Returns empty array for variadic parameters (handled separately).
Parameters
- $paramInfo : ParameterInfo
Return values
InferredParameterSchemabuildParameterSchema()
Builds the final schema for a single parameter by merging all three levels.
private
buildParameterSchema(ParameterInfo $paramInfo, array<string, mixed>|null $methodLevelParamSchema) : array<string|int, mixed>
Parameters
- $paramInfo : ParameterInfo
- $methodLevelParamSchema : array<string, mixed>|null
Return values
array<string|int, mixed>buildSchemaFromParameters()
Builds the final schema from parameter information and method-level schema.
private
buildSchemaFromParameters(array<string|int, ParameterInfo> $parametersInfo, SchemaAttributeData $methodSchema) : array<string, mixed>
Parameters
- $parametersInfo : array<string|int, ParameterInfo>
- $methodSchema : SchemaAttributeData
Return values
array<string, mixed>buildVariadicParameterSchema()
Builds schema for variadic parameters.
private
buildVariadicParameterSchema(ParameterInfo $paramInfo) : array<string, mixed>
Parameters
- $paramInfo : ParameterInfo
Return values
array<string, mixed>ensureArrayItems()
Guarantees an array-typed schema always declares `items`.
private
ensureArrayItems(array<string, mixed> $schema) : array<string, mixed>
items is optional in JSON Schema, but some strict clients reject an array schema
without it. When no element type could be inferred, default to the empty schema }
(matches anything) — represented as new \stdClass() so it serializes to } rather
than [].
Parameters
- $schema : array<string, mixed>
Return values
array<string, mixed>ensureObjectDefault()
An empty PHP array encodes as `[]`, which a client could not send back to an object-only parameter.
private
ensureObjectDefault(array<string, mixed> $schema) : array<string, mixed>
Parameters
- $schema : array<string, mixed>
Return values
array<string, mixed>extractMethodLevelSchema()
Extracts method-level or function-level Schema attribute.
private
extractMethodLevelSchema(ReflectionFunctionAbstract $reflection) : SchemaAttributeData
Parameters
- $reflection : ReflectionFunctionAbstract
Return values
SchemaAttributeDataextractParameterLevelSchema()
Extracts parameter-level Schema attribute.
private
extractParameterLevelSchema(ReflectionParameter $parameter) : SchemaAttributeData
Parameters
- $parameter : ReflectionParameter
Return values
SchemaAttributeDatagetParameterTypeString()
Determines the type string for a parameter, prioritizing DocBlock.
private
getParameterTypeString(ReflectionParameter $rp, Param|null $paramTag) : string
Parameters
- $rp : ReflectionParameter
- $paramTag : Param|null
Return values
stringgetTypeStringFromReflection()
Converts a ReflectionType object into a type string representation.
private
getTypeStringFromReflection(ReflectionType|null $type, bool $nativeAllowsNull) : string
Parameters
- $type : ReflectionType|null
- $nativeAllowsNull : bool
Return values
stringhasNullBranch()
Whether `null` is one of the top-level alternatives of a type, as in `string|null`. A `null` inside a generic or a shape, as in `array{name: string|null}`, belongs to that inner type and does not make the whole type nullable.
private
static hasNullBranch(string $type) : bool
Parameters
- $type : string
Return values
boolinferArrayItemsType()
Infers the 'items' schema type for an array based on DocBlock type hints.
private
inferArrayItemsType(string $phpTypeString) : string|array<string, mixed>
Parameters
- $phpTypeString : string
Return values
string|array<string, mixed>inferParameterTypes()
Infers JSON Schema types for a parameter.
private
inferParameterTypes(ParameterInfo $paramInfo) : array<string|int, mixed>
Parameters
- $paramInfo : ParameterInfo
Return values
array<string|int, mixed>mapPhpTypeToJsonSchemaType()
Maps a PHP type string (potentially a union) to an array of JSON Schema type names.
private
mapPhpTypeToJsonSchemaType(string $phpTypeString) : array<string|int, string>
Parameters
- $phpTypeString : string
Return values
array<string|int, string>mapPseudoTypeToJsonSchemaTypes()
Maps a PHPStan/Psalm pseudo-type or a literal type to the JSON Schema types of its base type, e.g. `non-empty-string` to `string`, `positive-int` or `int<0, max>` to `integer` and `'a'` to `string`.
private
static mapPseudoTypeToJsonSchemaTypes(string $type) : array<int, string>|null
Parameters
- $type : string
Return values
array<int, string>|null —null when the type is not a known pseudo-type
mapSimpleTypeToJsonSchema()
Helper method to map basic PHP types to JSON Schema types.
private
mapSimpleTypeToJsonSchema(string $type) : string
Parameters
- $type : string
Return values
stringmapTypeToSchema()
Maps a type inside a shape or generic, e.g. `string`, `int[]|null` or `array{x: int}`, to a JSON Schema.
private
mapTypeToSchema(string $type) : array<string, mixed>
Parameters
- $type : string
Return values
array<string, mixed>parseObjectLikeArray()
Parses object-like array syntax into a JSON Schema object.
private
parseObjectLikeArray(string $propertiesStr) : array{type: "object", properties?: array, required?: string[]}
Parameters
- $propertiesStr : string
Return values
array{type: "object", properties?: arrayparseParametersInfo()
Parses detailed information about a method's parameters.
private
parseParametersInfo(ReflectionMethod|ReflectionFunction $reflection) : array<string|int, ParameterInfo>
Parameters
- $reflection : ReflectionMethod|ReflectionFunction
Return values
array<string|int, ParameterInfo>parsePropertyDefinition()
Parses a single property definition from an object-like array syntax.
private
parsePropertyDefinition(string $propDefinition, array<string|int, mixed> &$properties, array<string|int, mixed> &$required) : void
Parameters
- $propDefinition : string
- $properties : array<string|int, mixed>
- $required : array<string|int, mixed>
splitTopLevel()
Splits a type string on a separator outside of generics, shapes, parentheses and quoted literals.
private
static splitTopLevel(string $type, string $separator) : array<int, string>
Parameters
- $type : string
- $separator : string