Nativephp Wifi Direct Laravel Package

Technical Evaluation

Architecture fit

• NativePHP-style Laravel plugin: a PHP façade (WifiDirect::isValidNetworkName(), isValidPassphrase()), a native bridge per platform (resources/android/src, resources/ios/Sources), and a JS layer (resources/js/index.js with TypeScript types) exposing one export per bridge function for Inertia/Vue/React. This is the correct shape for a Laravel product team — the domain logic and validation surface live in PHP where they are testable, and the JS layer means no bespoke glue per frontend.
• The FakeBridge macros (assertWifiDirectHosting(), assertWifiDirectJoining(), assertWifiDirectDisconnected(), assertQrScanRequested(), withWifiDirect() answering connect()) are the single most valuable item for a TPM: they make the feature testable in CI without hardware, which is normally the blocker for accepting a native-capability dependency.
• The platform asymmetry is the defining architectural fact. Android has real Wi-Fi Direct (WifiP2pManager) and can host a group. iOS has no Wi-Fi Direct; it participates by joining an Android-hosted group (SSID + passphrase via NEHotspotConfiguration) or via its own Apple-only path. Android→Android and iOS→iOS are first-class; iPhone joining an Android group is explicitly labelled experimental and failed to associate on a Galaxy A05s host at 2.4 GHz. Any product requirement of "cross-platform local sync" is currently a pilot, not a commitment.

Integration feasibility

• MIT licensed, Pest suite included, Laravel Boost guidelines shipped — low legal friction and a plausible path to contributor/maintainer coverage if we ever need to patch natively.
• Requires a native build pipeline (not a pure Composer install): Android manifest permissions, NSLocalNetworkUsageDescription (now declared by the plugin, good), and platform toolchains. This is a delivery-pipeline cost, not a code cost — budget for it in the first sprint.
• iOS minimum lowered to 15.0 broadens the addressable fleet with no product downside.

Technical risk

• Highest: cross-platform interop (iOS↔Android). Documented failure, no supported-device matrix, and it depends on host band/channel behaviour we do not control.
• High: the v1.0.0 changelog is dominated by Android lifecycle, threading and cancellation defects — activity held strongly, events dispatched to a destroyed activity, P2P state unsynchronised between the PHP thread and the main looper, joins completing after cancellation, Connected arriving after ConnectionFailed, permission requests lost to activity recreation. These are fixed, but a first public release carrying that defect density means field behaviour under aggressive OEM battery management should be assumed to have residual edge cases.
• Medium: contract changes even at 1.0.0 — connect() now returns bool and can return false with no event; parsePairing() now returns null on malformed codes; disconnect() always emits Disconnected even with no link. Callers that ignore return values are unaffected, but any UI state machine keyed on "disconnect fires only if connected" will need review.
• Medium: permission semantics. PermissionResult now carries reason (denied, permanently denied, approximate, interrupted) plus permanentlyDenied. This is a real improvement for UX copy and support triage, but it means the frontend must handle four states, not two.
• Low/positive: the Android crash on malformed pairing codes is fixed with validation at three layers (PHP, JS, native) and guarded WifiP2pConfig.Builder/P2P calls; network names are no longer written to logs, which removes a privacy review item.
• Key questions:
  1. What is the supported device/OS matrix, specifically for iOS-joins-Android? Is the A05s failure a band issue (2.4 GHz host) we can document around, or a broader association problem?
  2. Does the plugin handle Android 13+ NEARBY_WIFI_DEVICES (with neverForLocation), or only the 12/12L location path fixed here? This determines our Play Store permission declaration and review timeline.
  3. What is the maximum group size and expected throughput/range? This drives whether we position the feature as "pair two devices" or "small team sync".
  4. Is approx location permission sufficient for discovery on Android 12+, or does precise remain required? Affects permission-rationale copy and grant rates.
  5. Is there a non-Wi-Fi-Direct fallback (QR-only handoff, BLE, local server) we should design alongside, so the experimental path is never the only route?

Integration Approach

Stack fit

• Assumes a Laravel app with a NativePHP-style mobile shell plus Inertia/Vue or React. If we are on Livewire/Blade only, the JS library is unused and everything routes through the PHP façade — still viable, but we lose the event ergonomics (onWifiDirect(), Events names) that make the pairing UX pleasant.
• QR pairing is the intended discovery mechanism (assertQrScanRequested() in the fake API, plus the iOS QR rendering fixes). Assume a scan-to-pair flow rather than automatic discovery.

