Skip to content

Mobile v3.1 documentation #282

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shanerbaner82 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Mobile v3.1 documentation #282

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0bfed28
Update mobile v3 docs for SDK 29+ support and configurable SDK versions
shanerbaner82 Feb 20, 2026
9504d15
Add mobile v3.1 documentation for persistent runtime, queues, and exp…
shanerbaner82 Mar 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 89 additions & 0 deletions resources/views/docs/mobile/3/concepts/queues.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
---
title: Queues
order: 250
---

## Background Queue Worker

NativePHP runs a background queue worker alongside your app's main thread. Queued jobs execute off the main thread,
so they won't block your UI or slow down user interactions.

Both iOS and Android are supported.

## Setup

Set your queue connection to `database` in your `.env` file:

```dotenv
QUEUE_CONNECTION=database
```

That's it. NativePHP handles the rest — the worker starts automatically when your app boots.

## Usage

Use Laravel's standard queue dispatching. Everything works exactly as you'd expect:

```php
use App\Jobs\SyncData;

SyncData::dispatch($payload);
```

Or using the `dispatch()` helper:

```php
dispatch(new App\Jobs\ProcessUpload($file));
```

### Example Job

Here's a simple job that makes an API call in the background:

```php
namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Http;
use NativePHP\Plugins\Dialog\Dialog;

class SyncData implements ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

public function __construct(public array $payload) {}

public function handle()
{
Http::post('https://api.example.com/sync', $this->payload);

Dialog::toast('Sync complete!');
}
}
```

## How It Works

When your app boots, NativePHP automatically starts a dedicated PHP runtime on a separate thread. This worker
polls `queue:work --once` in a loop, picking up and executing queued jobs as they come in.

Because it runs on its own thread with its own PHP runtime, your queued jobs are fully isolated from the main
request cycle — long-running tasks won't affect app responsiveness.

<aside>

The queue worker starts automatically. You don't need to run any artisan commands or configure a supervisor.
NativePHP manages the worker lifecycle natively on both platforms.

</aside>

## Things to Note

- The queue worker requires [ZTS (Thread-Safe) PHP](/docs/mobile/3/getting-started/changelog), which is included by default in v3.1+.
- Only the `database` queue connection is supported. This uses the same SQLite database as your app.
- Jobs are persisted to the database, so they survive app restarts.
- If a job fails, Laravel's standard retry and failure handling applies.
38 changes: 37 additions & 1 deletion resources/views/docs/mobile/3/getting-started/changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,40 @@ title: Changelog
order: 2
---

For changes prior to v3, see the [v2 documentation](/docs/mobile/2/getting-started/changelog).
For changes prior to v3, see the [v2 documentation](/docs/mobile/2/getting-started/changelog).

## v3.1 — Persistent Runtime & Performance

### New Features

- **Persistent PHP Runtime** — Laravel boots once and the kernel is reused across requests, yielding ~5-30ms response times vs ~200-300ms previously.
- **ZTS (Thread-Safe) PHP** support enabling background queue workers
- **PHP Queue Worker** — a dedicated background thread runs queued Laravel jobs off the main thread on both iOS and Android. Just set `QUEUE_CONNECTION=database` and dispatch jobs as normal. See [Queues](../concepts/queues) for details.
- **Binary caching** — PHP binaries are cached in `nativephp/binaries` to avoid re-downloading on every build
- **Versions manifest** — binary URLs fetched from `versions.json` instead of being hardcoded
- **Android 8+ support** — minimum SDK lowered from Android 13 (API 33) to Android 8 (API 26), dramatically expanding device reach
- **PHP 8.3–8.5 support** — NativePHP now detects your app's PHP version from `composer.json` and matches it automatically, with PHP 8.3 as the lowest supported version
- **ICU/Intl support on iOS** — iOS now ships with full ICU support, enabling Filament and other packages that depend on the `intl` extension to work on both platforms
- **Configurable Android SDK versions** — `compile_sdk`, `min_sdk`, and `target_sdk` in your config
- **Plugin multi-register** — `native:plugin:register` discovers and registers multiple plugins in one pass
- **Unregistered plugin warnings** during `native:run`
- **`ios/i` and `android/a` flags** for the `native:jump` command

### Improvements

- Static linking on Android for better performance and reliability
- Plugin compilation during `native:package` builds
- URL encoding preserved on Android redirects
- Removed unused `react/http` and `react/socket` dependencies

### Developer Experience

- Laravel Boost skill support (shoutout Pushpak!) LINK TO PRS

## v3.0 — Plugin Architecture

