Upgrade Guide

#High Impact Changes

• Remove the NativePHP Composer repository
• Plugin-based architecture
• Rebuild required

#Medium Impact Changes

• NativeServiceProvider
• Core APIs are now plugins
• New plugin management commands

#Low Impact Changes

• Bridge functions
• Command reference documentation
• Plugin marketplace

#Upgrading To 3.0 From 2.x

NativePHP for Mobile v3 introduces a plugin-based architecture that makes the entire native layer extensible. All core functionality continues to work as before, but the underlying system is now modular and open to third-party plugins.

#Remove the NativePHP Composer Repository

v3 no longer requires the private Composer repository or license authentication. Remove the nativephp.composer.sh repository from your composer.json:

"repositories": [
    {
        "type": "composer",
        "url": "https://nativephp.composer.sh"
    }
]

Delete the entire repositories block above (or just the NativePHP entry if you have other repositories).

You can also remove any stored credentials for nativephp.composer.sh from your auth.json if you have one.

Then update your version constraint and run the upgrade:

"require": {
    "nativephp/mobile": "~2.0.0" 
    "nativephp/mobile": "~3.0.0" 
}

composer update
php artisan native:install --force

#Plugin Architecture

v3 introduces a comprehensive plugin system. Native functionality is now delivered through plugins — including all the official core APIs you already use (Camera, Biometrics, Scanner, etc.). These continue to work exactly as before; you don't need to change how you call them.

The difference is that third-party developers can now create plugins that add new native functionality to your app. Plugins are standard Composer packages that include Swift (iOS) and Kotlin (Android) code alongside their PHP interface.

Read more about the plugin system in the Plugins documentation, or browse ready-made plugins on the NativePHP Plugin Marketplace.

#NativeServiceProvider

v3 introduces a NativeServiceProvider for registering third-party plugins. Publish it with:

php artisan vendor:publish --tag=nativephp-plugins-provider

This creates app/Providers/NativeServiceProvider.php. Any third-party plugins you install must be registered here before their native code is compiled into your app. This is a security measure to prevent transitive dependencies from automatically including native code without your consent.

php artisan native:plugin:register vendor/some-plugin

Core APIs provided by nativephp/mobile do not need to be registered manually — they are included automatically.

Read more about Using Plugins.

#Core APIs Are Now Plugins

All core APIs (Camera, Biometrics, Dialog, Scanner, Geolocation, etc.) are now implemented as plugins internally. The PHP facades and events you use remain the same — no changes to your application code are needed.

Browse the full list of available core plugins in the Plugins documentation.

#Plugin Management Commands

v3 adds several new Artisan commands for working with plugins:

#Bridge Functions

Plugins communicate with native code through bridge functions — a standardized pattern for calling Swift and Kotlin code from PHP via nativephp_call(). Each plugin declares its bridge functions in a nativephp.json manifest.

If you've been using the core APIs through their facades, nothing changes for you. Bridge functions are primarily relevant if you're building your own plugins.

Read more in the Bridge Functions documentation.

#Plugin Marketplace

Find ready-made plugins for common use cases, or get the Dev Kit to build your own. Visit the NativePHP Plugin Marketplace.

#Command Reference

v3 includes a comprehensive Command Reference documenting all native:* Artisan commands with their options and usage.

#Rebuild Required

After upgrading, you must rebuild your native application:

php artisan native:install --force
php artisan native:run

The --force flag ensures the nativephp directory is completely rebuilt with the v3 native project files.