nativephp-mobile

name: nativephp-mobile description: "Builds native iOS and Android apps with PHP & Larvel. Activate when using native device APIs (camera, dialog, biometrics, scanner, geolocation, push notifications), EDGE components (bottom-nav, top-bar, side-nav), #nativephp JavaScript imports, native mobile events, NativePHP Artisan commands (native:run, native:install, native:watch), deep links, secure storage, or mobile app deployment."

NativePHP Mobile v3

Documentation

Before implementing any feature, fetch the relevant docs using WebFetch. Find the right URL in references/available-docs.md.

WebFetch("https://nativephp.com/docs/mobile/3/apis/camera", "Explain Camera API methods, events, and fluent builder options")

Build Commands — Tell the User, Don't Run

Never auto-run these commands. Always tell the user to run them manually:

npm run build -- --mode=ios      # or --mode=android
php artisan native:run ios       # or android
php artisan native:watch
./native open
./native watch

Environment Detection

Before suggesting commands, determine:

1. OS: macOS supports iOS + Android. Windows/Linux support Android only. WSL unsupported.
2. Frontend stack: Livewire/Blade (.blade.php with wire:, app/Livewire/) vs JavaScript (.vue/.jsx/.tsx, inertiajs in package.json).

Required Environment Variables

Set in .env before php artisan native:install:

NATIVEPHP_APP_ID=com.yourcompany.yourapp
NATIVEPHP_APP_VERSION="DEBUG"
NATIVEPHP_APP_VERSION_CODE="1"
# Optional for iOS:
NATIVEPHP_DEVELOPMENT_TEAM=XXXXXXXXXX

Artisan Commands Reference

HMR with Vite works when npm run dev runs alongside native:run.

Vite Configuration

import { nativephpMobile, nativephpHotFile } from './vendor/nativephp/mobile/resources/js/vite-plugin.js';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
            hotFile: nativephpHotFile(),
        }),
        tailwindcss(),
        nativephpMobile(),
    ]
});

JavaScript Usage (Vue/React/Inertia)

import { camera, dialog, scanner, biometric, on, off, Events } from '#nativephp';

await camera.getPhoto();
await dialog.alert('Title', 'Message');
await scanner.scan().prompt('Scan ticket').formats(['qr', 'ean13']);
await biometric.prompt().id('auth-check');

Event handling — always clean up in onUnmounted:

const handler = (payload) => { /* handle */ };
on(Events.Camera.PhotoTaken, handler);

// onUnmounted:
off(Events.Camera.PhotoTaken, handler);

PHP Usage (Livewire/Blade)

Core Facades (Native\Mobile\Facades): Camera, Dialog, Biometrics, Network, SecureStorage, File, Share, Haptics, System, Device

Plugin Facades (separate packages): Browser, Scanner, Microphone, Geolocation, PushNotifications

use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Events\Camera\PhotoTaken;

#[OnNative(PhotoTaken::class)]
public function handlePhoto(string $path): void
{
    // Process photo at $path
}

Event Handling

• Sync returns directly: SecureStorage::get(), Network::status()
• Async dispatches events: Camera::getPhoto() dispatches PhotoTaken
• Custom events: ->event(CustomEvent::class) (PHP) or .event('App\\Events\\Custom') (JS)
• Events dispatch to both JS and PHP simultaneously

EDGE Components (Native UI)

EDGE renders Blade components as native UI. Works with both Livewire and Inertia (layout is Blade).

• Prefix: native:bottom-nav, native:top-bar, native:side-nav
• Child items require unique id attributes
• Add nativephp-safe-area class to body for notch handling

<native:bottom-nav>
    <native:bottom-nav-item id="home" icon="home" label="Home" :url="route('home')" />
    <native:bottom-nav-item id="profile" icon="person" label="Profile" :url="route('profile')" />
</native:bottom-nav>

Plugin System (v3)

Modular plugin architecture — device features as separate Composer packages:

For authoring plugins: references/plugin-best-practices.md

Common Pitfalls

• Missing NATIVEPHP_APP_ID in .env before native:install
• Suggesting iOS commands on Windows/Linux
• Not cleaning up event listeners with off() in onUnmounted
• Missing unique id on EDGE component children
• Forgetting nativephp-safe-area class on body
• Using core facades for plugin features (e.g. Scanner requires nativephp/mobile-scanner)
• Forgetting nativephpMobile() / nativephpHotFile() in vite.config.js
• Not passing --mode=ios or --mode=android to npm run build
• Not fetching v3 docs before implementing — use WebFetch with URLs from references/available-docs.md