mollie/mollie-api-php v4.0.0

on GitHub

The first stable v4 release modernizes Mollie API PHP for PHP 8.2 and newer. It includes the changes from all three v4 betas and the v3 API additions through v3.14.0. If you are upgrading an application from v3, read the v3 to v4 upgrade guide before changing the dependency.

Before upgrading from v3

• Move to PHP 8.2+. PHP 7.4, 8.0, and 8.1 are no longer supported. CI covers PHP 8.2, 8.3, and 8.4.
• Replace type constants with enum cases. API value sets under Mollie\Api\Types are string-backed enums: for example, PaymentStatus::PAID becomes PaymentStatus::Paid. Resource status and method fields use enum cases while preserving unknown API values as strings. The GetAllConstants trait is gone; use cases() or the retained all() methods on the three enums documented in the upgrade guide.
• Review typed and readonly objects. Resource fields that previously held stdClass can now hold typed value objects such as Money. Familiar property reads such as $payment->amount->value still work. Rebuild a readonly value object when you need to change it. Check positional constructor calls after property promotion; named arguments retain their names. A typed property with no default stays uninitialized when a response omits that field; guard reads from partial responses.
• Review extension points. onResponse() always receives the raw Response; use onResolved() for middleware that needs a hydrated resource or collection. Subclasses that changed the protected static $endpoints map should override the ENDPOINTS constant. Custom retry strategies should follow the updated exception contract. Typed method arguments follow the strict_types setting of the calling file.

What v4 adds

• Better type information. MollieApiClient::send() infers the concrete resource from its request class in static analysis. ResourceHydratableRequest::hydrateInto() and wrapInto() also preserve inference when retargeting or wrapping a response.
• Money construction. Money::of('EUR')->minorUnits(1099) and Money::of('EUR')->fromString('10.99') account for currency exponents. Money supports macros for custom factories.
• Retries and errors. ExponentialRetryStrategy supports jitter and HTTP 429 Retry-After, and Response::rateLimit() reads rate limit headers. ValidationException exposes field errors; TooManyRequestsException exposes the retry delay. Exception messages no longer include API tokens or request bodies.
• Webhooks and testing. Four profile webhook events cover created, verified, blocked, and deleted profiles. Snapshot hydration carries the webhook origin into typed resources. MockResponse has typed factories for payments, customers, subscriptions, mandates, refunds, and other common resources.
• v3 feature parity. Payouts, terminal pairing codes, payment link applicationFee, response origins, and webhook snapshots are present in v4. PaymentMethod::Wero carries the v3.14.0 payment method addition into the enum.

Fixes incorporated during the betas

• Nullable enum fields now hydrate known values to enum cases; unknown values remain strings. If you compared a beta.2 field to a raw string, compare with the case or its ->value, or use Utility::equals().
• PaymentMethodStatus and TerminalPairingCodeStatus are enums. A method that was never requested has Method::$status === null; there is no PaymentMethodStatus::NOT_REQUESTED case.
• Resource nullability was aligned with the API contract for fields on Organization, Capability, Balance, Terminal, SalesInvoice, and other resources. Payment::$statusReason is now a readonly PaymentStatusReason value object.
• Request serialization preserves legitimate 0, "0", and 0.0 values. Idempotency keys are cleared when a request is assembled, including failure paths, and test mode is resolved consistently for each request.

The changelog has the detailed beta changes. Compare v3.14.0 with v4.0.0 for the full major upgrade, or beta.3 with v4.0.0 for the final changes. The full test suite passed in CI on PHP 8.2, 8.3, and 8.4; PHPStan also passed.