Skip to content

Commit 9504d15

Browse files
shanerbaner82claude
shanerbaner82
and
claude
committed
Add mobile v3.1 documentation for persistent runtime, queues, and expanded platform support
Adds changelog entries, upgrade guide for 3.0→3.1, new queues concept page, expanded configuration docs (persistent runtime, deep links, Android build options, dev server, App Store Connect), and updated commands with platform shorthand flags and multi-plugin registration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 0bfed28 commit 9504d15

5 files changed

Lines changed: 386 additions & 50 deletions

File tree

‎resources/views/docs/mobile/3/concepts/queues.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
title: Queues
3+
order: 250
4+
---
5+
6+
## Background Queue Worker
7+
8+
NativePHP runs a background queue worker alongside your app's main thread. Queued jobs execute off the main thread,
9+
so they won't block your UI or slow down user interactions.
10+
11+
Both iOS and Android are supported.
12+
13+
## Setup
14+
15+
Set your queue connection to `database` in your `.env` file:
16+
17+
```dotenv
18+
QUEUE_CONNECTION=database
19+
```
20+
21+
That's it. NativePHP handles the rest — the worker starts automatically when your app boots.
22+
23+
## Usage
24+
25+
Use Laravel's standard queue dispatching. Everything works exactly as you'd expect:
26+
27+
```php
28+
use App\Jobs\SyncData;
29+
30+
SyncData::dispatch($payload);
31+
```
32+
33+
Or using the `dispatch()` helper:
34+
35+
```php
36+
dispatch(new App\Jobs\ProcessUpload($file));
37+
```
38+
39+
### Example Job
40+
41+
Here's a simple job that makes an API call in the background:
42+
43+
```php
44+
namespace App\Jobs;
45+
46+
use Illuminate\Bus\Queueable;
47+
use Illuminate\Contracts\Queue\ShouldQueue;
48+
use Illuminate\Foundation\Bus\Dispatchable;
49+
use Illuminate\Queue\InteractsWithQueue;
50+
use Illuminate\Queue\SerializesModels;
51+
use Illuminate\Support\Facades\Http;
52+
use NativePHP\Plugins\Dialog\Dialog;
53+
54+
class SyncData implements ShouldQueue
55+
{
56+
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
57+
58+
public function __construct(public array $payload) {}
59+
60+
public function handle()
61+
{
62+
Http::post('https://api.example.com/sync', $this->payload);
63+
64+
Dialog::toast('Sync complete!');
65+
}
66+
}
67+
```
68+
69+
## How It Works
70+
71+
When your app boots, NativePHP automatically starts a dedicated PHP runtime on a separate thread. This worker
72+
polls `queue:work --once` in a loop, picking up and executing queued jobs as they come in.
73+
74+
Because it runs on its own thread with its own PHP runtime, your queued jobs are fully isolated from the main
75+
request cycle — long-running tasks won't affect app responsiveness.
76+
77+
<aside>
78+
79+
The queue worker starts automatically. You don't need to run any artisan commands or configure a supervisor.
80+
NativePHP manages the worker lifecycle natively on both platforms.
81+
82+
</aside>
83+
84+
## Things to Note
85+
86+
- The queue worker requires [ZTS (Thread-Safe) PHP](/docs/mobile/3/getting-started/changelog), which is included by default in v3.1+.
87+
- Only the `database` queue connection is supported. This uses the same SQLite database as your app.
88+
- Jobs are persisted to the database, so they survive app restarts.
89+
- If a job fails, Laravel's standard retry and failure handling applies.

‎resources/views/docs/mobile/3/getting-started/changelog.md‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,40 @@ title: Changelog
33
order: 2
44
---
55

6-
For changes prior to v3, see the [v2 documentation](/docs/mobile/2/getting-started/changelog).
6+
For changes prior to v3, see the [v2 documentation](/docs/mobile/2/getting-started/changelog).
7+
8+
## v3.1 — Persistent Runtime & Performance
9+
10+
### New Features
11+
12+
- **Persistent PHP Runtime** — Laravel boots once and the kernel is reused across requests, yielding ~5-30ms response times vs ~200-300ms previously.
13+
- **ZTS (Thread-Safe) PHP** support enabling background queue workers
14+
- **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.
15+
- **Binary caching** — PHP binaries are cached in `nativephp/binaries` to avoid re-downloading on every build
16+
- **Versions manifest** — binary URLs fetched from `versions.json` instead of being hardcoded
17+
- **Android 8+ support** — minimum SDK lowered from Android 13 (API 33) to Android 8 (API 26), dramatically expanding device reach
18+
- **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
19+
- **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
20+
- **Configurable Android SDK versions** — `compile_sdk`, `min_sdk`, and `target_sdk` in your config
21+
- **Plugin multi-register** — `native:plugin:register` discovers and registers multiple plugins in one pass
22+
- **Unregistered plugin warnings** during `native:run`
23+
- **`ios/i` and `android/a` flags** for the `native:jump` command
24+
25+
### Improvements
26+
27+
- Static linking on Android for better performance and reliability
28+
- Plugin compilation during `native:package` builds
29+
- URL encoding preserved on Android redirects
30+
- Removed unused `react/http` and `react/socket` dependencies
31+
32+
### Developer Experience
33+
34+
- Laravel Boost skill support (shoutout Pushpak!) LINK TO PRS
35+
36+
## v3.0 — Plugin Architecture
37+
38+
- **Plugin-based architecture** — the framework is built around a modular plugin system
39+
- **All core APIs shipped as plugins** — Camera, Biometrics, Dialog, and more are all individual plugins
40+
- **`NativeServiceProvider`** for registering third-party plugins
41+
- **Plugin management commands** — install, register, and manage plugins from the CLI
42+
- **Free and open source**

