serafim/boson

Native PHP WebView bridge

0.3.0 2025-03-21 00:34 UTC

Requires

• php: ^8.4
• ext-ffi: *
• ffi/env: ^1.0

Requires (Dev)

• ffi/var-dumper: ^1.0
• friendsofphp/php-cs-fixer: ^3.72
• jetbrains/phpstorm-attributes: ^1.2
• phpstan/phpstan: ^2.1
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^12.0
• symfony/console: ^6.4|^7.0
• symfony/var-dumper: ^6.4|^7.0

MIT

README

Why Boson? Because it's not an Electron! And much easier than that =)

Also, this repository contains included high level PHP bindings for webview v0.12.0.

• Simple Example
• Requirements
  • Windows
  • Linux & BSD
    • Debian
    • Fedora
    • FreeBSD
  • MacOS
• Usage
  • Window
    • Window Title
    • Window Resizing
    • Window Max Size
    • Window Min Size
    • Window Fixed Size
    • Window Dark Mode
  • WebView
    • HTML Content
    • Load Content From URL
    • Styles
      • Global Styles
    • JavaScript
      • Global Scripts
      • Creating Functions
      • Code Evaluation
      • Code Requests
  • Misc
    • Quit
    • Debug Mode
    • Custom Library

Simple Example

use Serafim\Boson\Application;

$app = new Application();

$app->webview->html = <<<'HTML'
    <button onclick="foo('HELLO');">Hello</button>
    HTML;

$app->webview->bind('foo', function (string $message): void {
    var_dump($message);
});

$app->run();

Requirements

• PHP ^8.4
  • ext-ffi

