studylink/mobile-documents

Native document viewer and picker for NativePHP Mobile

v1.0.1 2026-07-29 15:44 UTC

Requires

• php: ^8.2
• nativephp/mobile: ^3.0 || ^4.0

Requires (Dev)

• pestphp/pest: ^2.7|^3.0|^4.0

MIT

• Study Link

Published on Packagist.org on 2026-07-29 15:44 UTC

README

Native document viewer and picker for NativePHP Mobile. Opens a local file in the OS preview, and raises the OS document picker so the user can choose one.

Built for Study Link and released for anyone building on NativePHP Mobile. Requires nativephp/mobile v3 or v4.

Installation

composer require studylink/mobile-documents

Then allowlist the provider in your app's NativeServiceProvider::plugins():

protected function plugins(): array
{
    return [
        \StudyLink\Documents\DocumentsServiceProvider::class,
    ];
}

What it provides

• Documents.Open — opens a local file in the OS preview: QLPreviewController on iOS, an ACTION_VIEW intent through the core app's FileProvider on Android.
• Documents.Pick — raises the OS document picker (UIDocumentPickerViewController / Storage Access Framework). The picked file is copied into the app's own storage and the absolute path arrives asynchronously as a StudyLink\Documents\Events\DocumentPicked native event. A content:// URI or security-scoped URL never reaches PHP.

No permissions are required on either platform, and the plugin declares no FileProvider of its own — the NativePHP core app template already ships one serving the cache dir, which is why the Android viewer stages a copy there first.

Usage

use StudyLink\Documents\Facades\Documents;

Documents::open('/absolute/path/to/file.pdf');            // mime inferred from extension
Documents::pick(['pdf']);                                  // copies into storage/app/documents
Documents::pick(['pdf', 'jpg', 'png'], storage_path('app/inbox'));

Catch the pick in Livewire the same way the app catches camera events:

#[On('native:StudyLink\Documents\Events\DocumentPicked')]
public function documentPicked(bool $success, array $files = [], int $count = 0, ?string $error = null, bool $cancelled = false): void
{
    // $files[0]['path'] is an absolute path inside the app's storage.
}

Both calls guard on function_exists('nativephp_call') — the same guard the first-party plugins use. Note that this is not an on-device test: nativephp/mobile autoloads a Jump-mode polyfill of nativephp_call on dev machines, so off-device the call goes to the Jump bridge (and fails fast when no device is connected) rather than being skipped.

If your app needs to run off-device too (a browser during development, or a test suite), bind this behind your own interface and gate the native implementation on config('nativephp-internal.running') rather than on function_exists.

Tests

composer install
composer test