feat: add phpstan method annotations

[stobrien89]

Issue #, if available:
#3309

Description of changes:
Adds phpstan-method annotations to service client methods for better static analysis support.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[andrew-demb]

PHPStan seems to be working properly, but PHPStorm doesn't understand multiline array type declarations in "@phpstan-method" tags and adds a lot of inspection errors to the file. But it will affect only package development, not consumers.

Overall, the original goal was reached successfully.

[andrew-demb]

... relevant PhpStorm issues that I've found:

• https://youtrack.jetbrains.com/issue/WI-78397/PHPStorm-creates-an-Expected-variable-for-PHPDoc-method-word-wraps
• https://youtrack.jetbrains.com/issue/WI-75416/Support-multiline-psalm-array-declaration-with-comments

[Ocramius]

Note: this is where I ran into severe issues with AWS, passing completely ignored arguments to the API, and almost destroying production resources

[stobrien89]

You're right, this is the false-negative we accept with the unsealed marker. Sealing here would catch Buckt → Bucket, but it would also flag the common pattern of dynamically-built array<string, mixed> values passed as $args (request context, tracing metadata) where PHPStan/Psalm can't prove key set membership at the call site. What do you think about sealing top-level members, but leaving nested members unsealed?

[stobrien89]

@Ocramius bumping the above ^

[Ocramius]

Sorry, I was on vacation

but it would also flag the common pattern of dynamically-built array<string, mixed>

For this, tools like PHPStan/Psalm/Mago/Phan have the concept of a "baseline", which is a sufficient approach to catch this sort of detail.

What do you think about sealing top-level members, but leaving nested members unsealed?

I think it wouldn't be added value here.

People that use PHPStan/Psalm/etc. can ignore these issues themselves, as an opt-in, either via a pattern or via a baseline.

Reporting these problems is more valuable than taking an upfront decision to suppress them for consumers.