gautammkgarg/psr-for-wordpress

PSR implementations for WordPress that bridge PSR interfaces to native WordPress APIs. PSR-18 HTTP Client (wp_remote_request) and PSR-16 Simple Cache (transients / wp_cache) with companion key pattern.

v0.3 2026-05-30 07:46 UTC

Requires

• php: >=8.1
• nyholm/psr7: ^1.5
• psr/http-client: ^1.0
• psr/http-factory: ^1.0
• psr/http-message: ^1.1 || ^2.0
• psr/simple-cache: ^3.0

Requires (Dev)

• cache/integration-tests: dev-master
• php-http/client-integration-tests: ^4.0
• php-http/discovery: ^1.14
• php-http/httplug: ^2.0
• phpunit/phpunit: ^10.0 || ^11.0
• rmccue/requests: ^2.0

Provides

• psr/http-client-implementation: 1.0
• psr/simple-cache-implementation: 1.0

GPL-3.0-or-later

• Gautam Garg

• http
• cache
• wordpress
• requests
• psr
• wp
• http-client
• simple-cache
• object-cache
• psr-16
• psr-18
• transients

README

A PSR implementation library for WordPress that bridges PSR interfaces to WordPress's native APIs. Currently implements:

• PSR-18 HTTP Client — uses wp_remote_request() with fallback to WpOrg\Requests
• PSR-16 Simple Cache — uses set_transient() / wp_cache_set() with the companion key pattern

Why This Package Exists

WordPress bundles its own HTTP transport (wp_remote_request). It handles proxies, SSL, redirects, and other platform-specific concerns automatically.

Libraries like omnipay/common, and others use php-http/discovery to auto-detect a PSR-18 HTTP client. Without this package, they'd pull in Guzzle — adding a heavy dependency and bypassing WordPress's HTTP layer.

This package gives you:

• WordPress HTTP API as the transport inside WordPress
• WpOrg\Requests as fallback outside WordPress
• Zero-argument constructor for php-http/discovery auto-detection
• PSR-18 compliance — HTTP Client wherever ClientInterface is expected
• PSR-16 compliance — Simple Cache wherever CacheInterface is expected

Requirements

• PHP 8.1+
• rmccue/requests: ^2.0
• WordPress 5.0+ when used inside WordPress

Installation

composer require gautammkgarg/psr-for-wordpress

Usage

Auto-discovery (Omnipay, php-http/discovery)

Add to your project's composer.json:

{
    "extra": {
        "discovery": {
            "psr/http-client-implementation": "GautamMKGarg\\PsrForWordPress\\Http\\Psr18Client"
        }
    }
}

That's it. php-http/discovery will find Psr18Client automatically when any library calls Psr18ClientDiscovery::find().

Manual Usage

use GautamMKGarg\PsrForWordPress\Http\Psr18Client;
use Nyholm\Psr7\Factory\Psr17Factory;

$client = new Psr18Client();
$factory = new Psr17Factory();

$request = $factory->createRequest('GET', 'https://api.example.com/endpoint');
$response = $client->sendRequest($request);

echo $response->getStatusCode();    // 200
echo (string) $response->getBody(); // JSON response body

Custom Options

$client = new Psr18Client([
    'timeout'     => 30,   // seconds (default: 10)
    'redirection' => 0,    // disable redirects
    'sslverify'   => false, // disable SSL verification (not recommended in production)
]);

Global Timeout Override via WordPress Filter

Instead of manually configuring the client, use WordPress's native hook:

add_filter('http_request_args', function(array $args, string $url): array {
    // Increase timeout for payment gateway API calls
    $args['timeout'] = 30;
    return $args;
}, 10, 2);

How It Works

Inside WordPress

When wp_remote_request() is available, the client calls it directly:

PSR-7 Request → Build WP args → wp_remote_request() → Parse WP response → PSR-7 Response
                                        ↓ on WP_Error
                               throw NetworkException

Outside WordPress

Install dependency using composer require rmccue/requests.

When wp_remote_request() is not available:

PSR-7 Request → Build Requests options → WpOrg\Requests\Requests::request() → Parse response → PSR-7 Response
                                                    ↓ on exception
                                          throw NetworkException

Exceptions

Exception	Interface	When Thrown
NetworkException	Psr\Http\Client\NetworkExceptionInterface	WP_Error or transport exception
RequestException	Psr\Http\Client\RequestExceptionInterface	Invalid request (e.g., empty URI)

Both exceptions implement getRequest() to retrieve the original PSR-7 request.

PSR-16 Simple Cache

Two adapters are provided, both implementing Psr\SimpleCache\CacheInterface:

Adapter	WordPress Backend	Persistence	Best For
WpTransientsCache	set_transient, get_transient	Always persistent (DB by default, Redis if plugin)	Tokens, API responses, settings that must survive requests
WpObjectCache	wp_cache_set, wp_cache_get	Only with Redis/Memcached plugin	Query results, computed values reused within request

Usage

use GautamMKGarg\PsrForWordPress\Cache\WpTransientsCache;
use GautamMKGarg\PsrForWordPress\Cache\WpObjectCache;

// Persistent cache (survives requests)
$cache = new WpTransientsCache();

// In-memory cache (request-only unless Redis plugin)
$cache = new WpObjectCache('myplugin');

$cache->set('users', $users, 3600); // seconds
$users = $cache->get('users');
$cache->delete('users');

Companion Key Pattern — Storing false Correctly

WordPress returns false for both "key not found" and "value is false". We solve this by creating a companion key ({key}__found_psr16__) only when false is stored. Non-false values are stored raw — so native get_transient() can read them without mangling.

Feature	This Package
False handling	Companion key (only for false)
Native WordPress interop for non-false values	✅ Yes — values stored raw
Performance overhead	Near-zero (companion keys created only for false values)

Guzzle vs This Package — Timeout Difference

Guzzle uses 0 as the default timeout, meaning no timeout at all. That's why Guzzle never fails for slow APIs. This package defaults to 10 seconds — which is more appropriate for production WordPress sites than WordPress's built-in 5-second default. Increase it as needed.

License

GPL-3.0-or-later. See LICENSE for full text.