Download the PHP package yangweijie/perry-php without Composer

Perry PHP

Cross-platform UI abstraction and code generation framework. Define UI once in PHP, generate native code for Apple, Android, Windows, Linux, and Web platforms.

Table of Contents

• Installation
• Quick Start
• UI Components
  • Text — Text Display
  • Button — Clickable Button
  • VStack — Vertical Layout
  • HStack — Horizontal Layout
  • Spacer — Flexible Space
  • Image — Image Display
  • ScrollView — Scrollable Container
  • TextInput — Text Input Field
  • Toggle — Toggle Switch
  • AppContainer — Root App Container
• State Management
  • Binding — Reactive Data Binding
  • State / StateId — Low-level State
• Actions
  • Simple Actions
  • Closure Actions (AST-based)
  • Supported PHP Features
  • PHP Function Mappings
• Styling
  • Style Builder
  • Style Properties Reference
  • Platform Support Matrix
• Code Generation
  • Backends
  • Generators
  • IR System
• Platform Support
• Build System
• CLI Usage
• Examples
• Extending Perry
  • Adding a Custom Widget
  • Adding a Custom Backend
  • Adding a Custom Generator
  • Adding PHP Function Mappings
• Architecture

Installation

Requirements: PHP 8.2+

Quick Start

UI Components

All components extend Perry\UI\Widget. Each widget has:

• A constructor that accepts its specific parameters
• A kind() method returning the WidgetKind enum
• A style() method inherited from Widget for fluent styling
• A unique handle() (auto-generated WidgetHandle)

Text

Displays static text or reactive bound data.

Constructor:

Methods:

How bindings work: When a Text widget receives a Binding, AppContainer::bindings() auto-collects it. The backend generates @State (Swift), const state = {} (JS), or mutableStateOf (Kotlin) for it.

Generated code:

Full example — a live clock display:

Button

Clickable button with label and optional action.

Constructor:

Methods:

Generated code (Swift):

Generated code (HTML):

VStack

Vertical layout — arranges children top to bottom.

Constructor:

Spacing: Controlled via Style::padding() on the VStack — the padding value becomes spacing in SwiftUI:

Generated code:

HStack

Horizontal layout — arranges children left to right.

Constructor:

Generated code:

Spacer

Flexible space that expands to fill available area. Use inside HStack or VStack to push elements apart.

Constructor: No parameters.

Generated code:

Image

Displays an image from a path or resource name.

Constructor:

Methods:

Generated code:

ScrollView

Scrollable container for content that exceeds the viewport.

Constructor:

Generated code:

TextInput

Text input field with placeholder.

Constructor:

Methods:

Generated code:

Toggle

Toggle switch with label.

Constructor:

Methods:

Generated code:

AppContainer

Root application container. Wraps your widget tree, sets window dimensions, and auto-collects all Binding objects.

Constructor:

Methods:

Binding collection logic: AppContainer walks the entire widget tree and collects every Binding from Text widgets. Bindings passed as ...$extraBindings are also included. This is how the backends know which @State / const state variables to declare.

State Management

Binding

Declarative, two-way data binding. The primary way to manage state.

Constructor:

How it works:

1. Pass a Binding to a Text widget: new Text($display)
2. AppContainer auto-collects it
3. Backends generate state declarations:
   • Swift: @State private var display = "0"
   • JavaScript: const state = { display: "0" }
   • Kotlin: var display = mutableStateOf("0")
   • Dart: var display = ValueNotifier("0")
   • C#: var display = "0";
4. When a button action modifies $display, the generated code assigns to the state variable
5. Re-render updates all bound Text widgets

Using $count in actions (closure):

State / StateId

Lower-level state management for TextInput and Toggle widgets.

When to use:

• Binding — Most cases. Declarative, auto-collected by AppContainer.
• State/StateId — TextInput and Toggle widgets require StateId.

Actions

Simple Actions

Pre-built action types for common operations:

Widget Actions

Interactive widgets support Action for event handling:

Supported event properties:

Action types work across all widgets:

Closure Actions

The most powerful action type. Write PHP closures that get parsed into an AST and cross-compiled to any target language.

How it works:

Closure bindings (parameter substitution):

Nested closure pattern (for parameterized buttons):

Supported PHP Features

PHP Function Mappings

