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

Chapter project: environment sign-off and first simulator run

This chapter project runs on the same app you built in Chapter 1 — the Laravel project with mobile-home and NativePHP installed. You are not creating a new repository.

You have now: custom home screen on Jump.
You will ship: that same app booting in an iOS Simulator or Android emulator via php artisan native:run.

Solution on GitHub

Click here to see the GitHub solution

Before you start

  • Chapter 1 project complete (mobile-home loads in Jump)
  • Xcode (Mac) or Android Studio installed per lessons 2.4–2.5
  • NATIVEPHP_APP_ID set in .env

Step 1: Sign-off checklist

Create docs/environment-sign-off.md in your project (optional but recommended for your capstone):

# Environment sign-off — Field Notes

- [ ] PHP 8.3+ (`php -v`)
- [ ] Composer 2.x (`composer -V`)
- [ ] Node 20+ (`node -v`)
- [ ] Laravel loads in browser
- [ ] Jump connects on same Wi-Fi
- [ ] Xcode or Android Studio SDK installed
- [ ] `php artisan native:install` completed
- [ ] `nativephp/` in `.gitignore`

Tick each item on your machine before continuing.

Step 2: Build for simulator

From your project root:

php artisan native:run

Follow the prompts:

  • iOS: pick a simulator (e.g. iPhone 16)
  • Android: pick an AVD you created in Android Studio

First compile can take several minutes. Subsequent runs are faster.

Step 3: Verify the packaged app

When the simulator opens:

  1. You see your branded or default shell, then your WebView content.
  2. The home route shows "It works on mobile" (or your Chapter 1 heading) — not the Laravel welcome page.
  3. Quit and re-open the app; it still loads offline (PHP is on-device in packaged builds).

Step 4: Compare Jump vs native:run

Surface When to use
Jump Daily Laravel/UI iteration
native:run Test packaged behaviour, icons, splash (Ch 3+), plugins

Keep using Jump for most development. Use native:run when you need the real app binary.

If it goes wrong

Symptom Fix
No simulators listed Open Xcode → Settings → Platforms; or Android Studio → Virtual Device Manager
Gradle / CocoaPods errors Re-run php artisan native:install --force
Blank WebView Check storage/logs/laravel.log inside the project; fix PHP errors in browser first
Wrong app ID Confirm NATIVEPHP_APP_ID in .env before install

Remember

Chapter 3 adds icon and splash to this same project. Do not fork a new Laravel app.

From Using Native PHP — Environment setup and development workflow