Skip to content
Quiet Social

Testing and transports

This documentation is translated from French. Should the two versions differ, the French version prevails.

The SDK sends every request through a transport: CurlTransport by default, FakeTransport in your tests, or a class of your own. This page shows how to test an integration without touching the network, and how to adjust or replace the transport.

FakeTransport

QuietSocial\Sdk\Testing\FakeTransport answers with programmed responses and records every request. A request with nothing left to answer it fails the test instead of reaching the network.

use QuietSocial\Sdk\Client;
use QuietSocial\Sdk\Http\Request;
use QuietSocial\Sdk\Post;
use QuietSocial\Sdk\Testing\FakeTransport;

$transport = (new FakeTransport)
    ->push(200, ['data' => [['id' => 'dst_1', 'network' => 'linkedin', 'name' => 'Example', 'can_publish' => true]]])
    ->push(201, ['data' => ['id' => 'pub_1', 'status' => 'scheduled']]);

$client = new Client('qsc_test', 'qss_test', transport: $transport);

$publication = $client->publications()->create(Post::make('Hello')->reference('article:42'), to: ['linkedin']);

$transport->assertSentCount(2); // GET /destinations, then POST /publications
$transport->assertSent(fn (Request $request): bool => $request->method === 'POST'
    && str_ends_with($request->path(), '/publications')
    && $request->json()['destination_ids'] === ['dst_1']
    && str_starts_with((string) $request->header('Idempotency-Key'), 'article:42:'));

Queued responses are used first, in order; then the callable given to respondUsing(), if any.

Method Use
push(int $status, array|string $body = [], array $headers = []) Queues a response; an array body is sent as JSON.
respondUsing(callable $responder) Answers every request the queue does not cover: fn (Request $request): Response.
requests() Every request sent so far, in order.
assertSent(callable $check) At least one request satisfies the check.
assertSentCount(int $count) Exactly this many requests were sent.
assertNothingSent() No request was sent.

The assertions report through PHPUnit when it is installed, and throw a LogicException otherwise. A Request exposes method, url, path(), query(), header(), json() and, for an upload, part('file').

Simulating a refusal

A refusal is programmed like any response: the SDK translates it exactly as it would translate one from the API.

use QuietSocial\Sdk\Exceptions\RateLimited;

$transport = (new FakeTransport)->push(429, ['message' => 'Too many requests.'], ['Retry-After' => '17']);
$client = new Client('qsc_test', 'qss_test', transport: $transport);

try {
    $client->publications()->find('pub_1');
} catch (RateLimited $limited) {
    $limited->retryAfterSeconds; // 17
}

Images in tests

Prefer Image::fromContents() or Image::existing() to Image::fromUrl(): the address of a URL is checked against DNS before anything reaches the transport, and a local address is refused. An image given by its contents goes out as a POST /media upload, to be programmed like the other responses.

CurlTransport

The default transport uses cURL. It verifies certificates, only speaks HTTP and HTTPS, never follows redirects by itself, and refuses a response larger than its limit while it arrives (a SocialException with the code response_too_large). Its limits are adjustable:

use QuietSocial\Sdk\Http\CurlTransport;

$client = new Client(
    clientId: 'qsc_a1b2c3d4e5f6g7h8i9j0k1l2',
    clientSecret: (string) getenv('QUIET_SOCIAL_SECRET'),
    transport: new CurlTransport(connectTimeout: 5, timeout: 20, maxResponseBytes: 20 * 1024 * 1024),
);

connectTimeout and timeout are in seconds; maxResponseBytes is 20 MiB by default and also applies to downloaded images.

A custom transport

Any class implementing QuietSocial\Sdk\Http\Transport can replace CurlTransport, to add logging or to route requests through your own HTTP client. A transport sends one request and returns the Response, whatever its status: it never turns a 404 or a 500 into an exception, and throws ServiceUnavailable only when no response came back.

use QuietSocial\Sdk\Http\Request;
use QuietSocial\Sdk\Http\Response;
use QuietSocial\Sdk\Http\Transport;

final class LoggingTransport implements Transport
{
    public function __construct(private readonly Transport $inner) {}

    public function send(Request $request): Response
    {
        $response = $this->inner->send($request);

        error_log(sprintf('%s %s: %d', $request->method, parse_url($request->url, PHP_URL_HOST), $response->status));

        return $response;
    }
}

$client = new Client('qsc_…', (string) getenv('QUIET_SOCIAL_SECRET'), transport: new LoggingTransport(new CurlTransport));

A request carries the Authorization header: never log headers as they are. Image downloads also carry two connection hints, pinnedAddress (the address that was checked) and bypassProxy. CurlTransport honours them; a transport of your own that ignores them gives up the protection against DNS rebinding described in Images.