Skip to content

CLAUDE.md

Latest commit

 

History

History
104 lines (74 loc) · 3.67 KB

CLAUDE.md

File metadata and controls

104 lines (74 loc) · 3.67 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

PHP SDK for the Mollie API (https://docs.mollie.com/reference/overview). Supports PHP 7.4–8.4. Namespace: Mollie\Api.

Commands

# Run all tests (parallel)
composer test                    # or: vendor/bin/paratest --verbose

# Run a single test file
vendor/bin/phpunit tests/Path/To/TestFile.php

# Run a single test method
vendor/bin/phpunit --filter testMethodName tests/Path/To/TestFile.php

# Static analysis (level 5)
vendor/bin/phpstan

# Install dependencies
composer install

Architecture

This SDK has two interaction layers:

1. Modern Request Layer (preferred for new code)

Send typed request objects directly via $client->send(). Inspired by SaloonPHP.

src/Http/Requests/       → Typed request classes (CreatePaymentRequest, GetPaymentRequest, etc.)
src/Http/Request.php     → Abstract base class (ResourceHydratableRequest, CollectionHydratableRequest)
src/Http/PendingRequest  → Orchestrates the request pipeline
src/Http/Middleware/      → Request/response middleware (auth, hydration, error handling, idempotency)
src/Http/Adapter/        → HTTP client adapters (Guzzle, cURL, PSR-18)

2. Legacy EndpointCollection Layer

Fluent interface via magic properties on the client ($client->payments->create(...)). Delegates to the modern request layer via Factories.

src/EndpointCollection/  → Fluent endpoint classes (PaymentEndpointCollection, etc.)
src/Factories/           → Convert unstructured array data → typed Request objects

The HasEndpoints trait provides __get() magic to lazy-load endpoint collections.

Supporting Code

src/MollieApiClient.php  → Main entry point, composed via traits
src/Resources/           → Response models (Payment, Customer, etc.) with convenience methods
src/Contracts/           → Interfaces for extensibility (Connector, HttpAdapterContract, etc.)
src/Traits/              → Shared behavior (HandlesAuthentication, SendsRequests, HasMiddleware, etc.)
src/Types/               → Constants and enums (PaymentStatus, PaymentMethod, etc.)
src/Exceptions/          → Custom exception hierarchy (ApiException → specific subtypes)
src/Http/Data/           → Value objects (Money, Address, OrderLine, etc.)
src/Fake/                → Testing utilities (MockMollieClient, MockResponse)

Request Execution Flow

MollieApiClient::send(Request)
  → PendingRequest applies handlers (user-agent, headers, auth, testmode)
  → Middleware pipeline (onRequest)
  → HttpAdapter sends HTTP request
  → Middleware pipeline (onResponse: error conversion, hydration)
  → Returns hydrated Resource object

Adding a New Endpoint

  1. Create Request class in src/Http/Requests/ (extend ResourceHydratableRequest or CollectionHydratableRequest)
  2. Create Factory class in src/Factories/ to bridge array input → typed request
  3. Add method to the appropriate EndpointCollection in src/EndpointCollection/
  4. Add Resource class in src/Resources/ if it's a new resource type

Testing Pattern

Use the built-in mock client — no real HTTP calls needed:

$client = MollieApiClient::fake([
    GetPaymentRequest::class => MockResponse::ok(['resource' => 'payment', ...]),
]);

$payment = $client->send(new GetPaymentRequest('tr_xxx'));

$client->assertSent(GetPaymentRequest::class);

Test fixtures live in tests/Fixtures/. Documentation and code examples are in docs/.

CI

  • Tests: PHPUnit via Paratest across PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4
  • Static analysis: PHPStan level 5 (with baseline)
  • Code style: PHP CS Fixer