README

PHP client for the Request Network hosted REST API. It mirrors the TypeScript client's surface so WooCommerce and other PHP runtimes can talk to Request without a Node bridge.

Installation

Install via Composer:

composer require marcohefti/request-network-api-client

Quick start

Minimal example using the static factory:

use RequestSuite\RequestPhpClient\RequestClient;

$client = RequestClient::create([
    'apiKey' => $_ENV['REQUEST_API_KEY'],
]);

// Create a new payment request
$request = $client->requests()->create([
    'amount' => '100',
    'invoiceCurrency' => 'USD',
    'paymentCurrency' => 'ETH-sepolia-sepolia',
    'payee' => '0x0000000000000000000000000000000000000000',
    'reference' => 'order-123',
]);

$requestId = $request['requestId'] ?? null;

// Search for payments
$payments = $client->payments()->search(['requestId' => $requestId]);

Why Use This Client?

Instead of manually building HTTP requests and handling errors, this client provides:

• Type Safety: Strict type hints and PHPDoc throughout (PHPStan level 7 clean)
• Automatic Retries: Exponential backoff with jitter for transient failures
• Schema Validation: Runtime validation against OpenAPI specs (optional)
• Webhook Security: Timing-safe signature verification with secret rotation support
• Error Handling: Rich exception hierarchy with correlation IDs and retry headers
• Logging: Automatic credential redaction in PSR-3 compatible logs
• Testing: Built-in FakeHttpAdapter for easy unit testing

Before vs After: See docs/BEFORE-AFTER.md for side-by-side code comparisons showing how this client simplifies common Request Network API operations.

Documentation

• Architecture - System design and internals
• Testing - Test strategy, coverage, and validation
• HTTP Client - HTTP adapter, retry behavior, error handling
• Webhooks - Signature verification, middleware, event handlers
• Before/After - Code comparisons showing client benefits
• Troubleshooting - Common issues and solutions
• Publishing - Release checklist

What this client covers

• PHP-first RequestClient with facades for requests (including request listing), payouts, payments, secure payments, payer/compliance (v1+v2), client IDs, currencies (v1+v2), and legacy pay.
• Shared HTTP pipeline with retry, logging, and runtime validation driven by the synced OpenAPI spec.
• Webhook utilities: signature verifier, typed event objects, parser, dispatcher, PSR‑15 middleware, and testing helpers that mirror the TypeScript webhook module.
• Env‑based factory for backend and WooCommerce usage, with PSR‑4 autoloading under RequestSuite\RequestPhpClient.

Compatibility

• PHP: >= 8.2
• Frameworks: Designed for PSR‑15 stacks (e.g., WooCommerce, Laravel/Symfony via adapters)
• HTTP Clients: Any PSR-18 compatible client (Guzzle, Symfony HttpClient, etc.) or built-in cURL adapter

Development

Common commands:

• composer test – PHPUnit suites.
• composer stan – PHPStan analysis.
• composer cs / composer lint – coding standards (if configured).
• composer update:spec – sync OpenAPI + webhook fixtures from the contracts package.

See docs/TESTING.md and docs/ARCHITECTURE.md for the full testing strategy, spec sync flow, and domain layout.

Webhooks

The webhook module provides secure signature verification, typed event objects, and PSR-15 middleware:

use RequestSuite\RequestPhpClient\Webhooks\Events\PaymentConfirmedEvent;
use RequestSuite\RequestPhpClient\Webhooks\WebhookParser;

$parser = new WebhookParser();
$parsed = $parser->parse([
    'rawBody' => (string) $request->getBody(),
    'headers' => $request,
    'secret' => [$_ENV['REQUEST_WEBHOOK_SECRET']],
]);

if ($parsed->event() instanceof PaymentConfirmedEvent) {
    $data = $parsed->event()->data();
    $requestId = $data->string('requestId');
    // Handle payment confirmation
}

Features:

• Timing-safe signature verification with secret rotation support
• Typed event classes for all webhook types
• PSR-15 middleware for framework integration
• Event dispatcher for handler registration
• Testing helpers for unit tests

See docs/WEBHOOKS.md and examples/webhook-handler-middleware.php for complete webhook integration examples.

Logging & redaction

Pass either a callable (string $event, array $context) => void or a PSR-3 LoggerInterface via RequestClient::create(['logger' => ...]) to receive lifecycle events (request:start, request:response, request:error). When you supply a PSR-3 logger, the client automatically wraps it with Logging\PsrLoggerAdapter, which redacts sensitive fields (API keys, Authorization headers, webhook signatures) via Logging\Redactor before handing context to your logger:

use Monolog\Handler\StreamHandler;
use Monolog\Logger;
use RequestSuite\RequestPhpClient\RequestClient;

$logger = new Logger('request-network-api-client');
$logger->pushHandler(new StreamHandler('php://stdout'));

$client = RequestClient::create([
    'apiKey' => $_ENV['REQUEST_API_KEY'],
    'logger' => $logger,
    'logLevel' => 'info',
]);

WebhookMiddleware shares the same logger plumbing and emits webhook:verified, webhook:dispatched, and webhook:error events so you can trace webhook flows without leaking secrets.

Testing harness

Unit tests (and downstream consumers) can inject the built-in Testing\FakeHttpAdapter to queue responses and assert requests without rolling bespoke stubs:

use RequestSuite\RequestPhpClient\Testing\FakeHttpAdapter;

$fake = new FakeHttpAdapter([
    FakeHttpAdapter::jsonResponse(['status' => 'ok']),
]);

$client = RequestClient::create([
    'apiKey' => 'rk_test',
    'httpAdapter' => $fake,
]);

$client->requests()->create([...]);
$fake->assertSent(static fn ($pending) => $pending->method() === 'POST');

See docs/TESTING.md for the full harness (coverage guard, parity scripts, integration plans).

Composer scripts

• composer test - runs PHPUnit using phpunit.xml.dist.
• composer stan - runs PHPStan static analysis (level 7) using phpstan.neon.dist.
• composer coverage - prints PHPUnit coverage summary to the terminal.
• composer cs - runs PHPCS with PSR-12 + Slevomat rules.
• composer cs:fix - auto-fixes code style issues where possible.
• composer md - runs PHPMD (codesize/design/unusedcode) with configured thresholds.
• composer cpd - runs PHPCPD (copy/paste detection).
• composer deps:rules - runs PHPStan dependency rules (architecture contracts).

These are also invoked from the workspace validator (see root scripts/validate.sh).