pushinbr / pam-native-background-transfer
Durable background uploads, downloads and request chains for PAM Native.
Package info
github.com/push-in/pam-native-background-transfer
Language:Swift
Type:pam-native-plugin
pkg:composer/pushinbr/pam-native-background-transfer
Requires
- php: ^8.5
- pushinbr/pam-native: ^1.53.1
Requires (Dev)
- pushinbr/pam-native-testing: ^0.2.0
Suggests
- pushinbr/pam-native-media: ^0.4 to transcode videos before upload with ->transcode(VideoPreset::...)
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-19 00:22:20 UTC
README
Uploads and downloads that survive backgrounding and process death.
Schedule durable, observable transfers and HTTP request chains through WorkManager and background URLSession while your PHP application stays responsive.
Install · Quick example · Platforms · Permissions · Docs · Issues
Install
Inside a PAM Native project, add only this capability:
pam composer require pushinbr/pam-native-background-transfer pam doctor --fix
The package is a PAM Native plugin (module background-transfer); nothing is added to pam-native.json. Use pam packages to list direct requirements and pam composer remove pushinbr/pam-native-background-transfer to uninstall. New to PAM? Create a project with pam init my-app --template native (see the PAM Native overview), then come back here.
Quick example
<?php use Pam\Native\BackgroundTransfer\{Backoff, BackgroundTransfer, HttpStep, Multipart, NetworkRequirement, Secret, TransferHandle, TransferNotification, TransferSnapshot}; Secret::put('session', $accessToken); // refresh it any time; queued transfers read the latest value BackgroundTransfer::upload('https://api.example.com/media') ->multipart(fn (Multipart $m) => $m->file('file', $video->path, 'video/mp4')->field('caption', $caption, template: false)) ->header('Idempotency-Key', $clientMessageId) ->bearer(Secret::vault('session')) ->notification(TransferNotification::make('Sending video')->progress()->failed('Upload failed')) ->network(NetworkRequirement::Unmetered) ->retry(3, Backoff::Exponential) ->then(HttpStep::post('https://api.example.com/chats/42/messages') ->bearer(Secret::vault('session')) ->json(['media_id' => '{{response.id}}', 'client_id' => $clientMessageId])) ->tag('chat:42') ->dispatch(fn (TransferHandle $transfer) => $transfer->watch( fn (TransferSnapshot $s) => $this->progress = $s->progress(), ));
The video uploads and the message is posted even if the app is closed. Signed URL uploads, transcoding before upload, downloads, templates and the Zé Chat outbox are in the guide; every class and error is in the API reference. A runnable minimal app is in example/.
Platform support
| Platform | Support | Notes |
|---|---|---|
| Android | API 24+ | WorkManager 2.11.2 (expedited + dataSync foreground service when a notification is set), OkHttp 4.12.0 |
| iOS | 15.0+ | Background URLSession for every step; Security, UserNotifications; not validated on a device yet |
| PAM Native | 1.0.35 to < 2.0.0 | From pam-native.plugin.json; PHP 8.5+ |
Permissions and requirements
| Platform | Declared by the plugin |
|---|---|
| Android | android.permission.ACCESS_NETWORK_STATE, INTERNET, FOREGROUND_SERVICE, FOREGROUND_SERVICE_DATA_SYNC, POST_NOTIFICATIONS |
| iOS | No Info.plist keys or capabilities (background URLSessions do not need a background mode) |
Request PermissionKind::Notifications on Android 13+ if you want the progress notification to be visible; transfers run either way. transcode() needs pushinbr/pam-native-media 0.4+ on Android and 0.5+ on iOS. Full notes: docs/platform-notes.md.
What you can build
- Resumable media uploads that post the message when the file lands
- Signed URL uploads and request chains of up to 64 steps
- Offline download queues for video, documents or maps
- Reliable sync of large files under constrained networks
| Native path | WorkManager + OkHttp · background URLSession |
| Application model | Composer package + generated native integration |
| Design rule | Independent module; no feed, vertical or application template bundled |
Retries and security
Retries cover network errors and HTTP 408/425/429/5xx; other 4xx responses fail immediately with statusCode and response on the snapshot. Completed steps are checkpointed, so neither automatic nor manual retries repeat them. Mark a non-idempotent step with ->retryable(false) to fail instead of repeating it automatically.
URLs must be HTTPS (plain HTTP is accepted only for loopback test servers). Paths are PAM sandbox paths (FileReference::$path) and traversal is rejected natively. Transfer specs, step checkpoints and the secret vault are encrypted with AES-256-GCM (a non-exportable Android Keystore key; a device-only Keychain key on iOS) and are excluded from backups; snapshots never contain secrets.
Compatibility
pushinbr/pam-native-background-transfer |
pushinbr/pam-native |
Android | iOS |
|---|---|---|---|
| 0.4.x | >=1.0.35 <2.0.0 (tested with 1.14.x) |
API 26+ | 15+, full pipelines (transcode() with pam-native-media 0.5+) |
| 0.3.x | >=1.0.35 <2.0.0 |
API 26+ | Single requests only |
Platform SDKs, credentials, entitlements, physical hardware and store configuration remain application responsibilities.
Tests
composer test runs the PHP contract suite. Android JVM tests live in android/src/test and instrumented tests (MockWebServer, WorkManager, cross-plugin transcode) in android/src/androidTest; run them from a PAM Android host that includes this plugin (and pam-native-media for the transcode test) with connectedDebugAndroidTest.
Production checklist
- Persist transfer identifiers before leaving the initiating screen.
- Reconcile transfer state after launch and resume.
- Treat destination files as untrusted until size, type and checksum validation pass.
- Run
pam doctor,pam testand a signed release build on every supported platform. - Exercise denial, cancellation, backgrounding, process restart and offline behavior before release.
Security vulnerabilities should be reported through the repository security policy or GitHub private vulnerability reporting, not a public issue.
Troubleshooting
- Work never starts: verify HTTPS, network constraints and OS background policy.
- Path rejected: use an application-sandbox-relative path without traversal.
- Progress stops in development: query the persisted identifier after runtime reload.
- A watch goes silent: a watch ends when the native module restarts; re-read the durable state with
BackgroundTransfer::find()(Zé Chat re-checks after 30 s without a snapshot). - A 4xx response is not retried: only network errors and HTTP 408/425/429/5xx are retried; inspect
TransferSnapshot::$response. - A template path is missing: the transfer fails without retrying; check
{{response.…}}/{{steps.<name>.…}}against the real JSON. - Native integration is stale: run
pam doctor --fix, rebuild the native host, and inspect the first reported diagnostic.
Docs
- PAM Native overview
- PAM introduction
- Guide: uploads, signed URLs, transcoding, downloads, templates, iOS details, the Zé Chat outbox
- API reference
- Install and platform notes
- Plugin and native capability model
- Example app
- Changelog
- Report an issue
Part of the PAM ecosystem
PAM runs PHP natively on servers, desktops and phones. This repository is one piece of it.
| PAM | PAM Desktop | PAM Native | Ecosystem |
|---|---|---|---|
| the runtime and CLI | native desktop apps in PHP | native Android and iOS apps in PHP | every official package and plugin |
Docs: push-in.github.io/pam-docs · Issues
Apache License 2.0 · Made in Brazil by Pushin