Invalid PHPDocs - optional array keys

[AnnaNtagiou]

A lot of PHPDocs were invalid as they had comments at the EOL.

After PHPStan 2.1.6, which supports comments at EOL, the PHPDocs are valid but incorrect. There are array keys that are not required but are not defined as optional.

For example, in ClientEndpointsTrait we have this PHPDoc.

         * @param array{
	 *     id: string, // (REQUIRED) Script ID
	 *     context: string, //  Script context
	 *     timeout: time, // Explicit operation timeout
	 *     master_timeout: time, // Specify timeout for connection to master
	 *     pretty: boolean, // Pretty format the returned JSON response. (DEFAULT: false)
	 *     human: boolean, // Return human readable values for statistics. (DEFAULT: true)
	 *     error_trace: boolean, // Include the stack trace of returned errors. (DEFAULT: false)
	 *     source: string, // The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests.
	 *     filter_path: list, // A comma-separated list of filters used to reduce the response.
	 *     body: array, // (REQUIRED) The document
	 * } $params

While only the id and body keys are required, the rest of the keys are not optional.

[AJenbo]

To the person looking in to this, optional keys should end with a ?:

       /**
         * @param array{
	 *     id: string, // (REQUIRED) Script ID
	 *     context?: string, //  Script context
	 *     timeout?: time, // Explicit operation timeout
	 *     master_timeout?: time, // Specify timeout for connection to master
	 *     pretty?: boolean, // Pretty format the returned JSON response. (DEFAULT: false)
	 *     human?: boolean, // Return human readable values for statistics. (DEFAULT: true)
	 *     error_trace?: boolean, // Include the stack trace of returned errors. (DEFAULT: false)
	 *     source?: string, // The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests.
	 *     filter_path?: string, // A comma-separated list of filters used to reduce the response.
	 *     body: array, // (REQUIRED) The document
	 * } $params

Also time is not a PHP type, should it be string, DateTime or int????

[kostirez1]

This is also the case for Cluster::health()? The PHPDoc specifies index (and all others) as mandatory, even though the function body proves otherwise.

Causing PHPStan to:

         Parameter #1 $params of method                                         
         Elastic\Elasticsearch\Endpoints\Cluster::health() expects              
         array{index: list, expand_wildcards:                                   
         Elastic\Elasticsearch\Endpoints\enum, level:                           
         Elastic\Elasticsearch\Endpoints\enum, local: bool, master_timeout:     
         Elastic\Elasticsearch\Endpoints\time, timeout:                         
         Elastic\Elasticsearch\Endpoints\time, wait_for_active_shards: string,  
         wait_for_nodes: string, ...}, array{timeout: '10s'} given.             
         🪪  argument.type                                                      
         💡 Array does not have offset 'index'.       

Perhaps this should be handled throughout the entire repository right from the start? Thanks for bringing this up and putting the time in this fast!

[ezimuel]

Thanks @AJenbo, @AnnaNtagiou and @kostirez1 for your feedback. I need to update and fix some of these PHPDoc, when I implemented this was a very experimental feature.

[AnnaNtagiou]

@ezimuel I fixed the optional array keys in Indices and ClientEndpointsTrait with #1426. Could you have a look if you have time?

[momala454]

i think elasticsearch is dead. What else could we use ?

[AJenbo]

meilisearch looks really interesting.

[ezimuel]

@momala454 Elasticsearch is not dead at all. Please use this repo for reporting issues only about the elasticsearch-php project. If you are interested in other discussions about Elasticsearch you can use https://discuss.elastic.co/.

[ezimuel]

@AnnaNtagiou sorry for my late reply and thanks for the PR. Unfortunately, the fixes that you sent are based on generated code. I needed to close the PR and I'm working to fix this in the code generator. I'll update shortly, thanks again for your patience.

[AJenbo]

@ezimuel it would probably be good if you documented that the code is generated, and even better if you could point to the generator so that we can open PRs against it to fix things in the right place.

[ezimuel]

@AJenbo unfortunately, the code generator is not public. All the generated files have a @generated tag (e.g. here in Indices) that I proposed in 2021 as PSR-19 standard. We can definitely improve also the documentation, mentioning this @generated tag. Maybe, we can also add a github action that informs if you changed a generated file.

[AnnaNtagiou]

@ezimuel Thanks for the reply. I will be waiting for the fix then

[ezimuel]

I added a CONTRIBUTING guide where I explained the @generated tag. I hope this will help with future contributions. Thanks for your feedback.

[ezimuel]

I just sent this PR #1439 to fix the issue

[ezimuel]

Just released v8.17.1 with the fix in the PR #1442

[AJenbo]

Thanks

[AnnaNtagiou]

Thanks!