Nativephp Launcher Laravel Package

Product Decisions This Supports

• Dedicated-device / appliance strategy: Decides whether your app can be the device experience rather than just run on it. The package makes the app eligible as the home screen on every display, so a product can boot straight into your UI with no stock launcher, no recents entry, and no way for users to wander off into Android settings by accident. That's the enabling capability for kiosks, retail/POS terminals, in-car or industrial panels, handheld gaming devices, and TV/set-top experiences.
• Multi-display product bets: The HOME on the app's display + SECONDARY_HOME on the others split is the concrete mechanism behind "one app, two screens" products (dual-screen handhelds, foldables, clamshells, dual-panel kiosks). This is a roadmap-unlocking feature, not a polish item — it is the difference between supporting a dual-screen device and shipping a differentiated dual-screen product.
• Build vs. buy: The alternative is writing a native Android launcher component (manifest intent filters, home-task flags, per-display routing, BACK-at-root handling) plus a PHP bridge and maintaining it against Android version churn. This package collapses that into a handful of static calls and one event. For a team without a dedicated Android engineer, that's a clear buy; with a strong native team, it's a cheap head start you may later replace.
• Feature scope decisions it forces: The API surface (Launcher::apps(), Launcher::open($package, $display, $activity), Launcher::isDefaultHome(), Launcher::currentHome(), Launcher::openHomeSettings()) is deliberately a routing and eligibility layer, not a launcher UI. That means "we ship a launcher" is still a design and build commitment on our side — home layout, app grid, theming, per-display configuration, onboarding to actually get the user to set us as default (openHomeSettings() exists precisely because that grant is a user action, not something we can force).
• Event-driven screen ownership: HomeRequested($displayId) + Screens::show($displayId) gives a clean, composable contract: whichever display wants a home screen asks, and we decide what to put there. This supports roadmap items like per-display dashboards, "second screen shows companion panel," and hot-plug/display-change handling without bespoke plumbing.
• UX guarantee for hardware with no navigation: The IsHomeScreen trait (BACK at root stays put) is a small but product-relevant promise — it prevents the classic kiosk failure where a stray BACK gesture drops the user to a blank or stock Android surface.

When to Consider This Package

Adopt when most of the following hold:

• The product is Android-only or Android-first, and you've accepted that iOS has no equivalent capability (Apple does not permit replacing the home screen). If iOS parity is a requirement, this package cannot be part of the shared feature set.
• The device is a single-purpose or branded appliance — the customer expects to see your app, not a general-purpose phone.
• You are already on NativePHP mobile (or are choosing it) and need native launcher behavior without leaving PHP.
• You need per-display home behavior, or you're targeting dual-screen handhelds specifically.
• You can absorb 0.x churn: v0.1.0, small API surface, verified on exactly two devices (AYN Thor / Android 13, AYANEO / Android 11). Treat the API as stable-in-spirit but expect renames and behavior adjustments.
• You control or can document the device provisioning flow, since becoming default home requires a user/setup action.

Look elsewhere or defer when:

• You need a complete launcher out of the box (icon grid, widgets, wallpaper, search, folders). This package makes you eligible to be home; it doesn't draw the home screen.
• You need MDM/device-owner kiosk mode — that's an Android Enterprise / provisioning concern layered on top, not covered here.
• You plan to distribute on Google Play as a general-purpose launcher for consumer phones; launcher apps face policy and quality scrutiny well beyond this package's scope.
• Your target matrix includes older Android, unusual OEM skins, or TV/Car form factors that aren't in the two-device verification list. Budget for a device-lab pass before committing.
• You need iOS, desktop, or web parity in the same release.

How to Pitch It (Stakeholders)

For executives: This is a small package with a strategically large effect — it lets our app become the device. For dedicated-device products (kiosks, POS, in-vehicle, handheld gaming, dual-screen hardware), that means we can ship a fully branded, locked-down experience without hiring an Android launcher team or building a native module. It's the cheapest credible path to "our software is the product the user sees on boot," including on dual-screen devices where we control what each screen shows. The caveats are honest and bounded: Android only (iOS is a hard no for this capability anywhere), it's a v0.1.0 with a two-device test matrix, and it gives us the plumbing, not the home-screen UI — we still own that design work.

For engineering: Thin, event-driven API: Launcher::apps() / open($package, $display, $activity) for launching, isDefaultHome() / currentHome() / openHomeSettings() for state and provisioning, and HomeRequested($displayId) as the display-asks-for-home hook that pairs directly with the screens plugin (Screens::show($displayId)). The IsHomeScreen trait handles BACK-at-root so kiosk UX doesn't leak. Scope your risk accordingly: v0.1.0, Android 11–13 verified only, home-task behavior is inherently OEM-sensitive, and the default-home grant is a user action we must design an onboarding flow around. Recommend a device-matrix spike and a thin abstraction layer over the Launcher facade so we can swap or extend it later.