Download the PHP package smronju/nativephp-document-picker without Composer

NativePHP Document Picker

Presents the system document picker in a NativePHP Mobile app — to open a foreign file, and to save one back out to a location the user chooses.

• Open — iOS UIDocumentPickerViewController(forOpeningContentTypes:asCopy:), Android ACTION_OPEN_DOCUMENT. Hands PHP an absolute path to a copy of the chosen file.
• Save — iOS UIDocumentPickerViewController(forExporting:), Android ACTION_CREATE_DOCUMENT. Copies a file the app already wrote to wherever the user picks — Downloads, an SD card, a cloud provider's own app.

No storage permission on either platform, either direction: both pickers are system UI, and the user choosing a file or a destination is the entire grant.

Why open hands back a copy

Neither platform hands back something PHP can read. Android returns a content:// URI belonging to another app's provider, which fopen() cannot open at all; iOS returns a URL inside the provider's sandbox that needs coordinated access and a security-scoped resource dance the embedded runtime can't perform. So pick() copies first and reports the copy's path.

Why save exists at all

The system share sheet (Share::file() from nativephp/mobile-share) can only offer whatever apps happen to register a share receiver — on a device with no such app installed, there is nothing to save to. save() is backed by the OS's own storage layer instead (Android's Storage Access Framework; iOS's document provider system), so it always has somewhere to put the file, independent of what's installed.

Installation

Then rebuild — native code only compiles in at build time:

Usage

Opening a file

pick() only presents the picker. The result arrives via an event, because choosing a file can take arbitrarily long — a file in a cloud provider is downloaded first.

Saving a file

$sourcePath must already exist — this presents a picker for a file the app already wrote; it does not create one. Like pick(), this only presents the picker; the outcome arrives via an event.

Every listener parameter needs its own = null default even though the types are nullable — the #[On] dispatcher supplies an argument only for payload keys that are present, and this plugin omits every key on cancel. (An explicit JSON null would arrive as '', not null.)

Notes

• pick()'s copy is temporary. Read it, or move it somewhere durable, inside the listener. Android keeps only the most recently picked file; iOS may clear its temporary directory at any time.
• $name on DocumentPicked is untrusted — it comes from another app's provider. The Android side strips path separators before using it as a filename; do the same before putting it into a path of your own.
• save()'s Save panel name. iOS's forExporting shows the given file's own name in the panel, with no separate "suggested name" parameter — so the plugin stages a renamed copy first. Android passes $suggestedName through Intent.EXTRA_TITLE directly; the destination provider may still adjust it.
• MIME types are the shared vocabulary, both directions. iOS maps each to a UTType; anything it doesn't recognise is dropped rather than guessed at, and an empty list on pick() falls back to every file.

License

MIT