Mobile Laravel Package

Product Decisions This Supports

1. "Mobile app vs. responsive web" — the resourcing question, not just the tech question. The real blocker for most Laravel product teams isn't whether a mobile app is valuable, it's that shipping one means hiring Swift/Kotlin/React Native capacity you don't have. NativePHP collapses that into a staffing decision: can the existing PHP team own the mobile surface? If yes, the roadmap item moves from "next fiscal year, pending headcount" to "next quarter." That is the decision this package most directly unlocks.

2. Build vs. buy vs. agency — with a defensible cost model. Use it to model three options side by side: (a) contract agency for a native app, (b) hire 1–2 mobile engineers, (c) existing team ships with NativePHP. Option (c) trades a lower headcount cost for ecosystem/vendor risk — quantify both sides rather than defaulting to "we need real native devs."

3. Roadmap sequencing: companion app as a fast-follow, not a v2 rewrite. Because screens are PHP classes (NativeComponent) rendered from Blade and the app can share the same Laravel codebase, domain logic, Eloquent models, and SQLite storage, a mobile companion can ship incrementally against an existing product. This supports committing to "mobile in H2" in a planning cycle instead of "mobile after the platform rewrite."

4. Scope selection — what classes of feature are safely in the mobile roadmap. The included capability set (camera, notifications, biometrics, local SQLite/file storage, deep links, orientation/thermal telemetry, localisation declarations) maps cleanly onto a large share of B2B, internal-ops, field-service, and content-browsing apps. That lets you greenlight a scoped mobile backlog now — list→detail, forms, authenticated sessions, offline capture — and explicitly defer anything graphics- or SDK-heavy.

5. Team topology and hiring plan. If adopted, your mobile "platform" owner is a senior Laravel engineer, not a mobile specialist. That changes job specs, on-call rotation, and who reviews mobile PRs. Worth a deliberate decision rather than an accident.

6. Delivery-process investment: CI/CD and QA budget. The headless --json CLI surface (build without a running simulator, native:run/native:status/native:screenshot/native:open-url, structured failure stage values) is a genuine differentiator for agent-assisted and CI-driven development. This supports funding automated screenshot-verified build pipelines rather than manual QA passes — and is a strong argument for standardising on it if you already run agentic coding workflows.

7. Security and compliance posture review. The package's documented hardening (HMAC-signed and encrypt-sealed payloads before unserialize(), app key moved into the Android Keystore, no bundling of the developer's key) is enough to justify a security review rather than an outright rejection — a meaningful gate for regulated or enterprise customers.

When to Consider This Package

Adopt when most of these are true:

• Your product is Laravel/PHP and the team's depth is PHP, not Swift/Kotlin/TypeScript.
• The mobile surface is a companion or workflow app: auth, lists, detail views, forms, camera capture, notifications, offline-first local storage.
• You want one codebase and one deploy pipeline for web and mobile, with mobile routes gated behind a native-context check.
• Time-to-first-version matters more than platform-perfect polish; a ~1–2 week spike (scaffold → list/detail screen → camera/biometrics → screenshot verification) is an acceptable discovery cost.
• You can absorb a young ecosystem: small star count, no listed dependents, and a fast-moving release cadence with breaking-ish internal changes.
• Someone on the team will own the build/verify loop and read the docs; this is not a "drop in and forget" dependency.

Look elsewhere when any of these are true:

• Licence is unresolved. The NOASSERTION licence field is a hard procurement blocker. Get legal to confirm terms in writing before it appears in a roadmap slide — this alone can kill a quarter.
• The app is graphics-, game-, AR-, or heavy-animation-driven, or needs deep native SDK integrations not exposed by the plugin layer.
• You need long-term vendor stability guarantees, an SLA, or a large hiring pool of engineers who already know the framework.
• You require a mature native plugin ecosystem and third-party SDK coverage on day one.
• Your team has no Laravel depth — the advantage evaporates and you've chosen an unfamiliar stack and an immature one.
• Accessibility, platform-HIG fidelity, or app-store-grade performance on low-end Android is a headline requirement; validate these rather than assume.

Adoption gate I'd put in front of any sponsor: a two-week, timeboxed spike producing one verified list→detail flow plus camera, biometrics, and offline SQLite on both platforms, with a working headless build in CI, and a resolved licence position. Pass/fail, not a vibe check.

How to Pitch It (Stakeholders)

For executives — one paragraph: NativePHP for Mobile lets our existing Laravel team build and ship native iOS and Android apps in PHP and Blade, without hiring mobile specialists or contracting an agency. Same language, same codebase, same team, one deploy pipeline. It covers the capabilities most of our mobile roadmap actually needs — camera, notifications, biometrics, offline storage, deep links — and it has a genuinely modern delivery story: automated, headless build verification in CI rather than manual QA. The trade is ecosystem maturity: it's a young package with a small community and an unresolved licence, so I'm recommending a two-week timeboxed spike to de-risk technical fit and legal terms before we commit roadmap dates or headcount assumptions.

For engineering — the honest version: This is a screen framework, not a web renderer. Screens are NativeComponent PHP classes rendering EDGE Blade onto SwiftUI and Jetpack Compose; there is no web server and no web view in native screens — the web view is a legacy escape hatch for embedding external content, never a foundation. Core ships no renderers; nativephp/mobile-ui provides every element, so verify the plugin chain (native:plugin:list) before writing a screen — a missing renderer is the single most common setup failure. Style through design tokens in config/native-ui.php, not literals; icons through generated enums. The day-to-day loop is edit → native:run --json → native:screenshot → native:open-url to drive navigation → verify the PNG. Treat ok:true plus native:status running plus a non-error screenshot as the definition of "booted" — a clean laravel.log is not evidence, and boot fatals live behind native:tail --fatals. Budget ~10 minutes for the first build, and adopt the documented agent hygiene (no --watch, one rebuild at a time, never edit generated nativephp/ios|android files).

Known risks to state up front, not discover later: licence ambiguity (NOASSERTION), small ecosystem with effectively no downstream dependents, a rapid release cadence that will require upgrade attention, an implicit dependency on the mobile-ui plugin for anything to render at all, and a performance/app-store-fidelity ceiling that must be tested on real low-end Android hardware before any public-facing commitment.