NativePHP is a framework that runs full PHP applications natively on iOS and Android devices without a web server. A pre-compiled PHP runtime is bundled inside a Swift (iOS) or Kotlin (Android) shell application, allowing your entire Laravel app to execute on the user's phone. If you follow a Laravel deployment guide for server apps, NativePHP extends that knowledge to ship mobile apps without learning Swift, Kotlin, React Native, or Flutter.

The current stable release is v3.3.6 (June 5, 2026). The package nativephp/mobile is available on Packagist under an MIT license and has been free and open source since v3.0. PHP 8.3 is required; Laravel 10, 11, 12, and 13 are supported.

This guide covers everything a PHP developer needs: how NativePHP works, installation and configuration, available native device APIs, security best practices, App Store and Play Store deployment, and how NativePHP compares to React Native and Capacitor.

What Is NativePHP and How Does It Work?

NativePHP for Mobile uses a four-component architecture: (1) standard Laravel application code, (2) the nativephp/mobile Composer package, (3) custom-compiled PHP binaries bundled inside the app, and (4) native Swift or Kotlin shell applications hosting the PHP runtime. A custom PHP extension bridges native device APIs like camera, biometrics, and geolocation into PHP userland code.

The UI layer is a WebView. HTML, CSS, and JavaScript render your Blade templates, Livewire components, or Vue and React frontend exactly as in a browser. The backend running those templates lives on the device, not a server, resulting in an offline-first app with zero infrastructure cost per user and sub-30ms response times, thanks to the persistent runtime introduced in v3.1.

The GitHub organization hosts core repositories: NativePHP/mobile-air (C-language native runtime), NativePHP/mobile-starter (starter kit), and NativePHP/kitchen-sink-mobile as a reference application. The desktop variant (NativePHP/desktop) is separate. The older NativePHP/laravel and NativePHP/electron repositories are archived and unmaintained.

Installation and Prerequisites

NativePHP requires a macOS machine to build iOS apps because Xcode is mandatory for iOS compilation. Android builds work on macOS, Linux, or Windows native installations. WSL (Windows Subsystem for Linux) is not supported -- install directly on Windows and exclude your project folder from Windows Defender scanning to avoid build slowdowns caused by real-time antivirus scans of compiled files.

Version Requirements

• PHP: 8.3 or later (PHP 8.3 support was temporarily broken in v3.3.x and restored in v3.3.4 -- always use 3.3.4 or later)
• Laravel: 10, 11, 12, or 13
• iOS: Xcode latest stable, Apple Developer account, physical device in Developer Mode
• Android: Android Studio, USB Debugging enabled on the device, API 26 (Android 8.0) minimum SDK
• ICU/Intl extension: Optional at install time -- required if you use Filament or any locale-sensitive package

Installation Commands

# Install via Composer
composer require nativephp/mobile
Scaffold the native project
You will be prompted to choose ICU or non-ICU PHP binaries
php artisan native:install
Start development on a connected device
php artisan native:run
Force a full rebuild after any version upgrade
php artisan native:install --force

The nativephp/ directory generated by native:install is ephemeral. Add it to .gitignore immediately. It is fully regenerated on every install or upgrade. Committing it causes conflicts on collaborator machines and wastes repository space.

Building a mobile-ready Laravel application for your Mumbai business? Our team specializes in custom Laravel development and can help you ship web and mobile apps from one codebase.

Core Configuration: config/nativephp.php

NativePHP centralizes all mobile build settings in config/nativephp.php, auto-generated by native:install. Key configuration options cover app identity, runtime mode, iOS signing, and Android SDK targets:

// config/nativephp.php
return [
'app_id'      => env('NATIVEPHP_APP_ID', 'com.example.myapp'),
'app_version' => env('NATIVEPHP_APP_VERSION', 'DEBUG'),
'runtime' => [
'mode'                  => 'persistent',  // 'persistent' (v3.1+) or 'classic'
'reset_instances'       => true,
'gc_between_dispatches' => false,
],
'start_url'       => '/',
'deeplink_scheme' => 'myapp',
'ios' => [
'development_team' => env('NATIVEPHP_DEVELOPMENT_TEAM'),
'ipad'             => false,
],
'android' => [
'compile_sdk'      => env('NATIVEPHP_ANDROID_COMPILE_SDK', 36),
'min_sdk'          => env('NATIVEPHP_ANDROID_MIN_SDK', 33),
'target_sdk'       => env('NATIVEPHP_ANDROID_TARGET_SDK', 36),
'minify_enabled'   => true,
'shrink_resources' => true,
'obfuscate'        => false,
],
'cleanup_env_keys' => [
'APP_KEY', 'DB_PASSWORD',
],
];

