Nativephp Media Laravel Package

Product Decisions This Supports

• Build vs. buy for native media playback. If the product needs background audio, lock-screen/media-button controls, queue management, resume-where-you-left-off, or in-app video with picture-in-picture, this package replaces weeks of parallel AVFoundation/ExoPlayer work with a PHP + TypeScript bridge. v1.0.0 is the point at which "buy" becomes defensible in a build-vs-buy review.
• Privacy and store-compliance posture as a deliberate product choice. Device library access is now opt-in (NATIVEPHP_MEDIA_LIBRARY = true / audio / video). Apps that only play bundled files or remote URLs ship with no Google Play photo/video permission declaration and no iOS Music/Photos usage strings. Decide per product whether library access is actually a feature — every "no" shrinks the privacy policy, the store listing disclosures, and review friction.
• Roadmap sequencing for the media surface. The release defines a credible feature baseline: queue semantics (setQueue/skipTo/next/previous), playback resumption from the system resume card and media buttons, iOS limited-library and Android 14 partial video access, configurable usage descriptions. What is not here (DRM, adaptive streaming, downloads, editing) becomes your roadmap, not an integration surprise.
• Device coverage target. iOS 16.0 minimum is a product decision about install base; confirm it against your audience before committing.
• Definition of done and QA cost. FakeBridge helpers (withMedia(), assertMediaQueued(), assertVideoOpened(), assertMediaPermissionRequested()) plus a Pest suite mean media flows can be asserted in CI instead of manually on physical devices — a measurable reduction in regression cost per release.
• Supportability / licensing decision. MIT + config publishing + first public release means you can ship on it, vendor it, or fork it without legal friction. That is the gating question for adopting a young dependency.
• Security review trigger. The Android media session was previously exported such that any app could queue arbitrary URIs, including app-private files. Fixed in this version — but it makes "verify the pinned version and the media session surface" a release-checklist item, not a one-time read.

When to Consider This Package

Adopt when:

• You are building on NativePHP (mobile) with a Laravel/PHP team and no meaningful Swift/Kotlin depth.
• The product needs audio playback with background/lock-screen/Bluetooth control, a queue, and resume position — or embedded video with PiP.
• You want optional device music/video library access with correct permission UX across iOS limited access and Android 14 partial video selection.
• You want a typed JS client, event constants, and test seams rather than hand-rolling a bridge and its edge cases.
• MIT licensing and an iOS 16+ floor are acceptable.

Look elsewhere (or scope out) when:

• The app is web-only or has no native shell — this is iOS/Android only.
• You need DRM (Widevine/FairPlay), HLS/DASH adaptive streaming, live playback, transcoding, editing, or camera capture — none are in the stated scope.
• You are targeting desktop (Windows/macOS/Linux) with NativePHP; the release notes cover iOS and Android only.
• You require vendor-backed SLAs or a long-term support contract; this is a v1.0.0 package from a single publisher. Plan to fork or negotiate.
• You must support iOS below 16.0.

Adoption guardrails: pin the exact version, read the config keys (library, usage_descriptions) before enabling library access, run the nativephp-media-config publish step, and note that nativephp:media:configure replaces the old nativephp:media:enable-pip compile hook in any existing integration docs.

How to Pitch It (Stakeholders)

To executives (one paragraph): This package gives our Laravel app real native media playback — background audio with lock-screen and Bluetooth controls, resumable queues, and video with picture-in-picture — on both iOS and Android, without standing up a separate native team. It's MIT-licensed and it ships with device library access off by default, so apps that only stream their own content carry no extra Google Play permission declarations and no expanded privacy scope. The cost is integration plus device QA; the risk is that it's a young v1.0.0 dependency, which we mitigate by pinning the version and treating upgrades as reviewed changes.

To engineering (summary): v1.0.0 covers the parts that are expensive to get right: audio session lifecycle (including proper deactivation so other apps' audio resumes), media session and notification/Bluetooth transport controls, per-item resume positions saved for the outgoing track rather than the incoming one, Android 14 partial video access, iOS limited-library results, and activity/service reconnection — events are now buffered when the host activity is gone and replayed when it returns, and queued commands are no longer replayed after a failed service connection. The JS library is typed with a function per bridge function and event constants; config is publishable via the nativephp-media-config tag; FakeBridge assertions plus the Pest suite give us CI coverage. Two things to verify on integration: the Android media session is now scoped to playback commands only (third-party onAddMediaItems no longer trusts foreign URIs), and the single post_compile hook is nativephp:media:configure, anchored to com.protendai.media.VideoActivity. Minimum iOS is 16.0, and native logs no longer carry titles, paths, or URIs — useful for our data-handling review.