Mobile Laravel Package

Technical Evaluation

Architecture fit. NativePHP for Mobile ("SuperNative" v4) embeds a PHP runtime inside a native iOS/Android app. UI is composed of NativeComponent PHP classes registered via Route::native(), rendering EDGE Blade elements that compile down to SwiftUI on iOS and Jetpack Compose on Android. Critically, native screens do not use a web view — this is a screen framework, not a renderer. That distinction drives the whole evaluation: it is a good fit for form-and-list business apps (field ops, internal tooling, customer companion apps) built by a team whose depth is Laravel rather than mobile, and a poor fit for anything graphics-heavy, latency-sensitive, or dependent on deep platform SDK integration.

The strongest architectural argument is the single-codebase, two-surface shape: mobile screens live in routes/mobile.php behind a native-context check while the existing web deployment serves the same Laravel app. That is a materially cheaper operating model than a parallel React Native or Swift team, and it keeps one domain layer, one auth model, one test suite.

Integration feasibility. Bootstrapping is well-trodden: composer create-project nativephp/mobile-starter, then native:install. Two feasibility gates matter more than they look:

1. The plugin chain is load-bearing. Core ships no renderers — every element including column and text comes from nativephp/mobile-ui. native:plugin:list must show it registered. This is documented as the single most common setup failure and the cause of blank screens. A dependency graph where the headline package is non-functional standalone is a real architectural coupling to plan around.
2. Build-time-baked configuration. NATIVEPHP_DEEPLINK_SCHEME and NATIVEPHP_APP_ID are compiled in; adding them later costs a full rebuild. Environment/config decisions that normally live in .env become release artifacts. That needs to be in the project's day-one checklist, not discovered in sprint three.

Technical risk. Ranked by what would actually stop a programme:

• License (NOASSERTION) — highest-priority unknown. The repo license file is unrecognised by GitHub, and native:install fetches runtime plus nativephp/{ios,android} artifacts distributed outside the repo. The terms governing those binaries may differ from the repository's. This must be resolved with procurement/legal before any code investment.
• Bespoke abstraction surface. EDGE, theme tokens, generated icon enums, and a plugin event convention are all package-specific knowledge. None transfers to standard mobile skills; all of it is upstream-versioned. Documentation lives at nativephp.com/docs/mobile/4/.
• Security model requires real review. The package's own AGENTS.md states that web-view script can reach /_native/api/* endpoints and must be treated as untrusted, and documents authenticated (HMAC-signed or encrypt-sealed) transport lanes for unserialize() boundaries with purpose-binding and hash_equals verification. That is a mature design, but it also tells you the attack surface is non-trivial and the team must not add serialized transport casually.
• Adoption signals are weak or misleading. 1,212 stars but 0 dependents — integration happens through the starter template rather than direct composer require, so dependents understates reality while stars overstates it. Overall score (48/100, opportunity 57/100) reads as "promising, unproven." The 2026-10-29 last-release date is anomalous and should be reconciled against the actual package registry before being used in any planning artifact.
• Breadth of surface. The 4.6.0 changelog alone spans iOS 26 toolbar hit-testing, Android keystore password mangling, Windows path separators, Play Store review commits, and callback parser corruption. Fast cadence and a large contributor base are healthy signals, but they also mean many small platform-specific behaviours to absorb.

Key questions to resolve before committing

• What are the commercial terms and redistribution rights for the nativephp/{ios,android} runtime artifacts, and does the NOASSERTION license cover production distribution on both stores?
• Is nativephp/mobile-ui (and any renderer plugin we need) maintained by the same vendor, on the same release cadence, under the same terms?
• What is the supported-version matrix (PHP, Laravel, mobile, mobile-ui, runtime, Xcode, Android SDK/JDK), and what is the vendor's deprecation policy?
• Who owns a native crash our team cannot diagnose — is there a paid support tier, or is it community issues?
• Can we build, sign, and ship both platforms from our existing CI, and what does that add in runner cost?
• What is the app-store release story for Play Store "commit changes for review" flows and Apple review turnaround?

Integration Approach

Stack fit. Laravel + Blade + Livewire familiarity is directly transferable; no Node/TypeScript toolchain, no Swift or Kotlin required for the supported element set. Local SQLite and file storage handle offline-first requirements without new infrastructure. The notable infrastructure addition is a macOS build host with Xcode for iOS; Android needs the SDK/JDK. Windows-hosted builds are evidently supported but have historically been the source of path-separator bugs — treat macOS as the primary build environment and Windows as secondary.

