Download the PHP package aureuserp/nativephp-remote without Composer

NativePHP Remote

Connect NativePHP mobile apps to a centralized web server instead of running PHP on-device. Build one Laravel app that works as both a web app and a native mobile app.

How It Works

NativePHP normally bundles your Laravel app and runs it locally on the device. This package patches NativePHP so the mobile WebView connects to your existing web server instead. All requests go to your server — the native shell provides the mobile experience (top bar, side nav, camera, haptics, etc.).

Requirements

• PHP 8.2+
• Laravel 11 or 12
• NativePHP Mobile ^3.0

Installation

The service provider is auto-discovered. To publish the config:

Setup

1. Configure NativePHP Start URL

In your config/nativephp.php (or .env on the device), set the start URL to your server:

The ?nativephp=1 parameter is required on the first request — it sets a cookie so subsequent requests are recognized as native.

2. Patch NativePHP

After installing or updating NativePHP, run:

This copies patched Kotlin/Swift files that enable:

• Hosted remote URL routing (WebView connects to your server)
• HTTPS enforcement in production
• Camera permission handling
• Smooth WebView scrolling
• Hash-based navigation for native actions
• JS-to-native bridge (vibrate, toast, native UI updates)
• /_native/ API routing to local PHP runtime

Without --force, it applies incremental patches to existing files (useful after NativePHP updates).

3. Add Middleware

Add the middleware to routes that should support native mode:

• PersistNativeShell — Sets a cookie on the first ?nativephp=1 request so the app is recognized as native on subsequent requests.
• RenderHostedNativeUi — Sends Edge component data via x-native-ui response header and renders it in the DOM for native UI hydration.

4. Include Bridge Scripts

Add the bridge scripts component to your layout, before </body>:

This provides:

• window.BarcodeNative.vibrate() — Trigger device haptic feedback
• window.BarcodeNative.toast(message, duration) — Show native toast ('short' or 'long')
• Automatic native UI re-hydration after Livewire SPA navigation

5. Add Native UI JSON to Layout

For native top bar, side nav, and bottom nav to work, include the Edge data in your layout:

PHP Helpers

JavaScript Bridge

After including <x-nativephp-remote::bridge-scripts />:

Dual-Mode Pages

Build pages that work both as web and native:

Safe Area Insets

The native shell injects CSS variables for device safe areas (notch, navigation bar):

Hash-Based Actions

Trigger native actions via URL hash fragments. Useful for native top bar buttons:

Then listen in JavaScript:

Configuration

What the Patcher Does

Running php artisan nativephp:patch-remote --force applies these changes to NativePHP's native code:

License

MIT