README

A PHP client to call Gradio APIs.

TODO

• HTTP and WS support
• predict
• getConfig
• client options
• hf_token support
• viewApi
• Finish event system
• Add tests

Installation

You can install the package via composer:

composer require sergix44/gradio-client-php

Usage

Basic Usage

use SergiX44\Gradio\Client;

$client = new Client('https://my-special.hf.space');

$result = $client->predict(['arg', 1, 2], apiName: 'myFunction');

$outputs = $result->getOutputs(); // returns array of all outputs
$first = $result->getOutput(0);   // returns a single output by index

Hugging Face Token Authentication

To access private Hugging Face Spaces, pass your HF token:

use SergiX44\Gradio\Client;

$client = new Client('https://my-private.hf.space', hfToken: 'hf_your_token_here');

$result = $client->predict(['hello'], apiName: 'chat');

The token is automatically sent as a Bearer token in the Authorization header on all HTTP and WebSocket requests.

Viewing Available API Endpoints

Use viewApi() to inspect the available API endpoints, their parameters, and return types:

use SergiX44\Gradio\Client;

$client = new Client('https://my-special.hf.space');

$apiInfo = $client->viewApi();

// Returns an array with 'named_endpoints' and 'unnamed_endpoints'
// Each endpoint includes parameter and return type information
print_r($apiInfo);

Client Options

You can pass custom HTTP client options (Guzzle options) to customize the underlying HTTP client:

use SergiX44\Gradio\Client;

$client = new Client('https://my-special.hf.space', httpClientOptions: [
    'timeout' => 30,
    'headers' => [
        'X-Custom-Header' => 'value',
    ],
    'proxy' => 'http://proxy.example.com:8080',
]);

Using Function Index

If you know the function index instead of the API name, you can use fnIndex:

$result = $client->predict(['input'], fnIndex: 0);

Raw Response

To get the raw decoded response instead of an Output DTO:

$result = $client->predict(['input'], apiName: 'myFunction', raw: true);
// $result is an associative array

Event System

You can register callbacks for various events during the prediction process:

use SergiX44\Gradio\Client;
use SergiX44\Gradio\DTO\Messages\Estimation;
use SergiX44\Gradio\DTO\Messages\ProcessCompleted;

$client = new Client('https://my-special.hf.space');

// Called when a prediction is submitted
$client->onSubmit(function (array $payload) {
    echo "Submitted!\n";
});

// Called when queue position is estimated
$client->onQueueEstimation(function (Estimation $estimation) {
    echo "Queue position: {$estimation->rank}\n";
});

// Called when processing starts
$client->onProcessStarts(function () {
    echo "Processing started\n";
});

// Called when processing completes (success or failure)
$client->onProcessCompleted(function (ProcessCompleted $message) {
    echo "Completed: " . ($message->success ? 'success' : 'failed') . "\n";
});

// Called only on success
$client->onProcessSuccess(function (ProcessCompleted $message) {
    $output = $message->output;
});

// Called only on failure
$client->onProcessFailed(function (ProcessCompleted $message) {
    echo "Failed!\n";
});

// Called when the queue is full
$client->onQueueFull(function () {
    echo "Queue is full!\n";
});

// Called during streaming/generating
$client->onProcessGenerating(function () {
    echo "Generating...\n";
});

$result = $client->predict(['input'], apiName: 'myFunction');

Accessing Config

$config = $client->getConfig();

echo $config->version;   // Gradio version
echo $config->protocol;  // 'sse_v3', 'ws', etc.
echo $config->title;     // App title

File Upload

You can pass file paths or resources as arguments, and they will be automatically encoded as base64:

// Using a file path
$result = $client->predict(['/path/to/image.png'], apiName: 'classify');

// Using a resource
$stream = fopen('/path/to/audio.mp3', 'r');
$result = $client->predict([$stream], apiName: 'transcribe');

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Sergio Brighenti
• All Contributors

License

The MIT License (MIT). Please see License File for more information.