NativePHP for Mobile Documentation

The native-ui plugin (formerly compose-ui) is undergoing a rewrite to provide a consistent, themeable, and accessible UI kit that renders natively on both iOS and Android. The rewrite moves away from hand-rolled styling toward using native platform primitives and a centralized theming system.

Key improvements in the new architecture include:

• Native Primitives: Using actual platform components (e.g., Android OutlinedTextField) instead of hand-rolled styled text.
• Theming System: A centralized Theme class and configuration that allows consumer apps to set brand colors that propagate across all components.
• Type Safety: Moving away from 'stringly-typed' props across the bridge to prevent silent failures.
• Accessibility (a11y): Integration of roles, labels, and contrast validation.
• Two-way Binding: Improved state synchronization using the native:model directive.

The project is moving from a WebView-first model to a Persistent PHP Runtime model to significantly reduce navigation latency.

Current Model (WebView-first)

Every navigation triggers a full PHP lifecycle: onCreate() $\rightarrow$ WebView setup $\rightarrow$ loadUrl() $\rightarrow$ php_embed_init() $\rightarrow$ Laravel bootstrap $\rightarrow$ php_embed_shutdown(). This results in ~125-350ms of overhead per navigation.

New Model (Persistent PHP)

PHP boots once and stays alive. It decides whether to render a native UI or hand off to a WebView: onCreate() $\rightarrow$ phpRuntime.boot() (once) $\rightarrow$ phpRuntime.dispatch("/") $\rightarrow$ PHP returns either a Native Tree (for Compose) OR an HTML response (for WebView).

Performance Impact

NativePHP Mobile operates using a three-thread model to ensure the UI remains responsive even during heavy PHP processing:

1. PHP Thread: Hosts the persistent runtime. The Laravel application is booted once and kept warm. It runs the screen's runloop (Render $\rightarrow$ Publish $\rightarrow$ Sleep until event).
2. Reader Thread: Decodes and diffs incoming binary frames from the PHP thread. It coalesces updates by dropping stale intermediate frames to ensure the UI doesn't lag behind the current state.
3. UI Thread: The main platform thread that mounts the diffed changes to the screen. This thread also handles SharedValue gestures and animations directly to maintain high frame rates.

Additional Runtimes:

• Laravel Queues: Run on a separate embedded worker runtime.
• Android Lifecycle: When an Android Activity is destroyed, the PHP runtime is 'parked' rather than torn down, allowing for faster resumption.

SuperNative is the default architecture in NativePHP Mobile v4. It provides a PHP-driven, platform-native UI experience using SwiftUI on iOS and Jetpack Compose on Android.

Key characteristics:

• No Web View Required: Unlike traditional hybrid apps, it uses shared memory to communicate between PHP and the native UI, avoiding the overhead of a web view.
• EDGE Blade Components: Uses Blade components that compile to a fixed-length binary format for high-performance rendering.
• Truly Native: Components like native:button are real platform buttons, inheriting native accessibility, theming, and dark mode support automatically.
• What it is NOT: It is not a pixel-perfect rendering engine like Skia/Impeller, it is not a Virtual Machine, and it is not an HTML-to-native transpiler.

Opting back into Web View: If you need to use a web view for specific screens, you can use Route::native() to point to a screen containing a fullscreen webview element. You must also set NATIVEPHP_START_URL=/home in your .env file.

// Example of opting into a web view for a specific route
Route::native('/some-web-route');

The event system allows native code to trigger asynchronous operations that notify the PHP/Livewire layer.

The Flow:

1. Swift: Calls LaravelBridge.shared.send?(eventClass, payload).
2. JavaScript: Injects a dispatch into the browser: window.Livewire.dispatch('native:EventClass', payload).
3. PHP: A Livewire component listens for the event using the #[On('native:EventClass')] attribute.

To implement a new event, you must create a PHP Event class, dispatch it from Swift using the full namespace, and add the constant to the JavaScript NativeEvents object.

// 1. Create PHP Event Class
namespace Native\Mobile\Events\Your;
class ThingHappened {
    use /* ... */;
    public function __construct(public string $result, public ?string $id = null) {}
}

// 2. Dispatch from Swift
LaravelBridge.shared.send?("Native\\Mobile\\Events\\Your\\ThingHappened", ["result" => "success"])

// 3. Listen in Livewire
#[On('native:Native\\Mobile\\Events\\Your\\ThingHappened')]
public function handleThing($result, $id = null) { ... }

NativePHP Mobile uses a reactive model similar to Livewire for native components.

Two-way Data Binding: Use native:model="property" on input elements to bind to a public property in your NativeComponent. Supports modifiers like .blur, .lazy, and .debounce.300ms.

<native:text-input native:model="name" />

Reactivity Attributes:

• #[Computed]: Methods treated as properties. They are memoized per frame and invalidated on state change. Use #[Computed(persist: true)] to survive re-renders until state changes.
• #[Poll(interval)]: Runs a method at a specific interval (e.g., #[Poll(5000)]) or use native:poll="1s" in Blade to trigger re-renders.
• #[On(EventClass::class)]: Listens for native events (e.g., push notifications, websocket messages). Parameters bind by name to event properties. Listeners automatically teardown when the component unmounts.

Lifecycle Hooks:

• mount(): Runs only on the first push to the screen.
• onResume(): Runs when returning to the screen.
• onBackPressed(): Specifically for Android back button handling.
• unmount(): Runs when the component is removed.
• updated{Property}(): Runs when a bound property changes.

Native UI mode differs from WebView mode by maintaining a persistent PHP runtime. Instead of shutting down after a script execution, it enters an event loop:

1. Initialization: PHP calls nativephp_element_init() to allocate memory regions for the UI (a 4MB flat buffer, a 4MB property buffer, and a 256KB event buffer).
2. Publishing UI: PHP calls nativephp_element_publish($tree) to serialize a PHP array tree into a packed binary format in the flat buffer. This is sent to the Kotlin Compose renderer via JNI.
3. Waiting for Events: PHP calls nativephp_element_wait_event(-1), which blocks the PHP thread using a condition variable (pthread_cond_wait()).
4. Event Processing: When a user interacts with the UI, Kotlin writes a binary event into the 256KB event buffer and signals the condition variable. PHP unblocks, processes the event, rebuilds the UI tree, and repeats the loop.
5. Persistence: The PHP interpreter stays alive and holds state throughout the session. The global mutex remains locked, preventing any WebView requests from executing until the Native UI session ends and nphp_element_shutdown() is called.