Upgrade Guide

Upgrading To 4.0 From 3.x#

v4's headline is SuperNative — fully native UI. Most of the release is additive, but there are two breaking changes to your dependencies: the minimum PHP version has gone up, and a handful of APIs that used to be separate plugins are now core built-ins.

PHP 8.4 is now the minimum#

v3 ran on PHP 8.3. nativephp/mobile v4 requires PHP 8.4 or later, so upgrade your CLI PHP before running composer update or Composer will refuse to resolve. See Environment Setup for the full list of requirements.

Device, Dialog, File and System are now built in#

Device, Dialog, File, and System now ship inside nativephp/mobile — their native bridge functions are registered by core. nativephp/mobile v4 declares a Composer conflict with the four standalone plugins, so composer update will refuse to resolve until you remove them.

The quickest way is the --core-v4 flag, which finds whichever of the four you have installed, unregisters each from your NativeServiceProvider, and removes them all in a single composer remove:

php artisan native:plugin:uninstall --core-v4

Add --force to skip the confirmation prompt — handy when sweeping across several apps:

php artisan native:plugin:uninstall --core-v4 --force

Or uninstall them one at a time (this also unregisters each from your NativeServiceProvider):

php artisan native:plugin:uninstall nativephp/mobile-device
php artisan native:plugin:uninstall nativephp/mobile-dialog
php artisan native:plugin:uninstall nativephp/mobile-file
php artisan native:plugin:uninstall nativephp/mobile-system

Or remove them directly with Composer if they were never registered in your NativeServiceProvider:

composer remove nativephp/mobile-device nativephp/mobile-dialog nativephp/mobile-file nativephp/mobile-system

No application code changes are required. The Native\Mobile\Facades\{Device, Dialog, File, System} facades and their events (ButtonPressed, etc.) are unchanged. Their docs now live in The Basics section: Device, Dialog, File, and System.

The Vite dev server is now opt-in#

native:run and native:watch no longer start the Vite dev server automatically. If you rely on Vite HMR during development (React/Vue/Tailwind, etc.), add the --vite flag:

php artisan native:watch --vite
php artisan native:run --watch --vite

The old --no-vite flag still exists but is now redundant — Vite is off unless you ask for it. If you have --no-vite in your scripts, you can drop it.

Update your dependency#

"require": {
    "nativephp/mobile": "~3.1.0" 
    "nativephp/mobile": "~4.0.0" 
}

composer update
php artisan native:install --force

For Plugin Developers#

Widen the constraint in your plugin's composer.json to allow the new release:

"require": {
    "nativephp/mobile": "^3.0" 
    "nativephp/mobile": "^3.0|^4.0" 
}

If your plugin depends on any of the conflicting plugins above, remove them from your composer.json's require.