Nativephp Wifi Direct Laravel Package

Product Decisions This Supports

• Feature scope for offline / proximity-based workflows: This package enables Laravel-backed mobile apps to use Wi-Fi Direct for device-to-device connections without a network or cloud relay. Product candidates include field-service sync, local file or payload handoff, event/check-in tools, classroom or retail kiosk pairing, and multi-device demos where connectivity is unreliable.
• Build vs. buy: Adopt rather than build a native Wi-Fi Direct bridge in-house. The package provides Android and iOS native implementations, a PHP API, a JavaScript/TypeScript layer for Inertia/Vue/React, QR pairing helpers, permission handling, and test fakes. MIT licensing lowers procurement friction.
• UX decisions around permissions and failure states: PermissionResult now exposes reason (denied, permanently denied, approximate, interrupted) and permanentlyDenied, which supports clearer permission prompts, settings deep-links, and fallback flows. ConnectionFailed reason invalid lets the UI distinguish bad credentials from environmental failures.
• Pairing and onboarding design: parsePairing() returning null for malformed codes, plus PHP/JS/native validation of network names and passphrases, supports safer QR-code onboarding. The PM can specify “invalid code” UX instead of relying on native crashes or generic errors.
• Reliability and lifecycle expectations: Fixes for Android activity recreation, cancellation races, stale events, permission requests lost to recreation, and iOS dropped-link detection reduce the number of “ghost connection” states the product must explain. Still, the PM should treat connection state as eventually consistent and design UI that tolerates delayed Disconnected events.
• Roadmap gating for cross-platform interoperability: The known issue that iPhone joining an Android group is experimental—specifically failing on a Galaxy A05s host at 2.4 GHz—means cross-platform iPhone-to-Android group joining should be beta/feature-flagged, not a launch-critical promise, until validated on the target device matrix.
• Test strategy and release confidence: FakeBridge macros (assertWifiDirectHosting(), assertWifiDirectJoining(), assertWifiDirectDisconnected(), assertQrScanRequested()) and withWifiDirect() support automated product-flow tests in Laravel/Pest. This lowers the cost of regression testing connection UX.
• Frontend integration choice: The JavaScript library with TypeScript types and exports for Inertia, Vue, and React supports a single Laravel codebase with mobile frontends, rather than separate native modules per product surface.

When to Consider This Package

Consider this package when:

• You are building a Laravel application with a mobile client—especially Inertia/Vue/React—and need local device-to-device connectivity without internet or a server relay.
• Your primary use case is Android-to-Android or iOS-to-iOS Wi-Fi Direct, with QR-code or programmatic pairing.
• You can feature-flag or limit iPhone-to-Android group joining while it remains experimental.
• You can test on the actual target hardware, including lower-end Android hosts and iOS devices, rather than relying on emulators.
• You need permission-state nuance, cancellation behavior, and lifecycle handling that are already partially addressed by the package.
• You want MIT-licensed infrastructure with Laravel conventions, Pest tests, and frontend helpers rather than owning native Android/iOS code.
• Your app can require iOS 15+ and a reasonably modern Android device. The package lowers the iOS minimum to 15.0, which is still a product constraint to confirm against your install base.

Look elsewhere or defer when:

• Your launch requires dependable, production-grade iPhone-to-Android group joining today. The release notes explicitly call this experimental and document an association failure on a Galaxy A05s host.
• You need background or long-running transfers after the app activity is destroyed. The package intentionally tears down hosted groups/joins when the Android activity is destroyed, except on configuration changes.
• You need a pure web/PWA experience with no native wrapper. This package is a native bridge, not a browser-only Wi-Fi Direct API.
• You need mesh networking, many-device topology management, or advanced routing. Wi-Fi Direct groups are not a general mesh substitute.
• You need guaranteed behavior across a very broad Android device fleet without a hardware QA matrix. Android Wi-Fi Direct and permission behavior remain fragmented.
• You need an established, long-supported package with a public track record. This is the first public release; treat it as a pilot-ready dependency, not a mature platform bet without a spike.
• You cannot tolerate API changes in early adoption. connect() now returns bool, parsePairing() can return null, and disconnect() always emits Disconnected; these are manageable but require integration testing.

How to Pitch It (Stakeholders)

For executives: This is an MIT-licensed Laravel package that adds local Wi-Fi Direct connectivity to our mobile app without building and maintaining native Android/iOS bridges ourselves. It supports offline, proximity-based features—pairing, local handoff, field workflows—where cloud connectivity is unreliable. The first release includes hardened validation, permission reasons, lifecycle fixes, and frontend TypeScript support, which reduces time-to-pilot and native engineering cost. The main caveat is that iPhone joining an Android group is still experimental, so we should position cross-platform joining as beta and validate on target hardware before making it a launch commitment.

For engineering: Adopt behind a feature flag and integrate through the PHP API plus the JS/TypeScript exports. Use the FakeBridge macros for Pest coverage of hosting, joining, disconnection, and QR scan flows. Account for the new return contracts: connect() returns bool, parsePairing() returns null for malformed codes, and disconnect() always answers with Disconnected. Test on real Android and iOS devices, especially Android 12/12L permission behavior, activity recreation, cancellation races, and iOS local-network permission. Treat the known iPhone-to-Android group-join issue as a tracked risk with a fallback path—manual hotspot, QR-assisted setup, or Android-only hosting—until hardware validation clears it.