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.brfile next to an asset goes out as it is, also without the extension; see Static compression)
Installation
composer require mbolli/php-viaphp-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:
<?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();Count: 0
Only this tab sees this count.
php app.php
# [INFO] Via server started on http://0.0.0.0:3000Open 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:
- php-via runs your page handler, puts the view into its shell and sends the page. The shell's
via_headwrites the tags that connect the tab, the signal values come along as JSON, andvia_footloads Datastar. - Datastar opens an SSE stream to
/_sse, and php-via renders the view again for it. - A click makes Datastar POST to
/_action/increment, with the tab's signals in the body. - Your action runs. When it returns, the signals it changed go to the tab over the stream.
- 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.