The android section with compile_sdk, min_sdk, and target_sdk is mandatory from v3.1 onwards. Omitting it on v3.1 or later causes build errors that are difficult to diagnose because the error message references the native Gradle build, not your PHP code. The cleanup_env_keys array strips sensitive .env values before the binary is packaged -- always add every secret key here.

The Persistent PHP Runtime: 5 to 30ms Responses

The Persistent PHP Runtime, introduced in v3.1, is the most impactful performance improvement in NativePHP history. In classic mode, Laravel boots from scratch on every request, taking 200 to 300ms per response. In persistent mode, Laravel boots once and the kernel is reused across all subsequent requests, dropping response time to 5 to 30ms -- a ten-fold improvement that makes NativePHP apps feel genuinely fast on mid-range Android devices.

The tradeoff is that singleton state persists between requests within a session. Services that cache stale data can cause subtle bugs. The reset_instances configuration key (set to true) forces Laravel to re-resolve bound singletons between dispatches. Use gc_between_dispatches: true to run the PHP garbage collector between requests if you observe memory growth on long-running sessions.

The v3.3.0 release (May 8, 2026) added Jump: a live dev preview over a WebSocket bridge that enables hot module replacement during development. Changes to Blade templates or Vue components appear on the device without triggering a full Xcode or Gradle rebuild -- similar to Vite HMR for web projects. v3.3.5 (May 19, 2026) refined HMR behavior further.

Native Plugins and Available Device APIs

NativePHP v3.0 replaced the monolithic native layer with a modular plugin architecture. Every device API is now an individual plugin with its own PHP facade, JavaScript bridge, and native implementation. The fourteen core plugins available in v3.3.6 are:

• Biometrics -- Face ID, Touch ID, fingerprint authentication
• Browser -- In-app browser, deep link handling
• Camera -- Photo and video capture
• Device -- Device metadata: model, OS version, UUID
• Dialog -- Native alert, confirm, and prompt dialogs
• File -- Local file system access
• Firebase -- Push notifications via Firebase Cloud Messaging
• Geolocation -- GPS coordinates
• Microphone -- Audio recording
• Network -- Connectivity status (WiFi, cellular, offline)
• Scanner -- QR code and barcode scanning
• SecureStorage -- iOS Keychain / Android Keystore
• Share -- Native share sheet
• System -- Clipboard, haptics, vibration

Third-party plugins must be explicitly registered in NativeServiceProvider before native code is compiled. This is a deliberate security measure -- transitive Composer dependencies cannot silently inject native code into your binary.

// app/Providers/NativeServiceProvider.php
namespace App\Providers;

use Native\Mobile\Facades\NativeApp;
use Illuminate\Support\ServiceProvider;
class NativeServiceProvider extends ServiceProvider
{
public function boot(): void
{
NativeApp::allPlugins([
// Register third-party plugins explicitly here
]);
}
}

Biometrics Integration Example

use Native\Mobile\Facades\Biometrics;
use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Events\Biometric\Completed;

// Trigger the Face ID / fingerprint prompt
Biometrics::prompt();
// Handle the result in a Livewire component
#[OnNative(Completed::class)]
public function handleBiometric(bool $success)
{
if ($success) {
$secret = SecureStorage::get('vault_key');
$this->unlockVault($secret);
}
}

SecureStorage: iOS Keychain and Android Keystore

use Native\Mobile\Facades\SecureStorage;

SecureStorage::set('api_token', 'abc123xyz'); // returns bool
$token = SecureStorage::get('api_token'); // returns string|null
SecureStorage::delete('api_token'); // returns bool

On iOS, SecureStorage uses Keychain Services tied to the app bundle ID -- data persists through reinstalls if iCloud Keychain is enabled. On Android, the hardware-backed Keystore is used where available, and data is deleted on app uninstall. SecureStorage is suitable for tokens and small credentials only.

The UI Layer: Blade, Livewire, Vue, React, or Svelte

NativePHP does not mandate a specific UI framework. Your Laravel app renders HTML into a WebView. You can use Blade with Alpine.js, full Livewire reactive components, or a decoupled Vue or React SPA. These are the same modern Laravel frontends teams already use for web applications -- no new skills required.

