Originally published on php-apps.learnio.dev — part of the Using Native PHP course. View this lesson on the original site.
After install: what Chapter 1 created
You already installed NativePHP in Chapter 1. Lessons 1.7 and 1.8 walked through:
composer require nativephp/mobile
php artisan native:install
php artisan native:jump
You set NATIVEPHP_APP_ID in .env before running the installer. By the time you reach Chapter 2, that work should be done — this lesson explains what landed on disk and what to adjust before your first native:run on a simulator (lesson 2.10).
If you skipped Chapter 1 or started fresh here, run those three steps first, then continue below.
Docs: Configuration, Installation
The nativephp/ directory
php artisan native:install generates a nativephp/ folder with the iOS and Android shell projects. Treat it as build output:
- Add
nativephp/to.gitignoreif it is not already there. - Do not hand-edit files inside unless the docs tell you to — upgrades and re-installs can overwrite them.
- If install fails halfway or you upgrade the package, re-run with
--force:
php artisan native:install --force
config/nativephp.php
The installer publishes config/nativephp.php. Most values read from .env — the important ones you already set:
NATIVEPHP_APP_ID=com.yourcompany.fieldnotes
That identifier becomes your iOS bundle ID and Android application ID. Pick it once and keep it; changing it later affects store listings and signing.
Open config/nativephp.php and skim the keys. You do not need to memorise every option now. For this chapter, note:
- App identity —
app_id, version, and version code (used when you ship in Chapter 9). - Start URL — which Laravel route loads first in the packaged app (your Chapter 1
/→mobile-homeroute is fine). cleanup_env_keys— env vars stripped from the bundle before release (Chapter 7 goes deeper on secrets).
If your config file is missing keys after an upgrade, compare with vendor/nativephp/mobile/config/nativephp.php or republish:
php artisan vendor:publish --tag=nativephp-mobile-config --force
Using --force overwrites your copy — back up any custom values first.
ICU-enabled PHP binaries
During install you may be asked to choose ICU-enabled PHP binaries. Say yes if you use Filament, heavy intl formatting, or anything that needs the ICU extension inside the on-device runtime. Otherwise the default build is smaller and fine for Field Notes at this stage.
If you chose wrong, run php artisan native:install --force and pick the other option.
Verify install without repeating it
From your project root:
php artisan list native
You should see native:jump, native:run, native:watch, native:install, and related commands.
Confirm .env still has your app ID:
grep NATIVEPHP_APP_ID .env
Confirm Jump still works:
php artisan native:jump
If all three pass, you are ready for the rest of Chapter 2 — network tuning (2.7), hot reload (2.8), and when to switch to native:run (2.9).
If it goes wrong
| Symptom | Likely fix |
|---|---|
native:* commands missing |
Run composer require nativephp/mobile again, then php artisan native:install |
| Install complains about app ID | Set NATIVEPHP_APP_ID=com.yourcompany.appname in .env before install |
nativephp/ out of sync after upgrade |
php artisan native:install --force |
| Config keys missing | Compare with vendor default or republish the config tag |
Remember
Chapter 1 gets NativePHP onto your machine and your phone via Jump. Chapter 2 hardens the environment for packaged simulator builds. You install once; this lesson is about understanding and verifying what that install produced.
From Using Native PHP — Environment setup and development workflow