From e6ffa68aea521410e2dea40cf1f0b4e073204ca2 Mon Sep 17 00:00:00 2001 From: Simon Hamp Date: Fri, 23 Oct 2026 11:22:03 +0100 Subject: [PATCH] Explain how the version and build number decide when code updates The app only extracts its bundled Laravel code when the version number or build number changes, so a rebuild with the same pair keeps running the old code. Say that plainly, and tell people to bump NATIVEPHP_APP_VERSION_CODE before each build they install. Also fix the claim that native:release bumps the build number. It only bumps the version. native:package bumps the build number, and native:run never does. Co-Authored-By: Claude Opus 5.5 --- .../mobile/4/getting-started/configuration.md | 22 +++++++++++-------- .../mobile/4/getting-started/development.md | 4 ++++ .../docs/mobile/4/publishing/introduction.md | 10 +++++++-- .../views/docs/mobile/4/publishing/ios.md | 4 ++-- 4 files changed, 27 insertions(+), 13 deletions(-) diff --git a/resources/views/docs/mobile/4/getting-started/configuration.md b/resources/views/docs/mobile/4/getting-started/configuration.md index 33c8b0b72..3934c8a0f 100644 --- a/resources/views/docs/mobile/4/getting-started/configuration.md +++ b/resources/views/docs/mobile/4/getting-started/configuration.md @@ -34,11 +34,11 @@ So it's not something you want to be changing very often. ## `NATIVEPHP_APP_VERSION` -The `NATIVEPHP_APP_VERSION` environment variable sets your app's **public version string** - what shows up in App Store -and Play Store listings, and on-device under "Settings → Apps" (or equivalent). It maps to `CFBundleShortVersionString` -on iOS and `versionName` on Android. +The `NATIVEPHP_APP_VERSION` environment variable sets your app's **version number** - the public version string that +shows up in App Store and Play Store listings, and on-device under "Settings → Apps" (or equivalent). It maps to +`CFBundleShortVersionString` on iOS and `versionName` on Android. -Its companion, `NATIVEPHP_APP_VERSION_CODE`, sets the **internal build number** the stores use to distinguish uploads +Its companion, `NATIVEPHP_APP_VERSION_CODE`, sets the **build number** the stores use to distinguish uploads (`CFBundleVersion` on iOS, `versionCode` on Android). Users don't normally see this one, but the stores require it to increase with every upload. @@ -46,9 +46,8 @@ increase with every upload. latest code without needing to bump a version number by hand. You only need to change this when you're cutting a release build for distribution. Rather than editing your `.env` -manually, use the -[`native:release` command](commands#nativerelease), which bumps the version (and build -number) for you. +manually, use the [`native:release` command](commands#nativerelease) to bump the version number. +[`native:package`](commands#nativepackage) increments the build number each time it packages your app. +Because of this, two builds with the same version number and build number count as the same build. If you set a version +and then rebuild and install over an existing copy of your app without changing either number, the app keeps running +the code it extracted before. Bump `NATIVEPHP_APP_VERSION_CODE` before each build you install. `native:run` doesn't +change it for you. + ## Persistent Runtime NativePHP uses a persistent PHP runtime that boots Laravel once and reuses the kernel across all subsequent requests. diff --git a/resources/views/docs/mobile/4/getting-started/development.md b/resources/views/docs/mobile/4/getting-started/development.md index 3e8542536..332a87224 100644 --- a/resources/views/docs/mobile/4/getting-started/development.md +++ b/resources/views/docs/mobile/4/getting-started/development.md @@ -107,6 +107,10 @@ Your app will boot a little slower, but you will find that everything looks as y It's better than scratching your head for an hour trying to figure out why your changes aren't showing! +If you do set a version, the app only refreshes when the version number or the build number changes, so bump +`NATIVEPHP_APP_VERSION_CODE` before each build. See +[how NativePHP uses these values](configuration#codenativephp-app-versioncode). + ## Working with Xcode or Android Studio diff --git a/resources/views/docs/mobile/4/publishing/introduction.md b/resources/views/docs/mobile/4/publishing/introduction.md index c99b148ef..5b0b81d28 100644 --- a/resources/views/docs/mobile/4/publishing/introduction.md +++ b/resources/views/docs/mobile/4/publishing/introduction.md @@ -66,7 +66,7 @@ php artisan native:release patch ``` You can pass `patch`, `minor`, or `major` depending on the type of release you're cutting. This updates -`NATIVEPHP_APP_VERSION` in your `.env` and increments the build number for you. +`NATIVEPHP_APP_VERSION` in your `.env`. ### Versioning @@ -83,7 +83,13 @@ The app version is managed via the `NATIVEPHP_APP_VERSION` key in your `.env`. Both the Google Play Store and Apple App Store require your app's build number to increase for each release you submit. The build number is managed via the `NATIVEPHP_APP_VERSION_CODE` key in your `.env`. You don't need to manage this -yourself — running `native:release` automatically increments the build number and persists it back to your `.env`. +yourself for store builds: `native:package` increments the build number and persists it back to your `.env`. + +The build number also decides whether a device picks up your new code. Together with the version number, it identifies +a build, and the app only unpacks its bundled Laravel code when that pair changes. A release build installed over a +previous one with the same version and build number keeps running the previous code. `native:run --build=release` +doesn't increment the build number, so bump `NATIVEPHP_APP_VERSION_CODE` yourself before testing a new release build +on a device that already has one installed. ### Run a `release` build diff --git a/resources/views/docs/mobile/4/publishing/ios.md b/resources/views/docs/mobile/4/publishing/ios.md index 30e3cef69..9209d8926 100644 --- a/resources/views/docs/mobile/4/publishing/ios.md +++ b/resources/views/docs/mobile/4/publishing/ios.md @@ -196,8 +196,8 @@ php artisan native:package ios \ php artisan native:release patch ``` -Build numbers (`NATIVEPHP_APP_VERSION_CODE`) are incremented automatically based on your `.env`, so you don't have to -manage them by hand. +Build numbers (`NATIVEPHP_APP_VERSION_CODE`) are incremented automatically by `native:package`, so you don't have to +manage them by hand for App Store builds. ## Artifact Locations