Migration path

• Greenfield: no prior assessment and no prior integration, so no data or API migration. The only "migration" is for anyone who prototyped against a pre-1.0 branch — audit for parsePairing() null handling, connect() return values, and any logic that assumed Disconnected implies a prior connection.

Compatibility

• iOS 15.0+; Android needs the 12/12L permission fix behaviour and should be verified on 13/14/15 for NEARBY_WIFI_DEVICES. Info.plist string is now generic and plugin-declared, so no per-app copy work — but confirm NSLocalNetworkUsageDescription prose meets our App Store review standards.
• Validate against a device matrix that includes at least one Samsung, one Pixel, one aggressive-OEM (Xiaomi/Oppo) Android, and two iOS generations before committing to the cross-platform path.

Sequencing

1. Sprint 1 — Android-only pilot. Host/join between two Android devices, PHP façade + fake bridge in CI, permissions UX covering all four reason values, including permanentlyDenied → settings deep-link.
2. Sprint 2 — same-platform iOS. iOS↔iOS pairing, QR rendering, disconnect detection (NWPathMonitor + address poll now reports drops).
3. Sprint 3 — cross-platform as behind-a-flag beta. iPhone joining an Android group, instrumented with explicit failure telemetry, documented as experimental in-app.
4. Sprint 4 — hardening. Activity-recreation and backgrounding soak tests, cancellation races (createGroup()/connect() now cancel in flight and replace reported links), and teardown-on-destroy behaviour.

• Do not let steps 1–2 block on step 3. The release notes are effectively telling us the cross-platform path is not yet a shippable promise.

Operational Impact

Maintenance

• We inherit a native codebase on two platforms. Every Android and iOS major release is a potential breakage vector (permissions, background restrictions, local network privacy prompts). Budget a recurring maintenance line, not a one-off integration cost — this is the main total-cost-of-ownership argument against the package versus a server-relay design.
• Single maintainer / early-stage signal: v1.0.0 with a large fix list and one documented known issue. Have a contingency plan (fork-and-patch) since MIT permits it and the Pest suite gives us a safety net.

Support

• Support load will concentrate on three ticket types: permission denials (now diagnosable via reason), cross-platform pairing failures (currently unexplainable without device logs — requires us to build in-app diagnostics), and OEM background-kill symptoms. Pre-write KB articles for each before launch.
• The permanentlyDenied flag is the difference between a self-service fix and a support ticket; make sure the UI surfaces it.

Scaling

• Peer-to-peer: no server cost, no per-user infrastructure, which is attractive for offline/field/edge use cases. The trade-off is that scale is bounded by group size and physical proximity; this is not a substitute for a sync backend, it is a supplement to it.
• Log hygiene improved (network names no longer logged), which keeps us out of trouble as log volume grows.

Failure modes

• Silent permission denial (Android 12/12L precise-without-approximate) — fixed, but re-verify, since the failure mode was invisible.
• Stale link state after activity recreation — fixed via weak reference and main-looper confinement; still the most likely regression class under configuration changes.
• Cancellation races — user cancels, device joins anyway; or hosting deadline tears down a fresh join. Fixed for createGroup()/connect()/disconnect(), but this is exactly the class of bug that reappears.
• Late events after timeout (Connected after ConnectionFailed).
• Cross-platform association refusal — the current known issue, with no workaround documented beyond the README.
• Hosted group outliving the activity — now torn down on destroy (not on configuration change), which is the correct behaviour but means backgrounding ends sessions; product must accept that.

Ramp-up

• Moderate for a Laravel engineer: the PHP façade and fake bridge are approachable, and validation helpers plus the Pest suite flatten the learning curve.
• Steep for anyone debugging the native layer — thread confinement, looper dispatching, and P2P topology are specialist skills. Assume one engineer owns the native surface and that we are dependent on upstream for non-trivial Android/iOS defects.
• Recommend an internal spike (2–3 days) reproducing host/join/disconnect on our own device fleet before committing to a roadmap date, and treating the cross-platform path as unestimated until that spike returns.