For native navigation chrome, NativePHP provides EDGE Components: Top Bar, Bottom Navigation, Side Navigation, and icon sets. These components render using native UI primitives, giving the app a native look and feel without writing Swift or Kotlin. Tailwind CSS works inside the WebView exactly as it does on the web.

Security: What Every Developer Must Know

NativePHP's security model has four non-negotiable rules every developer must follow before shipping to the App Store or Play Store.

Per-Device APP_KEY Isolation

Since v3.0, NativePHP generates a unique APP_KEY for each device installation at first run, stored in the native Keystore or Keychain. Do not ship a shared APP_KEY in the binary. Data encrypted with Laravel's Crypt:: facade is device-specific and unrecoverable if the device is lost. Never sync Crypt-encrypted data to a remote server -- the keys will not match.

No Secrets in the Binary

Android APK files are ZIP archives. Any API key embedded in a compiled binary is extractable by anyone who downloads the APK. Use Android's Play Integrity API or Apple's App Attest -- the OS vouches for app legitimacy without embedding any shared secret in the binary.

The NativePHP security documentation recommends a defense-in-depth stack: (1) attestation handshake issuing 15-minute JWTs, (2) HMAC request signing with timestamp and nonce, (3) per-IP and per-device rate limiting, and (4) anomaly detection for traffic spikes.

Stripping Secrets Before Packaging

The cleanup_env_keys configuration array strips sensitive .env values before production builds are packaged. Always include APP_KEY, DB_PASSWORD, and every third-party API secret in this array. Failing to do so ships raw credentials inside the binary distributed to every user.

HTTPS is Mandatory

The NativePHP documentation states: "Always use HTTPS." All API communication between the on-device app and any remote backend must use TLS. Certificate pinning is recommended for additional transport security. OAuth2 with tokens under 48-hour expiration is the recommended authentication protocol. Never expose the APP_KEY through error tracking tools such as Sentry or Bugsnag.

Need a secure, scalable Laravel integration or custom web application for your business in Mumbai? We build integrations, automation pipelines, and custom portals that connect your systems seamlessly.

Deployment: iOS App Store and Google Play Store

iOS App Store Submission

1. Register your test device in your Apple Developer account and enable Developer Mode.
2. Bump the app version: php artisan native:release patch.
3. Run the package command with your distribution certificate, provisioning profile, and App Store Connect API key.

php artisan native:package ios 

--export-method=app-store 

--api-key-path=/path/to/AuthKey.p8 

--api-key-id=ABC123DEF 

--api-issuer-id=01234567-89ab-cdef-0123-456789abcdef 

--certificate-path=/path/to/distribution.p12 

--certificate-password=secret 

--provisioning-profile-path=/path/to/profile.mobileprovision 

--team-id=ABC1234567 

--upload-to-app-store

Mismatched provisioning profiles and entitlements are the most common cause of App Store rejection. Never commit .p8 API key files or .p12 certificates to version control.

Google Play Store Submission

1. Generate your signing keystore: php artisan native:credentials android (auto-adds the keystore to .gitignore).
2. Package as an Android App Bundle (AAB) for Play Store submission.

php artisan native:credentials android

php artisan native:package android 

--build-type=bundle 

--keystore=/path/to/my-app.keystore 

--keystore-password=pass 

--key-alias=my-app-key 

--key-password=pass 

--upload-to-play-store 

--play-store-track=internal 

--google-service-key=/path/to/service-account-key.json

Never commit .keystore files to Git. Verify the .gitignore entry exists before your first commit after credential generation.

Common Mistakes and How to Avoid Them

These ten mistakes from the NativePHP GitHub issue tracker and documentation cost developers the most time:

1. Not running --force after upgrading. Always run php artisan native:install --force after every version bump.
2. Committing the nativephp/ directory. It is a build artifact -- add it to .gitignore on day one.
3. Committing signing credentials. Never commit .keystore, .p8, or .p12 files.
4. Choosing non-ICU PHP binaries when using Filament. Filament requires the intl PHP extension. There is no in-place switch -- reinstall with ICU binaries.
5. Syncing Crypt-encrypted data off-device. Per-device APP_KEY makes cross-device decryption impossible.
6. Skipping NativeServiceProvider registration. In v3, plugins not registered are silently excluded -- no error message is shown.
7. Using WSL as the development environment. WSL is not supported. Install NativePHP natively on Windows.
8. Omitting the android config section on v3.1+. Missing compile_sdk, min_sdk, or target_sdk causes Gradle build failures.
9. Embedding API tokens in the binary. Use Play Integrity or App Attest instead.
10. Running native:run on iOS without device registration. The build fails at code-signing if the device is not registered with Developer Mode enabled.

