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.
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:
bool
in PHP types, notboolean
number
(which is its name in Javascript and so in JSON) butfloat
int
type then rather thanfloat
mixed
in PHP, notany
list<mixed>
(or even betterlist<string>
if values inside the array are expected to be strings) instead of usingarray
as 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)additionalProperties
should 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?