Improve static type inference for API client `send` method with strongly typed requests

[jnoordsij]

In the v3 major release strongly typed request objects were introduced; see also https://github.com/mollie/mollie-api-php/blob/master/UPGRADING.md#typed-request-objects. Where these are a great addition for writing safer code, they unfortunately result in less strict inferred types when doing static analysis, as the return type of send is simply mixed:

mollie-api-php/src/Traits/SendsRequests.php

Lines 40 to 43 in 6feb9bb

	/**
	* @return mixed
	*/
	public function send(Request $request)

In #789 (comment) I read:

I'm planning to add more improvements on the returned resources over the coming versions.

If you have an idea on how we can improve the returned typing without adding a dedicated method on the request itself, please let me know!

I'm not sure if there are any ongoing efforts on this account, but wanted to create this issue mostly as an encouraging nod that such attempts would be greatly appreciated and as a way to track possible updates.

As for ideas, there's two roads forward I can see that come to my mind:

• leverage distinct methods, similar to how the 'old' interfaces worked, however this is seemingly (per V3 typing #789 (comment) again) not the intended way to go
• introduce a generic type TResponse to the ResourceHydratableRequest; in theory (I've not really attempted much of this), I think something along the lines of the following signature on send could then be used:

    /**
     * @template TRequest of ResourceHydratableRequest
     * @template TResponse
     * 
     * @param TRequest
     * @return TRequest is ResourceHydratableRequest<TResponse> ? TResponse : mixed
     */
    public function send(Request $request)

[Naoray]

Hi @jnoordsij,

thank you for your encouragement. I am currently looking into which features to include in a new version of this package. Will definitely consider this approach and report back!