Originally published on php-apps.learnio.dev — part of the Using Native PHP course. View this lesson on the original site.

Exploring the Plugin Model in NativePHP Mobile v3

In NativePHP Mobile v3, native features are integrated as Composer packages, which include PHP facades alongside Swift and Kotlin code. This approach eliminates the need to fork the core for adding functionalities like camera access, biometrics, or custom SDK integrations. Instead, you simply select a plugin type, install it, register it, and rebuild your application.

Where to Find Plugins

Start with these official entry points:

Official Plugins

Official plugins are developed and published by the NativePHP team. These include core capabilities such as camera, biometrics, scanner, and geolocation, making them the safest choice for production-ready native behaviour. You can browse official and first-party packages on the Plugin Marketplace. For premium official plugins, you will need to install them via NativePHP's private Composer repository after configuring your credentials. Refer to the Using plugins guide for setup instructions regarding plugins.nativephp.com.

Community Plugins

Community plugins are created by other developers and can often be found on Packagist or linked from the plugin directory. While they can quickly fill in gaps (e.g., for contacts, NFC, in-app updates), it's crucial to review their maintenance status, permissions, and support before using them in production. Here are some key points to check:

  • Clear listing of required Android/iOS permissions.
  • Stability of the vendor namespace on Packagist.
  • Comprehensive documentation of facade methods and events in the README.
  • Explicit registration in NativeServiceProvider.

You can submit your own community plugin for listing through the marketplace's "Submit Your Plugin" flow, accessible from nativephp.com/plugins/marketplace.

Custom Plugins

Custom plugins are Composer packages that you own, suitable for proprietary SDKs, internal hardware, or features not covered by existing marketplace packages. They share the same structure as official plugins, which includes a PHP service provider, manifest, Swift/Kotlin bridge code, and explicit registration.

When creating custom plugins, refer to the Creating plugins guide and the Plugin Dev Kit linked from nativephp.com/plugins for assistance.

How the Three Types Fit Together

flowchart TD
    A[Need native capability] --> B{Exists officially?}
    B -->|Yes| C[Install from Plugin Marketplace]
    B -->|No| D{Community plugin fits?}
    D -->|Yes| E[Install via Composer + review README]
    D -->|No| F[Build custom plugin package]
    C --> G[Register in NativeServiceProvider]
    E --> G
    F --> G
    G --> H[php artisan native:plugin:list]
    H --> I[php artisan native:run]

Registration is crucial for security, as third-party native code will not be compiled until you register the package. Core APIs bundled with nativephp/mobile do not require manual registration.

Try it with Runnable Commands

To get started, pick a plugin from the marketplace, then install and register it using the following commands:

composer require nativephp/mobile-biometrics
php artisan vendor:publish --tag=nativephp-plugins-provider
php artisan native:plugin:register nativephp/mobile-biometrics
php artisan native:plugin:list
php artisan native:run

For a premium marketplace plugin, ensure you configure the private repository first (credentials from your purchased-plugins dashboard):

composer config repositories.nativephp-plugins composer https://plugins.nativephp.com
composer config http-basic.plugins.nativephp.com [email protected] your-license-key
composer require vendor/nativephp-premium-plugin
php artisan native:plugin:register vendor/nativephp-premium-plugin

Make sure to use the exact package name from the directory, replacing vendor/nativephp-premium-plugin with the name shown on the plugin page.

If It Goes Wrong

  • If the plugin is missing from native:plugin:list, confirm that native:plugin:register ran and that app/Providers/NativeServiceProvider.php includes the vendor.
  • If the build succeeds but the native call fails, consult the plugin README on its marketplace or GitHub page for permissions and facade usage.
  • If Composer cannot find a premium plugin, check the plugins.nativephp.com repository and your HTTP basic credentials in auth.json.
  • If you are still stuck, compare your steps with the Using plugins guide.

Remember

  • Official directory: nativephp.com/plugins — marketplace: nativephp.com/plugins/marketplace.
  • Install with Composer, register with native:plugin:register, verify with native:plugin:list, and rebuild with native:run.
  • Community plugins require the same registration discipline as custom ones — never assume that native code will work simply because Composer autoloaded PHP files.

From Using Native PHP — Introduction and first screen on mobile