Nativephp Media Laravel Package

Technical Evaluation

Architecture fit This is a NativePHP mobile plugin: a Laravel-side PHP facade (Media::), native sources compiled into the app bundle (resources/android/src, resources/ios/Sources), and a JS package (@protendai/nativephp-media) exposing one function per bridge function, event constants/listeners, and TypeScript types. Playback lives natively (platform media session, system resume card, media buttons, PiP); Laravel owns queue intent and app state; the front end reacts to bridge events.

• Strong fit for an existing NativePHP mobile app that needs audio queues, video, PiP, and OS media controls without writing Kotlin/Swift.
• Poor fit for a web-first or hybrid product: nothing in this release describes a web/desktop fallback, so a browser deployment needs a parallel HTML5 media path behind an interface.
• Architectural implication for roadmap: treat media as a platform-specific capability, not a cross-platform one, and scope features (device library browsing, PiP) as mobile-only.

Integration feasibility High for a NativePHP mobile codebase. Composer install → publish config (nativephp-media-config tag) → set NATIVEPHP_MEDIA_LIBRARY → rebuild; a single post_compile hook (nativephp:media:configure) applies the native configuration.

• CI is workable without devices for the PHP layer thanks to FakeBridge helpers (withMedia(), assertMediaQueued(), assertVideoOpened(), assertMediaPermissionRequested()) and the shipped Pest suite.
• Real-device smoke testing is still mandatory per release — the fixes in this version (activity recreation, service reconnection, PiP dismissal) are only observable on device.
• Effort shape: ~1–2 days to prove own-file/URL playback; ~1–2 sprints if device library, permission UX, PiP, and playback resumption are all in scope.

Technical risk

1. Ecosystem concentration. NativePHP mobile is young and this is a single-publisher package at v1.0.0. MIT licensing with in-repo native sources makes forking viable — budget for it rather than assuming vendor continuity.
2. Native coupling brittleness. The PiP patch is anchored to com.protendai.media.VideoActivity; resource paths and the post_compile hook were renamed even before the first public release. Pin exact versions and re-run device tests on every bump.
3. Policy/compliance — net positive. Device library access is now opt-in via NATIVEPHP_MEDIA_LIBRARY, so apps that only play their own files/URLs avoid a Google Play photo/video permission declaration entirely. Enabling audio/video re-introduces that declaration work plus iOS usage strings.
4. Two permission configs. Usage strings are configurable here but the app's own nativephp.permissions always wins — convenient, but a drift hazard unless a single source of truth is declared.
5. Security surface. Prior versions exported an Android media session that let any app queue arbitrary URIs (including app-private files); v1.0.0 restricts other packages to playback commands and trusts requestMetadata.mediaUri only from this app. The fix is good; the lesson is that this plugin exposes OS-level IPC and warrants a security read on every upgrade.
6. Unstated feature gaps. No mention of DRM/protected content, HLS/DASH, captions/subtitles, offline download/caching, gapless playback, or CarPlay/Android Auto. Do not commit roadmap on these until confirmed.
7. Debuggability vs. privacy. Logs are now scrubbed of titles, file paths, and URIs — correct for privacy, but field triage needs your own opt-in diagnostics.

Key questions

• Versioning and support policy: what NativePHP version matrix is supported, and how frequently do native paths and hook names change?
• Is there any web/desktop fallback plan, or is this permanently mobile-only?
• Which streaming protocols/containers are supported, and is DRM on the roadmap?
• What are the background-playback guarantees under Android 14/15 foreground-service rules and iOS audio session interruption handling?
• Is the queue persisted by the package or must the app rehydrate it after process death? Does resumption survive a cold start?
• Accessibility: captions, VoiceOver/TalkBack, and system media-control labeling?
• Where should usage strings canonically live — this config or nativephp.permissions?
• What is the security disclosure process and expected patch cadence?

Integration Approach

Stack fit Laravel + NativePHP mobile shell; Vite-built JS package; Pest for tests; iOS 16.0 minimum; Android with READ_MEDIA_VISUAL_USER_SELECTED (API 34) for partial "Select videos" access and legacy paths below that. The bridge is function-level, so it composes with Blade, Livewire, Inertia, or a Vue/React SPA without architectural preference.

