V3 typing

[bobvandevijver]

First of all, thanks for the new release!

I'm confused by the new typing introduced with V3 as it seems to be incomplete. Lets take a look at the following snippet (I will use the create payment endpoint for the rest of this description):

$typedPaymentObject = $mollieApiClient->payments->create([...]); // 2.x
$mixedObject = $mollieApiClient->send(new CreatePaymentRequest(...)); // 3.x

The first one is from V2, where you passed an untyped array of properties, but you did get back a typed object for further processing. The latter one, documented as the new typed method, returns a mixed object where the developer needs to explicitly add an annotation with the returned type. From my view both methods are partially untyped, but you can argue that with the request payload now being typed most the bulk is typed.

The v2 method uses a factory to create the CreatePaymentRequest based on the passed array and forwards it to the connector; wouldn't it be nice to be able to pass the CreatePaymentRequest object directly to that method to be able to get a fully typed interface, like in the following example? This would be a BC-break as the method signatures need to be adjusted.

$typedPaymentObject = $mollieApiClient->payments->create(new CreatePaymentRequest(...));

Or, maybe even better, why not a typed send method to the request object? This can be done with BC-break.

$typedPaymentObject = new CreatePaymentRequest(...)->send($mollieApiClient);

What do you think?

[Naoray]

Hi @bobvandevijver,

Thanks for your feedback!

The v2 endpoint methods were intentionally kept mostly as it was before to give developers a way to upgrade without many adaptations. That's also the reason for the factories to exist at all.

I consider the old approach legacy-based and don't plan to further enhance it. In fact, if it goes according to plan I d like to depreciate the legacy way of calling the endpoints.

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!

[Naoray]

FYI, you can also use the legacy way and pass an array with typed properties

$client->payments->create([
    'amount' => new Money(..)
    // ...
])

[bobvandevijver]

Thanks for the heads up on the possible deprecation of the v2 endpoint methods, good to know.

If you do not want to add a method to the request classes you will need to make strongly typed methods on the API client for each request class that has the correct return type. Other options could be to do something with PHPStan, but depending on your definition that would not be strongly typed...

I'm now also seeing that the request/upgrade documentation does not match the README. The following lines suggest that the Payment object is returned by the send() method

mollie-api-php/docs/requests.md

Lines 38 to 39 in f3143a9

	/** @var \Mollie\Api\Resources\Payment $payment */
	$payment = $mollie->send($createPaymentRequest);

mollie-api-php/UPGRADING.md

Line 64 in f3143a9

$payment = $client->send($request);

mollie-api-php/UPGRADING.md

Line 174 in f3143a9

$payment = $client->send($request);

But the README indicates that a toResource() needs to be called first (and a couple other pages in the documentation), as does the Mandata class.

mollie-api-php/README.md

Lines 63 to 64 in f3143a9

	/** @var Mollie\Api\Resources\Payment $payment */
	$payment = $response->toResource();

mollie-api-php/src/Resources/Mandate.php

Line 95 in f3143a9

->toResource();

[Naoray]

Good catch! That should not be in the readme. I must have missed it.

Initially this was how I set it up: a Response returned from the send method which could be transformed into a Resource class. But since you almost always want the resource, I changed it to always hydrate the response into a resource.

Will fix the readme and the Mandate asap