Is your feature request related to a problem?
Currently, the generated code for endpoints uses @param array $params, which does not provide any information to static analysis tools about the supported parameters.
What solution would you like?
The generated code has some documentation for parameters, so more precise information is already available in the generator. It would be great to use it to describe the proper array shape. This would allow phpstan and psalm to detect invalid usages of the client.
Compared to the existing human-readable documentation, a few changes are needed though:
- the boolean type is named
bool in PHP types, not boolean
- the double-precision type is not named
number (which is its name in Javascript and so in JSON) but float
- a bunch of number fields are probably expecting integers. If the info is available in the API schema used by the generator, it would be great to use the
int type then rather than float
- the top type accepting any value is named
mixed in PHP, not any
- for enum values, the type should use a union type of string literals to describe it
- for parameters expecting a JSON array, the type should be documented as
list<mixed> (or even better list<string> if values inside the array are expected to be strings) instead of using array as not all PHP arrays are lists (and both phpstan and psalm are able to perform such analysis)
- parameters expected a query DSL should probably be documented as
array<string, mixed> (for full type safety, projects could use https://packagist.org/packages/shyim/opensearch-php-dsl as a way to build the query DSL through a PHP API that can be analyzed statically)
- parameters expecting a JSON object using
additionalProperties should be typed as array<string, mixed>
What alternatives have you considered?
Writing a phpstan plugin providing stubs maintained manually for all methods would be totally unmaintainable. It is a lot easier to make the code generator include the info directly.
Do you have any additional context?
Is your feature request related to a problem?
Currently, the generated code for endpoints uses
@param array $params, which does not provide any information to static analysis tools about the supported parameters.What solution would you like?
The generated code has some documentation for parameters, so more precise information is already available in the generator. It would be great to use it to describe the proper array shape. This would allow phpstan and psalm to detect invalid usages of the client.
Compared to the existing human-readable documentation, a few changes are needed though:
boolin PHP types, notbooleannumber(which is its name in Javascript and so in JSON) butfloatinttype then rather thanfloatmixedin PHP, notanylist<mixed>(or even betterlist<string>if values inside the array are expected to be strings) instead of usingarrayas not all PHP arrays are lists (and both phpstan and psalm are able to perform such analysis)array<string, mixed>(for full type safety, projects could use https://packagist.org/packages/shyim/opensearch-php-dsl as a way to build the query DSL through a PHP API that can be analyzed statically)additionalPropertiesshould be typed asarray<string, mixed>What alternatives have you considered?
Writing a phpstan plugin providing stubs maintained manually for all methods would be totally unmaintainable. It is a lot easier to make the code generator include the info directly.
Do you have any additional context?