Documentation menu

Getting started with php-via

php-via is a PHP framework for server-side reactive UIs. Your app runs as a long-lived OpenSwoole server, and Datastar applies the server's updates in the browser.

You write signals, actions and views in PHP. Each tab receives new HTML and signal values over one SSE stream, so you write no JavaScript, run no build step and keep no separate API.

Requirements

  • PHP 8.4+
  • OpenSwoole PHP extension 26+
  • Composer
  • Twig (optional: views that are PHP closures need nothing more, template views need composer require twig/twig; see Twig templates)
  • Brotli PHP extension (optional: static files get Brotli level 11 once it is loaded, pages and SSE with Config::withBrotli(), and a .br file next to an asset goes out as it is, also without the extension; see Static compression)

Installation

composer require mbolli/php-via

php-via serves Datastar 1.0.5 itself, so the browser side needs no install.

Your first app

Create app.php in a new directory and put this counter in it. It is a complete php-via app:

The counter, running on this server
app.php
<?php
require __DIR__ . '/vendor/autoload.php';

use Mbolli\PhpVia\Config;
use Mbolli\PhpVia\Context;
use Mbolli\PhpVia\Via;

$app = new Via(new Config());

$app->page('/', function (Context $c): void {
    $count = $c->signal(0, 'count');

    $increment = $c->action(function () use ($count): void {
        $count->setValue($count->int() + 1);
    }, 'increment');

    $c->view(fn (): string => <<<HTML
        <div id="counter">
            <p>Count:
                <strong data-text="{$count->ref()}">
                    {$count->int()}
                </strong>
            </p>
            <button data-on:click="@post('{$increment->url()}')">
                +1
            </button>
        </div>
        HTML);
});

$app->start();
Live result

Count: 0

Only this tab sees this count.

php app.php
# [INFO] Via server started on http://0.0.0.0:3000

Open localhost:3000 in your browser and click the button. A second tab starts again at 0, because each tab keeps its own count. That is TAB scope, the default.

The action changes count and returns. php-via then sends the new value to the tab, and data-text shows it. $count->ref() writes the signal's reference for such expressions, and $count->int() writes the value into the first render. The view's HTML stays the same, so nothing renders again. When an action changes what the view renders, it calls $c->sync(), and Datastar puts the new HTML in place by the id of the view's top-level element, here counter.

How it works

A php-via page goes through these steps:

  1. php-via runs your page handler, puts the view into its shell and sends the page. The shell's via_head writes the tags that connect the tab, the signal values come along as JSON, and via_foot loads Datastar.
  2. Datastar opens an SSE stream to /_sse, and php-via renders the view again for it.
  3. A click makes Datastar POST to /_action/increment, with the tab's signals in the body.
  4. Your action runs. When it returns, the signals it changed go to the tab over the stream.
  5. Datastar updates the signals in the page. A sync() also sends the view's new HTML, and Datastar morphs only the elements that differ.

The page does not reload.

Configuring the server

Config holds the server's settings. Make every with*() call before new Via($config): the constructor freezes the Config, and a with*() call after it throws a LogicException.

$config = (new Config())
    ->withPort(8080)
    ->withDevMode(true); // for local work only

$app = new Via($config);

Dev mode logs more warnings, shows the exception of a page that fails instead of a bare Internal Server Error, and shows the default shell's Live Signals panel. Leave it off in production. The Config reference lists the settings.

Testing the counter

Testing\TestApp runs your pages in a test, without a server, through php-via's own page, action and SSE handlers. To share the page between the app and its tests, register it in a file of its own:

<?php
// routes.php
use Mbolli\PhpVia\Context;
use Mbolli\PhpVia\Via;

return function (Via $app): void {
    $app->page('/', function (Context $c): void {
        // the counter from app.php
    });
};

app.php then calls (require __DIR__ . '/routes.php')($app); before $app->start(), and a Pest test opens the page, clicks twice and reads the signal the browser holds:

<?php
// tests/CounterTest.php
use Mbolli\PhpVia\Config;
use Mbolli\PhpVia\Testing\TestApp;

it('counts clicks', function (): void {
    $app = new TestApp(new Config(), require __DIR__ . '/../routes.php');

    $tab = $app->open('/');
    $tab->action('increment')->action('increment');

    expect($tab->signal('count'))->toBe(2);
    $app->shutdown();
});

A TestTab also gives you the patches its stream received (patches()), the page as the server would render it now (html()), and disconnect(expire: true) to test a revival. TestApp runs everything in one process as one worker.

Next steps

  • Signals: reactive state and two-way binding
  • Actions: what runs when the browser posts, and what goes back
  • Views: when a view renders and how its HTML reaches the page
  • Scopes: share state between tabs and users
  • Components: compose complex pages from isolated sub-contexts
  • Examples: running examples with their PHP and Twig source

Professional support

Need help with architecture, migration, or scaling a server-centric PHP application? zwei und eins gmbh (the company behind php-via) offers audits and implementation support.