Augmented reality for NativePHP Mobile v4, driven from Laravel.
- AR Quick Look: drop a USDZ model in the room (iOS) or a glTF/GLB via Scene Viewer (Android).
- World-tracking sessions (iOS): full-screen ARKit + RealityKit view with plane detection, coaching overlay, tap-to-place, optional arrows on the screen edge pointing to off-screen notes (
offscreenArrows(), in each note's colour). - Sticky-note anchors: labelled, coloured notes you place, update and remove from PHP.
- Persistence (iOS): save the
ARWorldMapwith its anchors and relocalize on the next session. - Native prompt above the AR view, so you can ask for text without leaving the session.
Status: v0.1, experimental. The native code has not been compiled against a device yet.
| Feature | iOS | Android |
|---|---|---|
AR.Support |
yes | yes (reports supported: false) |
| Quick Look | local or remote .usdz |
HTTPS .glb / .gltf via Scene Viewer, no dismiss event |
| Sessions, taps, anchors | yes | not yet (not_implemented, SessionFailed fired) |
| World map persistence | yes (local file) | not yet (needs ARCore Cloud Anchors) |
| Prompt | yes | yes |
composer require alpine-ronin/nativephp-ar
php artisan native:plugin:register alpine-ronin/nativephp-ar
php artisan native:runFor local development, add a path repository to the app's composer.json:
"repositories": [{ "type": "path", "url": "../nativephp-ar" }]PHP changes apply immediately; Swift/Kotlin changes need php artisan native:run.
The plugin adds NSCameraUsageDescription to Info.plist (in English, with a French translation written when the app lists fr in nativephp.supported_locales) and the camera permission to the Android manifest.
use AlpineRonin\NativeAr\Anchor;
use AlpineRonin\NativeAr\Facades\AR;
if (! AR::isSupported()) {
return;
}
AR::session()
->id('kitchen')
->planes(['horizontal', 'vertical'])
->worldMap(storage_path('app/ar/kitchen.arworldmap'))
->anchors($notes->map(fn ($note) => Anchor::fromArray($note->anchor)))
->offscreenArrows()
->labels([
'hint' => 'Touchez une surface pour ajouter une note',
'relocalizing' => 'Bougez lentement pour retrouver vos notes',
])
->start();Handle the native events in a Livewire component or a native (EDGE) component:
use AlpineRonin\NativeAr\Events\{AnchorTapped, PromptSubmitted, SurfaceTapped};
use Illuminate\Support\Str;
use Native\Mobile\Attributes\OnNative;
#[OnNative(SurfaceTapped::class)]
public function onSurfaceTapped(string $id, array $transform): void
{
AR::prompt('Nouvelle note')
->placeholder('Acheter du lait…')
->buttons('Ajouter', 'Annuler')
->context(['transform' => $transform])
->show();
}
#[OnNative(PromptSubmitted::class)]
public function onPromptSubmitted(string $text, array $context): void
{
$anchor = new Anchor(Str::random(12), $context['transform'], $text, '#FFE066');
Note::create(['anchor' => $anchor->toArray()]);
AR::placeAnchor($anchor);
}
#[OnNative(AnchorTapped::class)]
public function onAnchorTapped(string $anchorId): void
{
AR::removeAnchor($anchorId);
}->datePicker('Add with reminder', 'Reminder', 'Add', 'Back') adds a third button to the prompt. It opens a date and time picker (iOS only, ignored on Android) after the text is typed. Confirming sends PromptSubmitted with date (unix timestamp), and cancelling brings the text prompt back. Without it, or with the plain submit button, date is null.
Callbacks can also be attached to the builders: ->surfaceTapped(fn (SurfaceTapped $e) => ...), ->sessionEnded(...), ->promptSubmitted(...).
AR::quickLook(public_path('models/chair.usdz'))->allowsScaling(false)->open();| PHP | Bridge function | Result |
|---|---|---|
AR::capabilities() / AR::isSupported() |
AR.Support |
sync |
AR::quickLook($source)->open() |
AR.QuickLook |
QuickLookDismissed |
AR::session()->start() |
AR.StartSession |
SessionStarted, SessionFailed, PermissionDenied |
AR::placeAnchor(Anchor) |
AR.PlaceAnchor |
sync bool, then AnchorPlaced |
AR::removeAnchor($id) |
AR.RemoveAnchor |
sync bool, then AnchorRemoved |
AR::saveWorldMap($path) |
AR.SaveWorldMap |
WorldMapSaved, WorldMapFailed |
AR::prompt($title)->show() |
AR.Prompt |
PromptSubmitted, PromptCancelled |
AR::endSession(?$saveTo) |
AR.EndSession |
SessionEnded |
Session-wide events: SurfaceTapped, AnchorTapped, TrackingStateChanged, Relocalized.
Every event carries id: the session, prompt or Quick Look id.
Native errors returned synchronously throw AlpineRonin\NativeAr\Exceptions\ArBridgeException.
Builders started implicitly (on destruct) report the exception instead of throwing it.
- A transform is a list of 16 floats, a column-major 4x4 matrix (
simd_float4x4order). Translation is at indices 12, 13, 14. SurfaceTapped::$transformis already oriented for a note: +Y is the surface normal, text "up" is world up on walls and away from the camera on tables.- A transform only makes sense in the coordinate space of the session that produced it. Across sessions:
- with
worldMap()and a saved map: ARKit relocalizes and restores the anchors itself;anchors()only provides their text, colour and size, matched by id. - without
worldMap(): anchors are placed at their raw transforms, relative to where the phone started. Useful for demos only.
- with
- With a
worldMap()path, the close button saves the map before dismissing (saveOnClose(false)to disable). - Save the map when the user has walked around: ARKit refuses to export a map that is still
limited.
Jump cannot run this plugin: it only ships the plugins compiled into the Jump app. You need a real build:
- Bifrost development builds compile iOS in the cloud and install on registered devices, no Mac needed. Requires an Apple Developer Program membership.
- Or a macOS machine / CI runner with Xcode.
Keep the AR-free parts of the app usable in Jump by guarding with AR::isSupported(), and test the PHP contract with the FakeBridge:
composer install
composer testEverything except the Swift build runs on Linux. The targets run natively (PHP 8.3 + Composer, JDK 17, Android SDK):
make install # composer install
make test # Pest suite
make android # Kotlin compile against NativePHP stubs
make stubs # check the stubs still match nativephp/mobile
make ci # all of the abovePrefix any command with ./.docker to run it in the project container instead (PHP 8.3, Composer, JDK 17, your Android SDK mounted, host network):
./.docker make ci
./.docker composer require some/packageThe Swift sources compile on macOS only (make ios), so CI runs them on a GitHub macos-15 runner, free for public repositories.
Both native checks build the plugin against small stubs of the NativePHP host app (ci/ios, ci/android); make stubs fails when upstream signatures drift.
- Android sessions with ARCore + SceneView, then Cloud Anchors for persistence.
- An embeddable
<native:ar-view>renderer for EDGE screens, so Blade UI can sit on top of the camera. - Image anchors and USDZ/GLB models as anchor content.
MIT