- **Plugin-based architecture** — the framework is built around a modular plugin system
- **All core APIs shipped as plugins** — Camera, Biometrics, Dialog, and more are all individual plugins
- **`NativeServiceProvider`** for registering third-party plugins
- **Plugin management commands** — install, register, and manage plugins from the CLI
- **Free and open source**
77 changes: 43 additions & 34 deletions resources/views/docs/mobile/3/getting-started/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,15 +32,22 @@ Build and run your app on a device or simulator.
php artisan native:run {os?} {udid?}
```

| Option | Description |
|--------|-------------|
| `os` | Target platform: `ios` or `android` |
| `udid` | Specific device/simulator UDID |
| `--build=debug` | Build type: `debug`, `release`, or `bundle` |
| `--watch` | Enable hot reloading during development |
| `--start-url=` | Initial URL/path to load (e.g., `/dashboard`) |
| Option | Description |
|--------|---------------------------------------------------|
| `os` | Target platform: `ios/i` or `android/a` |
| `udid` | Specific device/simulator UDID |
| `--build=debug` | Build type: `debug`, `release`, or `bundle` |
| `--watch` | Enable hot reloading during development |
| `--start-url=` | Initial URL/path to load (e.g., `/dashboard`) |
| `--no-tty` | Disable TTY mode for non-interactive environments |

<aside>

Before building, `native:run` checks for unregistered plugins and warns you if any are found. You can register them
with `php artisan native:plugin:register`.

</aside>

### native:watch

Watch for file changes and sync to a running mobile app.
Expand All @@ -49,10 +56,10 @@ Watch for file changes and sync to a running mobile app.
php artisan native:watch {platform?} {target?}
```

| Option | Description |
|--------|-------------|
| `platform` | Target platform: `ios` or `android` |
| `target` | The device/simulator UDID to watch |
| Option | Description |
|--------|-----------------------------------------|
| `platform` | Target platform: `ios/i` or `android/a` |
| `target` | The device/simulator UDID to watch |

### native:jump

Expand All @@ -62,14 +69,16 @@ Start the NativePHP development server for testing mobile apps without building.
php artisan native:jump
```

| Option | Description |
|--------|-------------|
| `--platform=` | Target platform: `android` or `ios` |
| `--host=0.0.0.0` | Host address to serve on |
| `--http-port=` | HTTP port to serve on |
| Option | Description |
|-----------------------|-------------|
| `--platform=` | Target platform: `android` or `ios` |
| `ios/i` | Shorthand for `--platform=ios` |
| `android/a` | Shorthand for `--platform=android` |
| `--host=0.0.0.0` | Host address to serve on |
| `--http-port=` | HTTP port to serve on |
| `--laravel-port=8000` | Laravel dev server port to proxy to |
| `--no-mdns` | Disable mDNS service advertisement |
| `--skip-build` | Skip building if `app.zip` exists |
| `--no-mdns` | Disable mDNS service advertisement |
| `--skip-build` | Skip building if `app.zip` exists |

### native:open

Expand All @@ -79,9 +88,9 @@ Open the native project in Xcode or Android Studio.
php artisan native:open {os?}
```

| Option | Description |
|--------|-------------|
| `os` | Target platform: `ios` or `android` |
| Option | Description |
|--------|-----------------------------------------|
| `os` | Target platform: `ios/i` or `android/a` |

### native:tail

Expand Down Expand Up @@ -119,12 +128,12 @@ Package your app for distribution with signing.
php artisan native:package {platform}
```

| Option | Description |
|--------|-------------|
| `platform` | Target platform: `android` or `ios` |
| `--build-type=release` | Build type: `release` or `bundle` |
| `--output=` | Output directory for signed artifacts |
| `--jump-by=` | Skip ahead in version numbering |
| Option | Description |
|--------|---------------------------------------------------|
| `platform` | Target platform: `android/a` or `ios/i` |
| `--build-type=release` | Build type: `release` or `bundle` |
| `--output=` | Output directory for signed artifacts |
| `--jump-by=` | Skip ahead in version numbering |
| `--no-tty` | Disable TTY mode for non-interactive environments |

**Android Options:**
Expand Down Expand Up @@ -181,10 +190,10 @@ Generate signing credentials for iOS and Android.
php artisan native:credentials {platform?}
```

| Option | Description |
|--------|-------------|
| `platform` | Target platform: `android`, `ios`, or `both` |
| `--reset` | Generate new keystore and PEM certificate |
| Option | Description |
|--------|--------------------------------------------------|
| `platform` | Target platform: `android/a`, `ios/i`, or `both` |
| `--reset` | Generate new keystore and PEM certificate |

### native:check-build-number

Expand Down Expand Up @@ -219,15 +228,15 @@ php artisan native:plugin:list

### native:plugin:register

Register a plugin in your NativeServiceProvider.
Register a plugin in your NativeServiceProvider. When called without arguments, discovers all unregistered plugins and lets you register them.

```shell
php artisan native:plugin:register {plugin}
php artisan native:plugin:register {plugin?}
```

| Option | Description |
|--------|-------------|
| `plugin` | Package name (e.g., `vendor/plugin-name`) |
| `plugin` | Package name (e.g., `vendor/plugin-name`). Optional — omit to discover unregistered plugins |
| `--remove` | Remove the plugin instead of adding it |
| `--force` | Skip conflict warnings |

Expand Down
Loading
Loading