How truelayer/truelayer-php works
Project Type and Purpose
• This is a PHP SDK / client library for the TrueLayer API.
• It’s an open-source tool that provides a type-safe facade over TrueLayer’s REST endpoints (payments, refunds, payouts, merchant accounts, signup-plus, webhooks).
• Key indicators:
• src/Client.php and src/Webhook.php expose the public API
• src/Services/Api and src/Services/ApiClient handle HTTP calls
• src/Entities, src/Interfaces and src/Factories implement a domain model + builder factories
• README describes usage scenarios (creating payments, refunds, webhooks)
File Structure Analysis
• Top-level src contains:
• Client entry point (Client.php, Settings.php)
• Domain model: Entities/Interfaces for AccountIdentifier, Payment, Payout, Webhook, etc.
• Factories: ApiFactory, ClientFactory, EntityFactory, WebhookFactory
• Services:
– Api (AccessTokenApi, PaymentsApi, …)
– ApiClient (core HTTP request builder + Decorators for signing, idempotency, retry, TL-Agent header)
– Auth (AccessToken service)
– Configuration (ClientConfig, WebhookConfig)
– Util (Arr, Str, Encryption, Retry, FromGlobals)
– Webhooks (JwksManager, Webhook, WebhookHandlerManager, WebhookVerifier)
• Patterns:
• Builder / Fluent configurator (Client::configure())
• Factory pattern for Entities and API clients
• Decorator pattern around ApiClient for cross-cutting concerns
• Layered separation: Public API → Services / Factories → Domain Entities → HTTP layer
• Config and lang directories hold config files and translations (validation messages)
Key Architectural Insights from README
• Public façade handles: authentication (with caching), signing, idempotency, retry logic, typed resource builders
• Dependencies: any PSR-18 HTTP client, PSR-16 cache
• Webhook subsystem verifies signatures via JWKs fetched from TrueLayer
• Clear labels for each component (e.g., “PaymentsApi”, “ApiClient”, “SigningDecorator”)
• from Client façade to API calls
• from ApiClient through Decorators to external TrueLayer endpoint
• from Webhook endpoint to WebhookVerifier to handlers
• Public façade (blue)
• Application services + factories (green)
• Domain entities (yellow)
• Infrastructure adapters (gray)
• External systems (orange)