NativePHP vs React Native vs Capacitor

NativePHP eliminates the hiring and reskilling cost for Laravel teams. The tradeoff is a younger framework with a smaller plugin ecosystem. React Native's native component rendering outperforms WebView for complex animations. For business apps, internal tools, and data-entry workflows in India, the 5 to 30ms response times of NativePHP's persistent runtime deliver a professional user experience.

Versioning Policy and Upgrade Path

NativePHP follows semantic versioning. Major versions contain breaking changes; minor and patch versions are drop-in upgrades. Key milestones:

• v1.10.4 (September 15, 2025) -- final v1 release
• v3.0.x -- Plugin architecture, MIT license, Packagist
• v3.1.x -- Persistent PHP Runtime (5 to 30ms), mandatory android config section
• v3.2.0 (April 1, 2026) -- Push notifications via Firebase, native:debug command
• v3.3.0 (May 8, 2026) -- Jump live preview, WebSocket hot reload
• v3.3.4 (May 11, 2026) -- PHP 8.3 support restored
• v3.3.6 (June 5, 2026) -- Current stable release

When migrating from v1 to v3, delete the nativephp.composer.sh entry from composer.json and remove credentials from auth.json. Then run php artisan native:install --force to regenerate the native project.

Testing and Verification

NativePHP development follows a three-stage cycle: dev preview, release test, and production package.

1. Dev preview: php artisan native:run -- runs on a physical device with Jump live reload in v3.3+.
2. Release test: php artisan native:run --build=release -- tests release configuration on device.
3. Debug: php artisan native:debug (v3.2.0+) -- surfaces runtime errors from the native shell.
4. Package: native:package ios [...] or native:package android [...].

NativePHP facades are mockable using standard Laravel patterns: Biometrics::fake(), SecureStorage::fake(). Run PHP business logic tests with php artisan test as you would any Laravel app. Device-specific behavior requires testing on a physical device or simulator.

Frequently Asked Questions

What PHP and Laravel versions does NativePHP support?

NativePHP v3.3.6 requires PHP 8.3 and supports Laravel 10, 11, 12, and 13. PHP 8.3 support was temporarily broken in early v3.3.x releases and was fully restored in v3.3.4 released on May 11, 2026. Always run the latest patch release to avoid this issue. Earlier NativePHP v1 releases supported a broader range of PHP versions, but v3 requires PHP 8.3 to use modern language features and typed properties across the framework.

Is NativePHP free to use in 2026?

Yes -- NativePHP has been free and open source under the MIT license since v3.0, released in early 2026. Prior to v3.0, the package required a paid commercial license purchased through a private Composer repository at nativephp.composer.sh. That private repository entry must be removed from composer.json when migrating to v3. The package is now available directly on Packagist at no cost for any project, commercial or otherwise.

Can NativePHP apps be submitted to the Apple App Store and Google Play Store?

Yes. NativePHP apps run a pre-compiled, bundled PHP interpreter -- they do not download or execute remote code at runtime, which satisfies both Apple and Google policies against dynamic code execution. Community developers report successful App Store and Play Store submissions as of 2026. Apple and Google's review policies can change, so always review the latest App Store Review Guidelines and Google Play Policy before submitting your app.

How does NativePHP handle app security?

NativePHP generates a unique APP_KEY per device installation stored in the native Keychain or Keystore, so Laravel-encrypted data is isolated to each device and cannot be decrypted on another device. Secrets must never be embedded in the binary because Android APK files are inspectable ZIP archives. For apps that call a remote Laravel API, use Android Play Integrity API or Apple App Attest to authenticate the app without embedding a shared secret. The cleanup_env_keys configuration array strips sensitive .env values before the binary is packaged for distribution.

How does NativePHP compare to React Native for a Laravel developer team?

NativePHP lets an existing Laravel PHP team ship mobile apps without learning JavaScript, TypeScript, Dart, Swift, or Kotlin, eliminating the cost of hiring or retraining mobile developers. React Native uses native UI components for smoother animations and more complex consumer UI interactions, while NativePHP renders in a WebView. For business apps, internal tools, and data workflows common in Mumbai and Indian enterprises, the 5 to 30ms response times of NativePHP's persistent runtime deliver a professional experience. React Native has a larger ecosystem having launched in 2015, compared to NativePHP mobile v1 which launched in May 2025.