=== false optimization: All generators detect expr === false and emit !expr instead.

Styling

Style Builder

Fluent API — chain methods to compose styles:

Methods:

Style Properties Reference

Platform Support Matrix

All 6 backends now support the full set of 28 StyleProperties and event system (Button/Slider/TextInput/Toggle Actions):

Support levels:

Code Generation

Backends

Generators

Generators transform IR into target language code. Each implements Perry\IR\Generator.

IR System

54 intermediate representation node types:

Core (14): Program, Assignment, IfStatement, BinaryOp, UnaryOp, Variable, Literal, FunctionCall, ReturnStatement, ArrayAccess, MethodCall, PropertyAccess, Ternary, ArrayLiteral

Loops (5): WhileStatement, ForStatement, ForeachStatement, BreakStatement, ContinueStatement

Switch/Match (3): SwitchStatement, CaseNode, MatchExpression

Output (2): EchoStatement, PrintStatement

Type System (1): Cast

Inc/Dec (2): Increment, Decrement

Compound Assignment (5): PlusAssign, MinusAssign, MulAssign, DivAssign, ModAssign

Binary Ops (11): PowOp, BitwiseAnd, BitwiseOr, BitwiseXor, ShiftLeft, ShiftRight, SpaceshipOp, CoalesceOp, LogicalAnd, LogicalOr, LogicalXor

Unary Ops (2): UnaryPlus, BitwiseNot

Nullsafe (2): NullsafeMethodCall, NullsafePropertyAccess

Exceptions (3): ThrowStatement, TryCatchStatement, CatchClause

Static (3): StaticCall, StaticPropertyAccess, ClassConstFetch

Include (1): IncludeStatement

Platform Support

Build System

Compile to native app:

Windows Requirements

Apps that use the WebView widget (e.g., the Pry JSON viewer) require WebView2 Runtime on Windows.

Install WebView2 Runtime:

• Option 1 — Evergreen Bootstrapper (recommended, auto-updates):
  Download from Microsoft Edge WebView2:
  https://go.microsoft.com/fwlink/p/?LinkId=2124703

• Option 2 — Evergreen Standalone Installer:
  https://go.microsoft.com/fwlink/p/?LinkId=2124702

• Option 3 — Fixed Version (for offline/restricted environments):
  https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section

• Check if already installed:
  Open Control Panel → Programs and Features and look for WebView2 Runtime.
  Or check C:\Program Files (x86)\Microsoft\EdgeWebView\Application\.

  WebView2 ships with Microsoft Edge (Chromium-based), so it's often already present on modern Windows systems.

Build output: The compiler writes pry.html alongside the .exe file. The app reads it at runtime via WebView2's NavigateToString().

CLI Usage

Examples

Calculator

Full calculator with 7 actions, state management, and styling. Runs on macOS and web.

Simple Counter

Todo List

Pry — JSON Viewer (with WebView2 on Windows)

A native JSON viewer with tree view, search, syntax highlighting, and clipboard support. Uses WebView widget to embed a full HTML/JS UI.

Note for Windows: Requires WebView2 Runtime. The generated pry.html file contains the complete viewer UI (tree rendering, search, context menus) and is loaded at runtime.

Extending Perry

1. Adding a Custom Widget

Create a new widget class, add it to WidgetKind, and update all backends to handle it.

Step 1: Create the widget class

Step 2: Add enum case to WidgetKind

Step 3: Update each backend to generate code for Slider

Step 4: Repeat for each backend (KotlinGenerator, DartGenerator, CSharpGenerator, etc.)

2. Adding a Custom Backend

A backend converts the widget tree into target platform code.

Step 1: Create the backend class

Step 2: Register in CodegenFactory

Step 3: Use it

3. Adding a Custom Generator

A generator converts IR nodes into target language code.

Step 1: Create the generator class

Step 2: Use it with a backend

4. Adding PHP Function Mappings

Each generator maps PHP built-in functions to target language equivalents.

Example: Add array_map() support to SwiftGenerator

To add support across all generators:

1. Add the mapping in SwiftGenerator.php
2. Add the mapping in JavaScriptGenerator.php
3. Add the mapping in KotlinGenerator.php
4. Add the mapping in DartGenerator.php
5. Add the mapping in CSharpGenerator.php
6. Add tests in tests/Generator/

Architecture

License

MIT