‎resources/views/docs/mobile/3/getting-started/commands.md‎

Lines changed: 43 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -32,15 +32,22 @@ Build and run your app on a device or simulator.
3232
php artisan native:run {os?} {udid?}
3333
```
3434

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

44+
<aside>
45+
46+
Before building, `native:run` checks for unregistered plugins and warns you if any are found. You can register them
47+
with `php artisan native:plugin:register`.
48+
49+
</aside>
50+
4451
### native:watch
4552

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

52-
| Option | Description |
53-
|--------|-------------|
54-
| `platform` | Target platform: `ios` or `android` |
55-
| `target` | The device/simulator UDID to watch |
59+
| Option | Description |
60+
|--------|-----------------------------------------|
61+
| `platform` | Target platform: `ios/i` or `android/a` |
62+
| `target` | The device/simulator UDID to watch |
5663

5764
### native:jump
5865

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

65-
| Option | Description |
66-
|--------|-------------|
67-
| `--platform=` | Target platform: `android` or `ios` |
68-
| `--host=0.0.0.0` | Host address to serve on |
69-
| `--http-port=` | HTTP port to serve on |
72+
| Option | Description |
73+
|-----------------------|-------------|
74+
| `--platform=` | Target platform: `android` or `ios` |
75+
| `ios/i` | Shorthand for `--platform=ios` |
76+
| `android/a` | Shorthand for `--platform=android` |
77+
| `--host=0.0.0.0` | Host address to serve on |
78+
| `--http-port=` | HTTP port to serve on |
7079
| `--laravel-port=8000` | Laravel dev server port to proxy to |
71-
| `--no-mdns` | Disable mDNS service advertisement |
72-
| `--skip-build` | Skip building if `app.zip` exists |
80+
| `--no-mdns` | Disable mDNS service advertisement |
81+
| `--skip-build` | Skip building if `app.zip` exists |
7382

7483
### native:open
7584

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

82-
| Option | Description |
83-
|--------|-------------|
84-
| `os` | Target platform: `ios` or `android` |
91+
| Option | Description |
92+
|--------|-----------------------------------------|
93+
| `os` | Target platform: `ios/i` or `android/a` |
8594

8695
### native:tail
8796

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

122-
| Option | Description |
123-
|--------|-------------|
124-
| `platform` | Target platform: `android` or `ios` |
125-
| `--build-type=release` | Build type: `release` or `bundle` |
126-
| `--output=` | Output directory for signed artifacts |
127-
| `--jump-by=` | Skip ahead in version numbering |
131+
| Option | Description |
132+
|--------|---------------------------------------------------|
133+
| `platform` | Target platform: `android/a` or `ios/i` |
134+
| `--build-type=release` | Build type: `release` or `bundle` |
135+
| `--output=` | Output directory for signed artifacts |
136+
| `--jump-by=` | Skip ahead in version numbering |
128137
| `--no-tty` | Disable TTY mode for non-interactive environments |
129138

130139
**Android Options:**
@@ -181,10 +190,10 @@ Generate signing credentials for iOS and Android.
181190
php artisan native:credentials {platform?}
182191
```
183192

184-
| Option | Description |
185-
|--------|-------------|
186-
| `platform` | Target platform: `android`, `ios`, or `both` |
187-
| `--reset` | Generate new keystore and PEM certificate |
193+
| Option | Description |
194+
|--------|--------------------------------------------------|
195+
| `platform` | Target platform: `android/a`, `ios/i`, or `both` |
196+
| `--reset` | Generate new keystore and PEM certificate |
188197

189198
### native:check-build-number
190199

@@ -219,15 +228,15 @@ php artisan native:plugin:list
219228

220229
### native:plugin:register
221230

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

224233
```shell
225-
php artisan native:plugin:register {plugin}
234+
php artisan native:plugin:register {plugin?}
226235
```
227236

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

0 commit comments

Comments
 (0)