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

License

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

sergix44 / gradio-client-php

Maintainers

Package info

Fund package maintenance!

Statistics

Security