Nativephp Mobile
Developmentnativephp-mobileNativephp 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
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:
- OS: macOS supports iOS + Android. Windows/Linux support Android only. WSL unsupported.
- Frontend stack: Livewire/Blade (
.blade.phpwithwire:,app/Livewire/) vs JavaScript (.vue/.jsx/.tsx,inertiajsinpackage.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
| Command | Purpose |
|---|---|
php artisan native:install | Install/upgrade native shell |
php artisan native:run ios/android | Build and launch on simulator/emulator |
php artisan native:watch | Hot reload during development |
php artisan native:jump | Quick restart without full rebuild |
php artisan native:tail | Stream device logs |
php artisan native:package | Package 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()dispatchesPhotoTaken - 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
idattributes - Add
nativephp-safe-areaclass 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:
| Package | Feature | Cost |
|---|---|---|
nativephp/mobile-browser | In-app browser, OAuth | Free |
nativephp/mobile-camera | Camera & photo picker | Free |
nativephp/mobile-dialog | Alerts & toasts | Free |
nativephp/mobile-device | Vibrate, flashlight, device info | Free |
nativephp/mobile-file | File move/copy | Free |
nativephp/mobile-microphone | Audio recording | Free |
nativephp/mobile-network | Network status | Free |
nativephp/mobile-share | Share URLs & files | Free |
nativephp/mobile-system | Open app settings | Free |
nativephp/mobile-scanner | QR/barcode scanning | $49 |
nativephp/mobile-biometrics | Face ID / Touch ID | $49 |
nativephp/mobile-geolocation | GPS location | $49 |
nativephp/mobile-secure-storage | Keychain/Keystore | $49 |
nativephp/mobile-firebase | Push notifications | Proprietary |
For authoring plugins: references/plugin-best-practices.md
Common Pitfalls
- Missing
NATIVEPHP_APP_IDin.envbeforenative:install - Suggesting iOS commands on Windows/Linux
- Not cleaning up event listeners with
off()inonUnmounted - Missing unique
idon EDGE component children - Forgetting
nativephp-safe-areaclass on body - Using core facades for plugin features (e.g.
Scannerrequiresnativephp/mobile-scanner) - Forgetting
nativephpMobile()/nativephpHotFile()invite.config.js - Not passing
--mode=iosor--mode=androidtonpm run build - Not fetching v3 docs before implementing — use WebFetch with URLs from references/available-docs.md