OpenParable
Skip to content
← Back to skills

Nativephp Mobile

Development
nativephp-mobile

Nativephp Mobile is an Agent Skill for development published in the NativePHP/mobile-air repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/NativePHP/mobile-air/blob/HEAD/resources/boost/skills/nativephp-mobile/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/nativephp-mobile, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

CommandPurpose
php artisan native:installInstall/upgrade native shell
php artisan native:run ios/androidBuild and launch on simulator/emulator
php artisan native:watchHot reload during development
php artisan native:jumpQuick restart without full rebuild
php artisan native:tailStream device logs
php artisan native:packagePackage for App Store / Play Store

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:

PackageFeatureCost
nativephp/mobile-browserIn-app browser, OAuthFree
nativephp/mobile-cameraCamera & photo pickerFree
nativephp/mobile-dialogAlerts & toastsFree
nativephp/mobile-deviceVibrate, flashlight, device infoFree
nativephp/mobile-fileFile move/copyFree
nativephp/mobile-microphoneAudio recordingFree
nativephp/mobile-networkNetwork statusFree
nativephp/mobile-shareShare URLs & filesFree
nativephp/mobile-systemOpen app settingsFree
nativephp/mobile-scannerQR/barcode scanning$49
nativephp/mobile-biometricsFace ID / Touch ID$49
nativephp/mobile-geolocationGPS location$49
nativephp/mobile-secure-storageKeychain/Keystore$49
nativephp/mobile-firebasePush notificationsProprietary

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