Migration path Greenfield — there is no earlier public version, so no code migration. If replacing browser <audio>/<video> in a wrapper app:

• Keep the web path behind a media interface and add a native adapter, so behavior differences (system controls, PiP, resumption) don't leak into product code.
• Re-map any existing "remember where I was" logic to the new semantics: setQueue/openVideo with startPosition = -1 and skipTo resume the item's saved position, while next, previous, and auto-advance always start at 0. Any prior assumption that position carries forward across track changes must be re-tested — it was actively wrong on iOS before this release.

Compatibility Pin the NativePHP mobile version alongside this package and verify: Composer constraints, the nativephp-media-config publish tag, the nativephp:media:configure post_compile hook (the old nativephp:media:enable-pip no longer exists), the NATIVEPHP_MEDIA_LIBRARY values (true/audio/video), and precedence against your app's nativephp.permissions. Test matrix: iOS 16/17/18; Android 13/14/15; permission granted / denied / limited; process kill during playback; PiP enter, exit, and dismiss; Bluetooth and notification controls; interruption by calls or other audio apps.

Sequencing 0. Spike (3–5 days): own-file and URL playback on both platforms; confirm the build hook and config publish work in your CI.

1. Foundation: publish config, decide the canonical home for permission strings, wire FakeBridge into CI.
2. Core playback: queue, background audio, resumption, system media controls, stop() releasing the audio session.
3. Video + PiP: highest native-coupling risk (activity anchoring, PiP dismissal detection) — schedule device QA explicitly.
4. Device library (opt-in): only with a paired compliance ticket for the Play photo/video declaration and iOS usage copy. Ship behind a flag so non-library apps keep the lighter permission footprint.
5. Security review + release: re-read the exported-surface changes and confirm no app-private URIs are reachable.

Gate each step on a full native rebuild and smoke test on both platforms; the most expensive failures in this release (dropped events after activity recreation, stale command replay) were invisible in PHP-only tests.

Operational Impact

Maintenance Pin exact versions and expect churn: native source locations and the post_compile hook name both changed inside the first public release, and PiP depends on a specific activity class name. The dominant ongoing cost is tracking upstream NativePHP breaking changes, because these hooks and sources are compiled into your app binary. Retain a fork path (MIT, sources included) as insurance.

Support Support scripts must cover distinct, user-visible failure classes: permission denied vs. limited (iOS "Selected Photos", Android 14 "Select videos"); no audio after closing video or PiP (fixed here); resume landing in the wrong place (fixed here); media buttons not responding. Because logs are now redacted, add an explicit in-app diagnostics opt-in rather than relying on device logs.

Scaling Scaling is per-device, not per-server: binary size, native build time, cold start, battery, and audio-session contention are the levers. Watch large libraries — iOS previously re-read and re-sorted the entire Music library per page, now fixed, but confirm paging behavior at 10k+ items before enabling library browsing broadly. Queue depth and concurrent players are constrained by the shared-player design (a second openVideo() during PiP used to stack a player), so validate one-player-at-a-time assumptions in product UX.

Failure modes Fixed in this release: bridge events dropped or crashing once the activity finished; queued commands replayed after a failed service connection; permission requests lost to activity recreation; saved positions written under the wrong track id (seek past end); Android not saving outgoing positions on manual changes; media session allowing arbitrary URI queueing; video close stopping shared music playback; PiP window stacking; app termination when a library permission was requested without a usage string.

Residual risks to monitor: OS audio-focus arbitration, Bluetooth/OEM battery optimizations, any newly exposed IPC surface in future versions, and any custom-activity work that breaks the anchored PiP patch.

Ramp-up A Laravel/PHP developer is productive on the facade and JS bridge in ~2–3 days using the Boost guidelines and FakeBridge. Native-level debugging (Kotlin/Swift) is needed for edge cases, so keep at least one mobile-capable engineer or a partner agreement available. Budget roughly one engineer-week for permission UX and compliance copy, two for video/PiP polish and device QA, plus one app-store review cycle before enabling device library access in production.