mollie / mollie-api-php

Mollie API client for PHP
http://www.mollie.com
BSD 2-Clause "Simplified" License
552 stars 191 forks source link

V3 #727

Open Naoray opened 4 months ago

Naoray commented 4 months ago

Upgrading

From v2 to v3

Removed unused Collections

This change should not have any impact on your code, but if you have a type hint for any of the following classes, make sure to remove it

Removed deprecations

The following was removed due to a deprecation

Changelog

Type cast embeded Resources

In previous versions resources requested via embed param on requests like get-payment were not casted into their respective collection or resource classes. Starting with this version all embeded resources are typecasted.

$payment = $mollie->payments->get('...', ['embed' => ['refunds']]);

$this->assertInstanceOf(RefundCollection::class, $payment->_embedded->refunds);

Added CaptureMode

A new Mollie\Api\Types\CaptureMode class which can be used when using on the create-payment request (s. captureMode) when using the capture feature.

PSR-18 Support

We added a new HTTP-adapter which supports PSR-18. The following example demonstrates on how to use the new adapter.

Note: The example uses nyholm/psr7 to get all necessary factories required. You can use the same factories by running composer require nyholm/psr7.

use Mollie\Api\MollieApiClient;
use Psr\Http\Client\ClientInterface;
use Nyholm\Psr7\Factory\Psr17Factory;
use GuzzleHttp\Client as GuzzleClient;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\StreamFactoryInterface;
use Mollie\Api\HttpAdapter\PSR18MollieHttpAdapter;

// Create instances of the required classes
$httpClient = new GuzzleClient(); // Instance of ClientInterface
$requestFactory = new Psr17Factory(); // Instance of RequestFactoryInterface
$streamFactory = new Psr17Factory(); // Instance of StreamFactoryInterface

// Instantiate the PSR18MollieHttpAdapter
$mollieHttpAdapter = new PSR18MollieHttpAdapter(
  $httpClient,
  $requestFactory,
  $streamFactory
);

$client = new MollieApiClient($mollieHttpAdapter);

$client->setApiKey("test_qM2fCcTADeP6m87E5yFbnzfcUGpEDb");
$client->payments->page();

Added Collection Methods

Two new collection methods were added which can be used to simplify interacting with collection resources.

Testmode is automatically removed..

..If an API key is used as authentication.

Say Goodby to the annoying [...]. Try switching live / test API keys.

Requests, Payloads and Queries

The new version can be used as before without any changes to the codebase (except the few mentioned above). The underlying codebase was changed drastically to allow a few improvements. There are now 3 different ways to interact with the client.

The old way

Just as you used to... Pass in arrays of data and receive your Resource/ResourceCollection.

// old way of creating a payment
$payment = $mollie->payments->create([
    "amount" => [
        "currency" => "EUR",
        "value" => "10.00"
    ],
    "description" => "My first API payment",
    "redirectUrl" => "https://webshop.example.org/order/12345/",
    "webhookUrl"  => "https://webshop.example.org/mollie-webhook/",
]);

Slightly improved

With this approach you can use new Objects and therefore actually know what data is required to pass into the method, but you can still using the old way of calling the request.

// improved
use Mollie\Api\Http\Payload\Money;
use Mollie\Api\Http\Payload\CreatePaymentPayload;

$payload = new CreatePaymentPayload(
    description: 'My first API payment',
    amount: new Money('EUR', '10.00'),
    redirectUrl: 'https://webshop.example.org/order/12345/',
    webhookUrl: 'https://webshop.example.org/mollie-webhook/'
);

$payment = $mollie->payments->create($payload);

This is the way!

Finally, the new way of interacting with the client:

  1. create your payload
  2. pass it into your request
  3. send it
  4. inspect response 4b. receive your Resoure/ResourceCollection
// newest ;-)
use Mollie\Api\Http\Payload\Money;
use Mollie\Api\Http\Payload\CreatePaymentPayload;
use Mollie\Api\Http\Requests\CreatePaymentRequest;

$payload = new CreatePaymentPayload(
    description: 'My first API payment',
    amount: new Money('EUR', '10.00'),
    redirectUrl: 'https://webshop.example.org/order/12345/',
    webhookUrl: 'https://webshop.example.org/mollie-webhook/'
);

$response = $mollie->send($payload);

$payment = $response->toResource();
$jsonData = $response->json();
$status = $response->status();

With this you get a Response and can also inspect its status, body or any other payload. If you want to use the $client->send() method but don't want to call the ->toResource() method to receive your Resource, you can simply call MollieApiClient::shouldAutoHydrate().


Some Context...

..on how the new request cycle works

Screenshot 2024-09-09 at 11 03 17