Migration path. Do not port existing Livewire/Inertia screens. The stated scoping rule is the right one: anything that only works as a web view is not ready for the mobile roadmap. The recommended path is a net-new mobile surface on the existing Laravel app — new NativeComponent screens in routes/mobile.php, sharing models, actions, and auth with the web app, with native:web-view reserved for embedding genuinely external content inside a native screen. This keeps the web product untouched and gives a clean rollback: deleting the mobile routes costs nothing.

Compatibility. Pin the entire chain — nativephp/mobile, nativephp/mobile-ui, nativephp/ios, nativephp/android — as an explicit version set in composer.lock, and pin the resolved runtime. Upgrades are scheduled work, not background noise: 4.6.0 shipped ~28 PRs including behavioural fixes (keyboard dismissal semantics, border precedence, Play Store commit handling) that can change rendering or release behaviour without a major version bump. Budget a quarterly upgrade window with a full build/screenshot regression pass each time.

Sequencing (recommended)

1. Week 0 — commercial and legal. License, runtime distribution terms, support tier. Stop here if unresolved.
2. Week 1 — environment proof. Scaffold from the starter, native:install, verify native:plugin:list shows the UI plugin, publish config/native-ui.php, generate icon enums, set NATIVEPHP_APP_ID and NATIVEPHP_DEEPLINK_SCHEME immediately.
3. Week 1–2 — vertical slice. One list → detail flow as a NativeComponent with a native:icon and theme-token styling. This single screen exercises plugin registration, icon generation, tokens, routing, and the build/verify loop — the cheapest possible viability proof.
4. Week 2–3 — automate the loop in CI. Wire native:run --json, native:screenshot --json, and native:tail <os> --fatals --json into a pipeline. 4.6.0's ability to build a simulator app without a running simulator is what makes this affordable; native-error-screen exception reporting is what makes it meaningful rather than exit-code theatre.
5. Week 4+ — breadth. Remaining screens, deep-link-driven navigation tests, then store submission for an internal or TestFlight/closed-track release before any public launch.

Operational Impact

Maintenance. Ongoing cost is dominated by upstream tracking, not by code we write. Expect a quarterly upgrade cycle plus ad-hoc patches for platform OS releases (iOS 26 chrome and hit-testing fixes are already in the changelog). Design tokens in config/native-ui.php and generated icon enums keep restyling to a config edit rather than a grep-and-replace — a real maintenance dividend if the discipline holds. Never hand-edit nativephp/ios or nativephp/android; they are generated.

Support. In-house support depth is intentionally thin: no Swift/Kotlin means platform-level defects are escalated upstream or to the community. Partially mitigated by genuinely good diagnostics — native:tail <os> --lines=100 --json for anything thrown after Laravel boots, native:tail <os> --fatals --json for boot fatals, with exception.app_frame pointing at the first line in our own code. The operational trap is documented and worth repeating in the runbook: a clean laravel.log is not evidence the app booted. ok:false, stage:verify means built-but-not-running, and the log will typically be empty.

Scaling. Scaling is not a server concern — it is a build-farm and headcount concern. Per-developer and per-CI-job costs: macOS runners, simulator/emulator capacity, and build minutes (first build roughly ten minutes; incremental far less). Two hard constraints to plan team throughput around: one rebuild at a time per app repo, and never run two agents against the same app repo. That caps parallelism per repository regardless of team size and should shape how work is partitioned (device-claim files like nativephp/agent-device.json exist precisely to arbitrate this). Staffing scales by hiring Laravel developers, not mobile engineers — a large, available labour pool — but concentrates risk in one framework rather than distributed native skills.

Failure modes to instrument

The "booted" definition should be codified in the pipeline, not left to judgement: native:run --json returns ok:true and native:status --json shows running:true seconds later and the screenshot is not the red error screen. Anything less is not a green build.

Ramp-up. A competent Laravel developer reaches a verified list → detail screen in roughly one to two working days once the environment is up; environment bring-up itself is the larger risk than code. Training materials are unusually strong for a package of this age — a starter template, a documented agent build/verify loop, and an AGENTS.md with real security guidance. Budget two to three sprints before the team is independently productive across both platforms, and expect one person to become the named owner of the build toolchain and upstream upgrade cycle. That specialisation is the team's single point of failure and should be a deliberate staffing decision, not an accident.