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, payouts, 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).

marcohefti / request-network-api-client

Maintainers

Details