wilaak/datastar-swoole

Datastar SDK for Swoole.

v0.3.1 2025-08-12 19:16 UTC

Requires

• php: >=8.2
• starfederation/datastar-php: 1.0.0-RC.3
• swoole/ide-helper: ^6.0

MIT

• Wilaak

README

This package offers an SDK for integrating Datastar with Swoole. It is a simple "wrapper" of the official PHP SDK.

Traditional PHP SAPI servers such as Apache, PHP-FPM or FrankenPHP struggle with efficiently handling large numbers of concurrent long-lived requests.

Swoole’s asynchronous, coroutine-driven architecture allows your application to efficiently manage thousands of simultaneous long-lived connections.

Installation

First you must install the Swoole PHP extension. Please refer to the documentation.

composer require wilaak/datastar-swoole

Usage Examples

In Swoole, each request is put in its own coroutine, allowing you to write PHP code in a standard blocking way.

Note: To ensure proper behavior of built-in functions, you must enable coroutine hooks. This is achieved by calling \Swoole\Runtime::enableCoroutine() at the start of your program.

// After this line of code, file operations, sleep, Mysqli, PDO, streams, etc., all become asynchronous IO.
\Swoole\Runtime::enableCoroutine();

$http = new \Swoole\Http\Server("0.0.0.0", 8082);

$http->on('request', function (\Swoole\Http\Request $request, \Swoole\Http\Response $response) {
    $sse = new \Wilaak\DatastarSwoole\SSE($request, $response);

    $message = "Hello, World!";
    foreach (str_split($message) as $i => $char) {
        $sse->patchElements("<h3 id='message'>" . substr($message, 0, $i + 1) . "</h3>");
        sleep(1);
    }
});

$http->start();

Note: When in a long-running request, it's important to close the connection once the user disconnects so as to not keep running forever:

// After this line of code, file operations, sleep, Mysqli, PDO, streams, etc., all become asynchronous IO.
\Swoole\Runtime::enableCoroutine();

$http = new \Swoole\Http\Server("0.0.0.0", 8082);

$http->on('request', function (\Swoole\Http\Request $request, \Swoole\Http\Response $response) {
    $sse = new \Wilaak\DatastarSwoole\SSE($request, $response);
    while (true) {
        $sse->patchElements("<h3 id='message'>" . time() . "</h3>");
        $success = $response->write('ping: hello');
        if ($success === false) {
            break;
        }
        sleep(1);
    }
});

$http->start();

This example covers most of the usage possible with this SDK:

use starfederation\datastar\enums\ElementPatchMode;

// After this line of code, file operations, sleep, Mysqli, PDO, streams, etc., all become asynchronous IO.
\Swoole\Runtime::enableCoroutine();

$http = new \Swoole\Http\Server("0.0.0.0", 8082);

$http->on('request', function (\Swoole\Http\Request $request, \Swoole\Http\Response $response) {

    // Creates a new `SSE` instance.
    $sse = new \Wilaak\DatastarSwoole\SSE($request, $response);

    // Reads signals from the request.
    $signals = $sse->readSignals();

    // Patches elements into the DOM.
    $sse->patchElements('<div></div>', [
        'selector' => '#my-div',
        'mode' => ElementPatchMode::Append,
        'useViewTransition' => true,
    ]);

    // Removes elements from the DOM.
    $sse->removeElements('#my-div', [
        'useViewTransition' => true,
    ]);

    // Patches signals.
    $sse->patchSignals(['foo' => 123], [
        'onlyIfMissing' => true,
    ]);

    // Executes JavaScript in the browser.
    $sse->executeScript('console.log("Hello, world!")', [
        'autoRemove' => true,
        'attributes' => [
            'type' => 'application/javascript',
        ],
    ]);

    // Redirects the browser by setting the location to the provided URI.
    $sse->location('/guide');
});

$http->start();

License

MIT