mollie/mollie-api-php v4.0.0-beta.3

on PHP Packagist

Added

• PaymentStatusReason value object (code, message); Payment::$statusReason is now ?PaymentStatusReason instead of an untyped stdClass. ->code/->message reads and json_encode() keep working; update instanceof stdClass checks, any mutation (the object is readonly), and array-only consumers by calling toArray().
• PaymentMethod cases Billink, Bizum, Mobilepay, Vipps, and Voucher. Existing cases are unchanged; the enum documents known SDK vocabulary, not an allow-list.
• CapabilityStatus::Unrequested and Capability::isUnrequested().
• Balance::$pendingAmount (?Money), the amount field the Balance API returns.
• ResourceHydratableRequest::hydrateInto() and ::wrapInto(). Both carry @phpstan-self-out and @psalm-this-out annotations that PHPStan honors so send() infers the re-targeted class or wrapper. setHydratableResource() is unchanged but cannot narrow the type.

Changed

• PaymentMethodStatus and TerminalPairingCodeStatus are string-backed enums. Their SCREAMING_SNAKE constants are gone, the same migration the other value sets took in beta.1. PaymentMethodStatus::NOT_REQUESTED has no case: Method::$status is null for a method that was never requested. TerminalPairingCode::$status is typed TerminalPairingCodeStatus|string.
• Method::$status no longer has a null default. The API marks the field required (nullable), so an omitted field now stays uninitialized instead of reading as "not requested"; an explicit null still means the method was never requested.

Fixed

• Nullable enum unions now hydrate to enum cases. Enum|string|null properties resolved as mixed and kept the raw API string. Affected: Payment::$method, Payment::$sequenceType, Refund::$status, Mandate::$status, Settlement::$status, Profile::$status, CurrentProfile::$status, Invoice::$status, Subscription::$status, and, after its enum migration, Method::$status. Code written against beta.2 that compares these to raw strings must compare with the case or ->value, or use Utility::equals(), which accepts the case or raw value on either side. MandateCollection::whereStatus() accepts a MandateStatus case or raw string. Unknown values still arrive as strings; null is unchanged. Profile::$categoryCode (int|string|null) keeps the delivered scalar type.
• Organization::$address, $registrationNumber, and $vatNumber are nullable with a null default, matching the API contract. Beta.2 threw TypeError on null and Error on an omitted field. Organization::$locale stays a required, non-null string.
• Capability::$statusReason accepts null; Capability::$organizationId is nullable with a null default because the field is not part of the Capability response.
• Balance no longer fails on a conformant response: $incomingAmount and $outgoingAmount (both deprecated because they are not part of the Balance response), $transferFrequency, and $transferThreshold are nullable with a null default.
• Fields the API contract marks nullable or optional no longer throw TypeError on null or Error when omitted: Terminal::$brand, $model, $serialNumber (?string); Terminal::$timezone, $locale (?string = null); Capture::$amount (?Money); PaymentLink::$profileId (?string); Webhook::$profileId (?string); Partner::$partnerType (?string); Partner::$partnerContractUpdateAvailable (?bool = null); BalanceTransaction::$deductions (?Money = null); BalanceTransaction::$mode (?string = null); Route::$releaseDate (?string = null); ConnectBalanceTransfer::$category (?string = null); SalesInvoice::$paymentTerm, $currency, $webhookUrl (?string = null); and SalesInvoice::$lines (?array = null). Other SalesInvoice fields are unchanged pending further contract review.
• UPGRADING.md no longer prints a Types class count and now documents enum reflection, rebuilding readonly value objects, uninitialized typed properties, wrapped-request inference, and caller-side strict_types behavior.

For contributors

• A test asserts every file under src/Types/ is a backed enum except the query helpers and Types\Method.
• A PHPStan fixture under tests/ asserts the inferred send() types on every analysis run.