v1.8

Bug Fixes

Critical: SIGSEGV crash on Ubuntu 22.04+ / glibc 2.34+ (#linux)

The bundled libtcl8.6.so was compiled against glibc ≤ 2.29. In glibc 2.34, libpthread.so.0 and libdl.so.2 were merged into libc.so.6; the leftover stubs altered the GLOB_DAT symbol-search order so that environ resolved to a stale pointer inside TclSetupEnv → SIGSEGV before the window appeared.

Root cause confirmed via coredump analysis:

#0  TclSetupEnv    (libtcl8.6.so + 0xc7988)   ← cmpq $0x0,(%rax) — environ points to stale memory
#1  Tcl_CreateInterp (libtcl8.6.so + 0x472b7)
#2  ffi_call (libffi.so.8)

Fix: libtcl8.6.so and libtk8.6.so rebuilt from Tcl/Tk 8.6.16 source on Ubuntu 24.04 (glibc 2.39). The new binaries link directly against libc.so.6 — no separate libpthread/libdl stubs — and include matching init-script directories (tcl8.6/, tk8.6/).

Affected distros (all now fixed with zero system dependency):

• Ubuntu 22.04 (glibc 2.35)
• Ubuntu 24.04 (glibc 2.39)
• Ubuntu 25.04 (glibc 2.42)
• Fedora 35+ / RHEL 9+ and any distro on glibc ≥ 2.34

Note for glibc < 2.34 (Ubuntu 20.04 and older): the new bundled binary requires glibc 2.34+ symbols. If FFI::cdef() fails to load it, the library automatically falls back to the system-installed Tcl (sudo apt install tcl8.6 tk8.6).

Breaking Changes

serveDirectory() removed from WebView

serveDirectory() spun up a PHP built-in HTTP server, causing firewall prompts and port conflicts on consumer PCs. It has been removed — use serveFromDisk() instead (available since v1.7):

// Before (removed)
$webview->serveDirectory(__DIR__ . '/frontend/dist');

// After
$webview->serveFromDisk(__DIR__ . '/frontend/dist');

serveFromDisk() uses native platform URI schemes — no ports, no extra processes.

Tooling

Reproducible Linux library build (build/rebuild-linux-libs.dockerfile)

If the bundled .so files ever need to be refreshed (e.g. new Tcl version), run:

docker build -f build/rebuild-linux-libs.dockerfile --output src/lib .

This produces a consistent set of .so binaries + matching init-script directories from the same source tarball, ensuring the version lock that Tcl_Init enforces is always satisfied.

v1.7

What's New

`serveFromDisk()` — Native file serving, no HTTP server

Serve your frontend build directly from disk using platform-native URI schemes. No ports, no firewall prompts, no extra processes — works on consumer PCs out of the box.

```php
$webview->serveFromDisk(DIR . '/frontend/dist');
```

Platform	Mechanism	URL
Linux	WebKitGTK `phpgui://` URI scheme	`phpgui://app/index.html`
Windows	WebView2 virtual host	`https://phpgui.localhost/\`
macOS	`loadFileURL:allowingReadAccessToURL:`	`file://…/index.html`

Includes SPA router fallback on Linux (unknown paths serve `index.html`).

`serveVite()` — Dev/prod auto-detection

```php
$webview->serveVite(DIR . '/frontend/dist');
```

`enableFetchProxy()` — Transparent CORS bypass

```php
$webview->enableFetchProxy();
```

`onServeDirReady()` — Know the effective URL

```php
$webview->onServeDirReady(function(string $url) {
echo "Serving at: $url\n";
});
```

Bug Fixes

• Linux: Path traversal hardening — `g_serve_dir` normalized with trailing `/` so `/srv/app-evil/` cannot match `/srv/app/`
• Linux: `phpgui://` scheme registered only once per process (idempotency guard)
• Linux: Fixed double-slash in asset file paths
• Windows: `SetVirtualHostNameToFolderMapping` failures now emit a descriptive error to PHP instead of silently loading nothing
• macOS: Replaced `webview_navigate("file://...")` with `loadFileURL:allowingReadAccessToURL:` — fixes asset 404s in multi-file SPAs
• macOS: Installed `WKUIDelegate` so `alert()`, `confirm()`, and `prompt()` show native `NSAlert` panels

Pre-built Binaries

• `webview_helper_linux_x86_64` — rebuilt with all v1.7 fixes
• macOS and Windows binaries: CI rebuild pending — use v1.6 binaries in the meantime

v1.6 — WebView Widget (Beta)

What's New

WebView Widget (Beta)

Build desktop apps with HTML/CSS/JS frontends and PHP backends — a Tauri-like experience for PHP developers.

• Native webview windows via platform browser engines (WebKitGTK, WKWebView, WebView2)
• JSON-over-stdio IPC bridge between PHP and the webview
• Commands (JS→PHP): call PHP functions from JavaScript via bind()
• Events (PHP→JS): push data to the frontend via emit()
• Runs alongside Tcl/Tk widgets in the same event loop
• Pre-built helper binaries auto-downloaded on composer install

$app = new PhpGui\Application();
$wv = new PhpGui\Widget\WebView([
    'title' => 'My App',
    'width' => 1024,
    'height' => 768,
]);
$wv->setHtml('<h1>Hello from PHP!</h1>');
$wv->bind('greet', fn($id, $args) => $wv->returnValue($id, 0, '"Hello!"'));
$app->addWebView($wv);
$app->run();

Beta: The WebView API is functional and tested across Linux, macOS, and Windows, but may change before stable release.

Other Changes

• Upgraded all GitHub Actions to latest versions (Node.js 24)
• Added CI testing for WebView on all three platforms
• Auto-download of pre-built helper binaries via composer install

Pre-built Binaries

Helper binaries attached below are auto-downloaded by composer install:

• webview_helper_linux_x86_64
• webview_helper_darwin_x86_64
• webview_helper_darwin_arm64
• webview_helper_windows_x86_64.exe

v1.5

Bug Fixes

Windows zero-dependency fix — On a fresh Windows PC, tcl86t.dll failed to load because its dependency zlib1.dll (bundled in windows/bin/) wasn't in PATH. The bundled directory is now added to PATH before FFI loads, mirroring how Linux (LD_LIBRARY_PATH) and macOS (DYLD_FALLBACK_LIBRARY_PATH) were already handled.

Widgets whose create() was never called — Frame, Entry, Combobox, and Menubutton were missing __construct, so their Tcl
widgets were silently never created.

Entry getValue/setValue didn't work — Was missing -textvariable, so get/set operated on an unlinked Tcl variable instead of the
widget.

Combobox failed on Windows — package require ttk fails on Tcl 8.5+ because ttk is built into Tk. Removed the redundant call.

Menu::destroy() was a no-op — Menu creates at .{$id} but inherited destroy tried .{$parent}.{$id}. Added a proper override.

Testing

• tests/TestRunner.php — New assertion framework. Tests now exit code 1 on failure so CI catches regressions.
• CanvasTest.php — New: covers all drawing methods
• CheckbuttonTest.php — New: covers state management and callbacks
• All 10 existing tests rewritten with real assertions + winfo exists Tcl verification
• TopLevelWidgetTest rewritten without interactive dialogs (CI-safe)
• CI runs all 13 tests on Linux, macOS, and Windows

113 assertions passing across 13 test files on all three platforms.

v1.4

What's New

macOS (Apple Silicon) Support — Zero Dependencies

PHP GUI now works out of the box on macOS with zero system package requirements. No Homebrew, no Xcode, no X11 — just composer require and go.

Bundled Libraries

• Tcl 9.0.3 — native arm64 macOS binary (libtcl9.0.dylib)
• Tk 9.0.3 — native Cocoa/Aqua rendering, no X11 needed (libtcl9tk9.0.dylib)
• libtommath 1.x — bundled dependency with @loader_path linking for full portability
• All dylibs are ad-hoc signed and reference only macOS system frameworks

Tcl 9.0 API Support

• ProcessTCL now supports both Tcl 8.6 (Linux/Windows) and Tcl 9.0 (macOS) C APIs
• Tcl 9 removed several legacy functions (Tcl_Eval, Tcl_GetStringResult, Tcl_GetVar, Tcl_SetVar); the FFI bridge now uses the Tcl 9 equivalents (Tcl_EvalEx, Tcl_GetObjResult+Tcl_GetString, Tcl_GetVar2, Tcl_SetVar2) automatically based on the loaded library version
• No changes required in widget code or user-facing API — fully backwards compatible

Bug Fixes

• Fixed callback/quit signal temp file path mismatch on macOS (sys_get_temp_dir() returns /var/folders/... on macOS, not /tmp/). This was causing all event callbacks (button clicks, menu actions, key bindings) to silently fail on macOS.

CI/CD

• Added test-macos job to GitHub Actions workflow — macOS tests now run alongside Linux tests on every PR

Platform Support

Platform	Status	Tcl/Tk Version	Dependencies
Linux x86_64	✅ Zero-dep	8.6.16	None (bundled)
macOS arm64	✅ Zero-dep	9.0.3	None (bundled)
Windows	✅ Zero-dep	8.6	None (bundled)

Requirements

• PHP 8.1+ with ext-ffi

v1.3

What's New

Zero-Dependency Linux Support

PHP GUI now works out of the box on Linux with zero system package requirements. Just composer require and go — no need to install libtcl8.6, libtk8.6, or any X11 libraries.

Bundled Libraries

• Tcl/Tk 8.6.16 — portable shared libraries built on Debian Bullseye (glibc 2.29+), compatible with most modern Linux distributions
• X11 runtime libraries — libX11, libxcb, libXau, libXdmcp bundled in src/lib/x11/
• Tk built with --disable-xft to eliminate the libXft/fontconfig/freetype dependency chain

Code Fixes

• Fixed library path resolution in ProcessTCL (bundled → system fallback)
• Fixed Message widget path names (missing dot prefix)
• Fixed TopLevel widget test (invalid -text option)
• ProcessTCL automatically sets LD_LIBRARY_PATH, TCL_LIBRARY, TK_LIBRARY for bundled libs

CI/CD

• Added GitHub Actions workflow for automated testing on each PR
• Added Dockerfile.test for zero-dependency verification
• Added build-libs.yml workflow for rebuilding portable binaries

Requirements

• PHP 8.1+ with ext-ffi
• Linux: works out of the box (only xvfb needed for headless/CI environments)
• Windows/macOS: existing support unchanged

v1.2

Full Changelog: v1.1...v1.2

v1.1

Full Changelog: v1.0...v1.1