[FEATURE] Generate precise types for endpoints to allow static analysis tools to understand the signatures

[stof]

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?

[saimedhi]

Hi @stof , please feel free to contribute. Thank you.

[dblock]

Catch All Triage - 1, 2, 3