throttr/sdk

Throttr PHP SDK for ultra-fast rate limiting.

1.0.0 2025-04-28 11:12 UTC

Requires

• php: >=8.1

Requires (Dev)

• phpunit/phpunit: ^12

AGPL-3.0-or-later

README

php client for communicating with a Throttr server over TCP.

The SDK enables sending traffic control requests efficiently, without HTTP, respecting the server's native binary protocol.

Installation

Add the dependency using Composer:

composer require throttr/sdk

Basic Usage

<?php

require 'vendor/autoload.php';

use Throttr\SDK\Service;
use Throttr\SDK\Enum\TTLType;

// Configure your instance with 4 connections ...
$service = new Service('127.0.0.1', 9000, 4);

// Define a consumer ... it can be an IP and port or UUID, whatever ...
$consumerId = "127.0.0.1";

// Define the resource ... it can be a METHOD + URL or UUID, whatever ...
$resourceId = "/api/resource";

// Connect to Throttr
$service->connect();

// Add limit to the registry
$service->insert(
    consumerId: $consumerId,
    resourceId: $resourceId,
    ttl: 3000,
    ttlType: TTLType::MILLISECONDS,
    quota: 5,
    usage: 0
);

// Do you want to know if that was stored?
$response = $service->query(
    consumerId: $consumerId,
    resourceId: $resourceId,
);

printf(
    "Allowed: %s, Remaining: %d, TTL: %dms\n",
    $response->can() ? 'true' : 'false',
    $response->quotaRemaining() ?? 0,
    (int)($response->ttlRemainingSeconds() * 1000)
);

// Do you want to update the quota?
$service->update(
    consumerId: $consumerId,
    resourceId: $resourceId,
    attribute: AttributeType::QUOTA,
    change: ChangeType::DECREASE,
    value: 1
);

// Do you want to know the new value?
$response = $service->query(
    consumerId: $consumerId,
    resourceId: $resourceId,
);

printf(
    "Allowed: %s, Remaining: %d, TTL: %dms\n",
    $response->can() ? 'true' : 'false',
    $response->quotaRemaining() ?? 0,
    (int)($response->ttlRemainingSeconds() * 1000)
);

// Close the connections ...
$service->close();

Technical Notes

• The protocol assumes Little Endian architecture.
• The internal message queue ensures requests are processed sequentially.
• The package is defined to works with protocol 2.0.0 or greatest.

License

Distributed under the GNU Affero General Public License v3.0.