Platform	X86	AMD64	ARM64	Technologies
Windows	✓	✓	✖ (see #1)	Windows API, WebView2
Linux	✓	✓	✖ (see #1)	GTK, WebKitGTK
macOS	✓	✓	✓	Cocoa, WebKit

1. It would be nice if you sent a PR with support for this platform:

cmake -DCMAKE_BUILD_TYPE=Release -S . -B ./build
cmake --build ./build --target webview --config Release

# The binary will be located in `./bin/libwebview.[ext]`

Windows

Requires Windows 10 or higher.

End-users must have the WebView2 runtime installed on their system for any version of Windows before Windows 11.

Note: A pre-builded version of the bridge already comes with the portability package in bin/WebView2Loader.dll. No any additional installation required.

Linux and BSD

The GTK and WebKitGTK libraries are required. You need to check your package repositories regarding which packages to install.

Debian

WebKitGTK 6.0, GTK 4

apt install libgtk-4-1 libwebkitgtk-6.0-4

WebKitGTK 4.1, GTK 3, libsoup 3

apt install libgtk-3-0 libwebkit2gtk-4.1-0

WebKitGTK 4.0, GTK 3, libsoup 2

apt install libgtk-3-0 libwebkit2gtk-4.0-37

Fedora

WebKitGTK 6.0, GTK 4

dnf install gtk4 webkitgtk6.0

WebKitGTK 4.1, GTK 3, libsoup 3

dnf install gtk3 webkit2gtk4.1

WebKitGTK 4.0, GTK 3, libsoup 2

dnf install gtk3 webkit2gtk4.0

FreeBSD

GTK 4

pkg install webkit2-gtk4

GTK 3

pkg install webkit2-gtk3

MacOS

It appears that no additional dependencies are required.

Usage

Window Title

To get or update the title, you should change the $title property

$app = new Serafim\Boson\Application();

$app->webview->title = 'New Title';

echo 'Current Title: ' . $app->webview->title;

$app->run();

Or set title from configuration

$app = new Serafim\Boson\Application(
    window: new Serafim\Boson\Window\NewWindowCreateInfo(
        title: 'New Title'
    ),
);

$app->run();

Window Resizing

To change the size, use the resize() method.

$app = new Serafim\Boson\Application();

$app->window->resize(640, 480);

$app->run();

Or set size from configuration

$app = new Serafim\Boson\Application(
    window: new Serafim\Boson\Window\NewWindowCreateInfo(
        width: 640,
        height: 480,
    ),
);

$app->run();

Window Max Size

To change the max size, use the resize() method.

[Linux/GTK4]: Using WindowSizeHint::MaxBounds for setting the maximum window size is not supported with GTK 4 (Linux platform) because X11-specific functions such as gtk_window_set_geometry_hints were removed. This option has no effect when using GTK 4.

$app = new Serafim\Boson\Application();

$app->window->resize(640, 480, \Serafim\Boson\Window\WindowSizeHint::MaxBounds);

$app->run();

Window Min Size

To change the min size, use the resize() method.

$app = new Serafim\Boson\Application();

$app->window->resize(640, 480, \Serafim\Boson\Window\WindowSizeHint::MinBounds);

$app->run();

Window Fixed Size

To set the fixed size, use the resize() method.

$app = new Serafim\Boson\Application();

$app->window->resize(640, 480, \Serafim\Boson\Window\WindowSizeHint::Fixed);

$app->run();

Window Dark Mode

To set the dark mode (dark theme), use the $darkMode window property.

[Linux]: Currently not supported, this option has no effect

[MacOS]: Currently not supported, this option has no effect

$app = new Serafim\Boson\Application();

$app->window->darkMode = true;

$app->run();

Or set dark mode from configuration

$app = new Serafim\Boson\Application(
    window: new Serafim\Boson\Window\NewWindowCreateInfo(
        darkMode: true,
    ),
);

$app->run();

WebView HTML Content

To set the content, you should use the $html property

$app = new Serafim\Boson\Application();

$app->webview->html = '<button>Do Not Click Me!</button>';

$app->run();

Or set html content from configuration

$app = new Serafim\Boson\Application(
    window: new Serafim\Boson\Window\NewWindowCreateInfo(
        webview: new Serafim\Boson\WebView\HTMLWebViewCreateInfo(
            html: '<button>Do Not Click Me!</button>',
        ),
    ),
);

$app->run();

Please note that reading this property is NOT possible. If you need to read the contents, use the data retrieval method.

$app = new Serafim\Boson\Application();

$app->webview->request('document.body.innerHTML')
    ->then(function (string $html) {
        var_dump($html);
    });

$app->run();

WebView URL

To load content from the URL, you should use the $url property

$app = new Serafim\Boson\Application();

$app->webview->url = 'https://nesk.me';

$app->run();

Or set URL from configuration

$app = new Serafim\Boson\Application(
    window: new Serafim\Boson\Window\NewWindowCreateInfo(
        webview: new Serafim\Boson\WebView\URLWebViewCreateInfo(
            url: 'https://nesk.me',
        ),
    ),
);

$app->run();

Global Styles

You can register a CSS style that will be applied to any page

$app = new Serafim\Boson\Application();

$app->webview->styleBeforeLoad(<<<'CSS'
    body {
        background: #900;
    }
    CSS);

$app->run();

Or set styles from configuration

$app = new Serafim\Boson\Application(
    window: new Serafim\Boson\Window\NewWindowCreateInfo(
        webview: new Serafim\Boson\WebView\WebViewCreateInfo(
            styles: [<<<'CSS'
                body {
                    background: #900;
                }
                CSS],
        ),
    ),
);

$app->run();

Global Scripts

You can register a JavaScript code that will be applied to any page

$app = new Serafim\Boson\Application();

$app->webview->evalBeforeLoad(<<<'JS'
    alert('hello');
    JS);

$app->run();

Or set scripts from configuration

$app = new Serafim\Boson\Application(
    window: new Serafim\Boson\Window\NewWindowCreateInfo(
        webview: new Serafim\Boson\WebView\WebViewCreateInfo(
            scripts: [<<<'JS'
                alert('hello');
                JS],
        ),
    ),
);

$app->run();

Creating Functions

You can create a function that can be called directly from WebView

$app = new Serafim\Boson\Application();

$app->webview->bind('foo', function () { 
    var_dump('Executed!');
});

$app->run();

Or set functions list from configuration

$app = new Serafim\Boson\Application(
    window: new Serafim\Boson\Window\NewWindowCreateInfo(
        webview: new Serafim\Boson\WebView\WebViewCreateInfo(
            functions: ['foo' => function () { 
                var_dump('Executed!');
            }],
        ),
    ),
);

$app->run();

Code Evaluation

You can execute arbitrary code directly on current WebView

$app = new Serafim\Boson\Application();

$app->webview->eval('document.write("Hello World!")');

$app->run();

Code Requests

You can directly get data from WebView context

$app = new Serafim\Boson\Application();

$app->webview->request('document.location')
    ->then(function (array $data) {
        var_dump($data);
    });

$app->run();

Quit

To exit the application, you should call the quit() method

$app = new Serafim\Boson\Application();

$app->webview->html = '<button onclick="quit()">exit</button>';

$app->webview->bind('quit', function () use ($app) {
    $app->quit();
});

$app->run();

Debug Mode

To enable debug mode, you should define the debug: ?bool argument of the Application instance.

$app = new Serafim\Boson\Application(
    // true  - enable debug mode
    // false - disable debug mode
    // null  - autodetect debug mode
    debug: true, 
);

$app->run();

Custom Library

To define binary, you should define the library: ?non-empty-string argument of the Application instance.

$app = new Serafim\Boson\Application(
    // string - defines pathname to the library
    // null   - autodetect library
    library: __DIR__ . '/path/to/custom-webview.so',
);

$app->run();