README

Native desktop applications written in PHP.
Components, state and styles in PHP; a Rust host that lays the tree out and drives real platform views.
No Electron, no Node.js, no web view in the rendering path.

Install · Quick example · Platforms · Features · Docs · Issues

Install

Create a project with the PAM CLI and run it:

pam init my-app --template desktop
cd my-app
pam composer require pushinbr/pam-desktop:^2.1
pam desktop init
pam desktop dev

pam init --template desktop in CLI 2.2.11 still scaffolds pushinbr/pam-desktop ^1.2 (1.x), so the third line moves the project to 2.x; it becomes unnecessary once the template is updated. pam desktop init writes a small application: a router, a home screen as a .pam.php template with scoped CSS, design tokens, a service and a test. pam desktop dev needs no argument (it finds the nearest pam-desktop.json), reloads the window about 0.3 s after a save and keeps #[State] values. Without PHP on the machine, the host installs it (the PAM runtime on Linux and macOS, the official windows.php.net build on Windows).

pam desktop runs the package's launcher, which downloads the native host of the installed version for the current system from the GitHub release (Linux, macOS and Windows, x86_64 and aarch64), verifies its SHA-256 and runs it. PAM_DESKTOP_HOST points the launcher at a host built from source. To build and run from a checkout, see Examples.

PAM Desktop 2.0 is a different product from 1.x. Version 1 rendered a web interface in a Servo web view behind a typed command gateway; version 2 renders a native interface from PHP components. Applications written for 1.x do not run on 2.x. See Migrating from 1.x.

Quick example

examples/counter/index.php:

<?php

declare(strict_types=1);

use Pam\Desktop\App;
use Pam\Desktop\Component;
use Pam\Desktop\Attributes\State;
use Pam\Desktop\Style;
use Pam\Desktop\UI\Button;
use Pam\Desktop\UI\Column;
use Pam\Desktop\UI\Text;

require __DIR__.'/../../vendor/autoload.php';

final class Counter extends Component
{
    #[State]
    public int $count = 0;

    public function render(): Column
    {
        return Column::make(
            Text::make('PAM Desktop')->style(new Style(fontSize: 28, fontWeight: 700)),
            Text::make("Count: {$this->count}")->style(new Style(fontSize: 18)),
            Button::make('Increment')->onPress(function (): void {
                $this->count++;
            }),
        )->style(new Style(padding: 24, gap: 16));
    }
}

App::run(new Counter());

Assigning to a #[State] property schedules a render. The host receives a patch with the one text that changed.

Platform support

Requirements

The optional features of the host on Linux, tray and hotkeys, need no extra system library. Platforms lists what each feature does.

The host starts the backend of the system it was built for. Two things were not verified on Linux either: the accessibility tree with a real screen reader, and global shortcuts through the Wayland portal (X11 key grabs were verified). Per-feature status: Platforms; first-run checklist: First run on macOS and Windows.

How it works

A PAM Desktop application is a PHP script. It declares components with reactive state and returns a tree of elements (Column, Row, Text, Button, Input, VirtualizedList…), using the same component syntax as PAM Native, the mobile sibling of this project.

The pam-desktop host starts that script in a PHP worker process and talks to it over stdin and stdout in binary frames. For every frame the host lays the tree out, computes the difference from the previous one and updates real platform views:

• GTK 4 on Linux
• AppKit on macOS
• Win32 with Direct2D and DirectWrite on Windows

Rendering never goes through a web view. A WebView element exists for the cases where an application wants to embed a page.

The host does not wait for PHP to animate, scroll, track gestures, play media or edit text. PHP runs when an event needs application logic and sleeps otherwise.

Features

Capabilities that only exist on phones in PAM Native (location, contacts, sensors, biometrics, SMS…) are not part of PAM Desktop. Their class names are still known: using one throws a PluginException that names the optional package it belongs to.

Examples

Every directory under examples/ is a runnable application that exercises one feature: counter, showcase, controls, lists, chat, navigation, motion, gestures, images, media, webview, canvas, shell, windows, dragdrop, text, modules, links, toast, errors, web-defaults. What each one shows and how to run them from a checkout: docs/examples.md. Crate and package map: docs/repository-layout.md.

Docs

• Getting started
• Components
• Templates
• Styling
• Grid tracks
• DesktopUI
• Charts
• Desktop shell
• Media and web
• Animation and gestures
• Modules
• Accessibility
• Development
• Architecture
• Compatibility
• Platforms
• First run on macOS and Windows
• Distribution
• Updates
• Migrating from 1.x
• Examples
• Repository layout
• Changelog

Part of the PAM ecosystem

PAM runs PHP natively on servers, desktops and phones. This repository is one piece of it.

_{Docs: push-in.github.io/pam-docs · Issues}

_{MIT License. The reactive PHP component core, the binary wire protocol and the layout and diff engine started as a copy of PAM Native and remain under the Apache License 2.0; NOTICE lists the origin release and the directories that hold the copied code. The two projects do not depend on each other; fixes are ported between them by hand.
Made in Brazil by Pushin}