jooservices/client

A robust, layered HTTP Client wrapper for JOOservices

1.1.0 2026-03-09 23:15 UTC

Requires

• php: ^8.5
• guzzlehttp/guzzle: ^7.9
• jooservices/dto: ^1.0
• mongodb/laravel-mongodb: ^5.6
• monolog/monolog: ^3.10
• psr/log: ^3.0
• psr/simple-cache: ^3.0
• symfony/options-resolver: ^7.0

Requires (Dev)

• laravel/pint: ^1.18
• mockery/mockery: ^1.6
• phpbench/phpbench: ^1.4
• phpmd/phpmd: ^2.15
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^12.0
• squizlabs/php_codesniffer: ^3.10
• symfony/filesystem: ^7.4
• symfony/var-dumper: ^7.0

MIT

• JOOservices

README

A robust, layered HTTP Client wrapper designed for extensibility, strict typing, and high performance. Built with a "Clean Architecture" approach, decoupling the business logic from the underlying Guzzle transport.

Features

• Strictly Typed: Configuration object (ClientConfig) ensures type safety before requests start.
• Layered Architecture: Adapters (Guzzle) are isolated from Core Logic.
• Resilience: Built-in Retry (Backoff/Jitter) and Circuit Breaker.
• Async & Concurrency: Support for non-blocking requests (getAsync) and Batch Processing.
• Observability: detailed Logging and PSR-16 Caching integration.
• Performance: < 10μs overhead per request.

Installation

composer require jooservices/client

Quick Start

Basic Usage

Use the ClientBuilder to create an instance.

use JOOservices\Client\Client\ClientBuilder;

$client = ClientBuilder::create()
    ->withBaseUri('https://api.example.com')
    ->withTimeout(5)
    ->withHeader('Authorization', 'Bearer token')
    ->build();

$response = $client->get('/users/1');

echo $response->status(); // 200
print_r($response->json()); // ['id' => 1, ...]

Async Requests & Batching

// Single Async Request
$promise = $client->getAsync('/users/1');
$response = $promise->wait();

// Batch Processing (Concurrent)
$results = $client->batch([
    'user1' => fn() => $client->getAsync('/users/1'),
    'user2' => fn() => $client->getAsync('/users/2'),
]);

print_r($results['user1']->json());

Advanced Configuration

Resilience (Retry & Circuit Breaker)

use JOOservices\Client\Resilience\RetryConfig;
use JOOservices\Client\Resilience\CircuitBreakerConfig;

$client = ClientBuilder::create()
    ->withRetry(new RetryConfig(
        maxAttempts: 3,
        baseDelayMs: 100
    ))
    ->withCircuitBreaker(new CircuitBreakerConfig(
        failureThreshold: 5,
        recoveryTimeoutMs: 10000
    ))
    ->build();

Logging & Caching

use JOOservices\Client\Logging\MonologFactory;
use JOOservices\Client\Cache\FilesystemCache;

$logger = MonologFactory::createDaily('my-app', __DIR__ . '/logs');
$cache = new FilesystemCache(__DIR__ . '/cache');

$client = ClientBuilder::create()
    ->withLogger($logger, logBodies: true)
    ->withCache($cache, defaultTtl: 3600)
    ->build();

Quality Assurance

We use strict static analysis and testing.

composer quality

This runs:

• Pint: Code Style Fixer
• PHPStan: Static Analysis (Level 9)
• PHPUnit: Unit, Feature & Integration Tests (with 98% coverage gate)
• PHPBench: Performance Analysis

Docker Development

If PHP is not installed locally, run everything in Docker.

docker compose up -d --build mongodb
docker compose run --rm php composer install
docker compose run --rm php composer test

For live network integration tests (real sites), run:

docker compose run --rm -e JOOCLIENT_RUN_LIVE_NETWORK_TESTS=1 php \
    vendor/bin/phpunit tests/Feature/Logging/RealSiteIpLoggingTest.php

This test hits:

• https://httpbin.org/get
• https://example.com
• https://google.com

Contributing

See CONTRIBUTING.md for details.