Skip to content

Commit f79596d

Browse files
shanerbaner82claude
shanerbaner82
and
claude
authored
Mobile v3.1 documentation (#282)
* Update mobile v3 docs for SDK 29+ support and configurable SDK versions - Add Android SDK Versions section to configuration docs - Remove permissions section from configuration (moved elsewhere) - Update environment setup to reflect API 29+ minimum - Add WebView compatibility note for Tailwind v4 on older devices - Update plugin docs min_version examples from 33 to 29 * 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> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 3e98d48 commit f79596d

9 files changed

Lines changed: 434 additions & 110 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)