Download the PHP package sghimire/mobile-file-access without Composer

Mobile File Access

Generic native "save file" / "open file" for NativePHP Mobile apps, powered by the Storage Access Framework on Android and UIDocumentPickerViewController on iOS.

Not tied to any particular file type or app — use it to import/export a backup, save a generated PDF, let a user attach an arbitrary document, or read any file the user picks from their device or cloud storage (Files app / Google Drive / Dropbox, wherever the system document picker can reach).

Features

• Save arbitrary bytes to a location the user chooses, with a suggested file name.
• Read any file the user picks, back as base64 — including from cloud-backed providers exposed through the system Files app.
• No storage permissions required on either platform. The document picker grants per-file access on the user's behalf; this plugin never requests WRITE_EXTERNAL_STORAGE/READ_EXTERNAL_STORAGE (Android) and declares no Info.plist usage description (iOS).
• Fluent, chainable builders in both PHP and JavaScript.
• FileSaved / SaveCancelled / FilePicked / PickCancelled Laravel events, or bind straight to Livewire with #[OnNative].
• Works from PHP (Blade/Livewire) and from JavaScript (Vue, React, Inertia, or plain JS).

Example App

Authenticator is a full example app built using this plugin

Requirements

• PHP ^8.2
• nativephp/mobile ^3.0
• iOS 14+ / Android API 23+
• livewire/livewire — only needed if you use the #[OnNative] attribute

Installation

Laravel's package auto-discovery registers FileAccessServiceProvider for you. Then register the plugin with NativePHP:

This wires up the plugin's nativephp.json manifest (bridge functions — no permissions to merge, there aren't any) into your native build. Rebuild/reinstall the native shell afterwards (php artisan native:install or native:run) so the bridge functions are picked up.

How It Works (Under the Hood)

Same two-phase pattern as every async call in this plugin family — a synchronous "start" acknowledgement, then the real result delivered later through two parallel channels.

1. Request out. FileAccess::save(...)->save() / FileAccess::pick()->pick() (PHP) and FileAccess.save(...) / FileAccess.pick() (JS) both reach the same bridge — JS via fetch('/_native/api/call', { method: 'FileAccess.Save' | 'FileAccess.Pick', params }), PHP via nativephp_call(...). The bridge router opens the native picker: ActivityResultContracts.CreateDocument/OpenDocument on Android, UIDocumentPickerViewController on iOS.
2. Immediate ack. The call returns right away confirming the picker is open — not that the user has chosen anything yet.
3. Result comes back later, once, per call. On Android, the native side calls NativeActionCoordinator.dispatchEvent(...); on iOS, LaravelBridge.shared.send?(...). Both inject a script that fires a native-event CustomEvent on document (what the JS On()/Off() helpers listen for) and make a call back into Laravel that instantiates and dispatches the real event class (what Event::listen() / #[OnNative] pick up). The user backing out of the picker delivers SaveCancelled/PickCancelled the same way.

Because results are asynchronous and delivered to PHP and JS independently, always drive your UI from the events — never from the return value of save()/pick().

PHP Usage

The FileAccess facade

save()/pick() on the builder return bool — true once the request reached the native bridge, false if it couldn't be started (e.g. running outside the native shell, or the builder was already started once).

If you never call ->save()/->pick() explicitly, it fires automatically when the builder object is destructed — so FileAccess::save('report.pdf', $bytes); alone is enough to trigger it. Calling it yourself is recommended so you can check the return value.

PendingFileSave methods

PendingFilePick methods

Listening for results

Livewire: #[OnNative]

JavaScript Usage

Importing

This package doesn't publish a #nativephp import alias (that's reserved for NativePHP's first-party plugins). Import the file directly — either from the vendor path, or copy it into your own resources/js/ and import it from there:

Full TypeScript types are included in file-access.d.ts alongside it.

Saving a file

FileAccess.save(fileName, content) returns a thenable builder — await it directly, or chain builder methods first. content accepts a string (assumed already base64), a Uint8Array, or an ArrayBuffer.

Picking a file

Listening for events

Vue 3 example: encrypted backup export/import

JS API reference

await-ing (or .then-ing) a PendingFileSave/PendingFilePick sends the request to the native bridge exactly once — awaiting it twice is a no-op the second time.

Events reference

FileSaved

SaveCancelled

FilePicked

PickCancelled

• PHP classes: Sandip\FileAccess\Native\Events\FileAccess\{FileSaved,SaveCancelled,FilePicked,PickCancelled}
• JS event name constants: Events.FileAccess.{FileSaved,SaveCancelled,FilePicked,PickCancelled}

Why no permissions?

Both platforms delegate file access entirely to a system-owned picker:

• Android uses Intent.ACTION_CREATE_DOCUMENT and Intent.ACTION_OPEN_DOCUMENT (the Storage Access Framework) via ActivityResultContracts.CreateDocument/OpenDocument. The system grants your app a scoped, per-URI permission for exactly the file the user chose — no WRITE_EXTERNAL_STORAGE/READ_EXTERNAL_STORAGE manifest entry is requested or needed, on any supported API level.
• iOS uses UIDocumentPickerViewController, which similarly hands back a security-scoped URL for just the chosen file/destination. No Info.plist usage-description key applies here (those are only for Camera/Photo Library/Microphone-style device resources).

If you need something this plugin doesn't cover — e.g. picking straight from the photo library — pair it with a plugin built for that (like sghimire/mobile-scanner for camera/QR, or NativePHP's own media picker), which will declare whatever permission that flow actually needs.

Platform notes

Both are configured automatically by nativephp.json — you don't need to edit native project files by hand.

Testing

Outside of a compiled native shell, FileAccess::save(...)->save() and FileAccess::pick()->pick() return false (there's no bridge to call) — this is expected and is exactly what the test suite asserts.

License

MIT