PHP client example

Eranio Published on: 14. October 2026

StreamBridge (Minecraft): PHP client example

A simple PHP client that takes on the same role as the plugin: periodically poll the bridge endpoint, report your own status, and process the returned actions. Useful if you want to build your own integration (for example for a different game or your own server type) against the same interface.

Base class

<?php

class StreamBridgeClient
{
    private string $url;
    private string $token;

    public function __construct(string $url, string $token)
    {
        $this->url = rtrim($url, '/') . '/api/v1/minecraft/bridge';
        $this->token = $token;
    }

    /**
     * Reports the current state and fetches waiting actions.
     *
     * @param array $players List of online players
     * @param array $results Results of previously executed actions
     * @return array{actions: array, display: array}
     */
    public function poll(array $players = [], array $results = [], bool $paused = false, string $game = 'minecraft'): array
    {
        $ch = curl_init($this->url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => json_encode([
                'version' => '1.8.0',
                'paused' => $paused,
                'game' => $game,
                'players' => $players,
                'results' => $results,
            ]),
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json',
                'Authorization: Bearer ' . $this->token,
            ],
            CURLOPT_CONNECTTIMEOUT => 5,
            CURLOPT_TIMEOUT => 8,
        ]);
        $response = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($status !== 200) {
            throw new RuntimeException("Bridge request failed (HTTP {$status}): {$response}");
        }

        return json_decode($response, true) ?? ['actions' => [], 'display' => []];
    }
}

Usage

$client = new StreamBridgeClient('https://your-panel.example', 'your-token');

$players = [
    ['name' => 'Steve', 'health' => 20, 'max_health' => 20, 'food' => 20, 'level' => 30,
     'world' => 'world', 'dimension' => 'overworld', 'gamemode' => 'survival', 'effects' => [], 'timers' => []],
];

$result = $client->poll($players);

foreach ($result['actions'] as $action) {
    echo "Action {$action['action']} for {$action['player']} from {$action['viewer']}\n";
    // Execute the action in your own game/server here ...

    // Then report the result on the next poll() call:
    // $results[] = ['id' => $action['id'], 'ok' => true, 'detail' => null];
}

if ($result['display']['live'] ?? false) {
    echo "{$result['display']['streamer']} is currently live on {$result['display']['platform']}!\n";
}

Important: every received action must be acknowledged in the results array (with its id) on the next poll() call, otherwise it keeps counting as still open.

FAQ

Do I need to send the full player structure? No, every field except name is optional and falls back to a sensible default when missing (see the "Send status & fetch actions" guide in the test area).

How often should I call poll()? The real plugin polls once per second by default (see poll-interval-ticks in the configuration). Match that so actions arrive promptly without hitting the endpoint more often than necessary.

What happens if I don't report a result? The action stays "sent but unconfirmed" and won't be included again in the response, but the server never records it as successful.