NativePHP Events

This skill provides guidance for handling events dispatched from native device functionality to your Laravel application.

Overview

NativePHP uses an event system to handle asynchronous native operations. When a user takes a photo, scans a QR code, or completes biometric authentication, native code dispatches events that your application can listen for.

Synchronous vs Asynchronous Operations

Synchronous - Execute immediately, no event needed:

• Haptics::vibrate()
• Device::flashlight()
• Dialog::toast('Hello!')
• SecureStorage::set() / get() / delete()
• System::isIos() / isAndroid()

Asynchronous - Trigger native UI, dispatch event on completion:

• Camera::getPhoto() → PhotoTaken / PhotoCancelled
• Camera::recordVideo() → VideoRecorded / VideoCancelled
• Camera::pickImages() → MediaSelected
• Scanner::scan() → CodeScanned
• Biometrics::prompt() → Completed
• Geolocation::getCurrentPosition() → LocationReceived
• Microphone::record() → MicrophoneRecorded / MicrophoneCancelled
• Dialog::alert() → ButtonPressed
• PushNotifications::enroll() → TokenGenerated

Event Dispatching Pattern

Native code (Kotlin/Swift) dispatches events via JavaScript injection to the WebView:

window.Livewire.dispatch('native:Native\\Mobile\\Events\\Camera\\PhotoTaken', payload)

Events are broadcast to both frontend (Livewire/JavaScript) and backend (Laravel listeners).

Listening in Livewire Components

Using #[OnNative] Attribute (REQUIRED)

NativePHP provides a custom #[OnNative] attribute that MUST be used for listening to native events. This attribute automatically handles the native: prefix and event class resolution.

use Livewire\Component;
use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Events\Camera\PhotoTaken;
use Native\Mobile\Events\Camera\PhotoCancelled;

class PhotoUploader extends Component
{
    #[OnNative(PhotoTaken::class)]
    public function handlePhotoTaken(string $path, string $mimeType = 'image/jpeg', ?string $id = null)
    {
        // Handle the photo
        $this->photoPath = $path;
    }

    #[OnNative(PhotoCancelled::class)]
    public function handlePhotoCancelled(bool $cancelled = true, ?string $id = null)
    {
        // Handle cancellation
    }
}

IMPORTANT: Always use #[OnNative(EventClass::class)] - NEVER use the raw #[On('native:...')] syntax. The OnNative attribute from Native\Mobile\Attributes\OnNative is the required pattern for NativePHP applications.

All Available Events

Camera Events

PhotoTaken - Native\Mobile\Events\Camera\PhotoTaken

public string $path;
public string $mimeType = 'image/jpeg';
public ?string $id;

PhotoCancelled - Native\Mobile\Events\Camera\PhotoCancelled

public bool $cancelled = true;
public ?string $id;

VideoRecorded - Native\Mobile\Events\Camera\VideoRecorded

public string $path;
public string $mimeType = 'video/mp4';
public ?string $id;

VideoCancelled - Native\Mobile\Events\Camera\VideoCancelled

public bool $cancelled = true;
public ?string $id;

Gallery Events

MediaSelected - Native\Mobile\Events\Gallery\MediaSelected

public bool $success;
public array $files = [];
public int $count = 0;
public ?string $error;
public bool $cancelled = false;
public ?string $id;

Scanner Events

CodeScanned - Native\Mobile\Events\Scanner\CodeScanned

public string $data;
public string $format;
public ?string $id;

Biometric Events

Completed - Native\Mobile\Events\Biometric\Completed

public bool $success;
public ?string $id;

Dialog Events

ButtonPressed - Native\Mobile\Events\Alert\ButtonPressed

public int $index;
public string $label;
public ?string $id;

Microphone Events

MicrophoneRecorded - Native\Mobile\Events\Microphone\MicrophoneRecorded

public string $path;
public string $mimeType = 'audio/m4a';
public ?string $id;

MicrophoneCancelled - Native\Mobile\Events\Microphone\MicrophoneCancelled

public bool $cancelled = true;
public ?string $id;

Geolocation Events

LocationReceived - Native\Mobile\Events\Geolocation\LocationReceived

public bool $success;
public ?float $latitude;
public ?float $longitude;
public ?float $accuracy;
public ?int $timestamp;
public ?string $provider;
public ?string $error;
public ?string $id;

PermissionStatusReceived - Native\Mobile\Events\Geolocation\PermissionStatusReceived

public string $location;
public string $coarseLocation;
public string $fineLocation;
public ?string $id;

PermissionRequestResult - Native\Mobile\Events\Geolocation\PermissionRequestResult

public string $location;
public string $coarseLocation;
public string $fineLocation;
public ?string $error;
public ?string $id;

Push Notification Events

TokenGenerated - Native\Mobile\Events\PushNotification\TokenGenerated

public string $token;
public ?string $id;

App Events

UpdateInstalled - Native\Mobile\Events\App\UpdateInstalled

public string $version;
public int $timestamp;

Custom Event Classes

Create custom events by extending built-in events:

namespace App\Events;

use Native\Mobile\Events\Camera\PhotoTaken;

class ProfilePhotoTaken extends PhotoTaken
{
    // Add custom properties or methods
}

Use with fluent API:

Camera::getPhoto()
    ->id('profile')
    ->event(ProfilePhotoTaken::class)
    ->start();

Listen for custom event:

#[OnNative(ProfilePhotoTaken::class)]
public function handleProfilePhoto(string $path)
{
    // Handle profile photo specifically
}

Tracking Requests with IDs

Use IDs to correlate requests with responses:

// In your component
public function takePhoto()
{
    Camera::getPhoto()
        ->id('avatar-' . auth()->id())
        ->remember()
        ->start();
}

#[OnNative(PhotoTaken::class)]
public function handlePhoto(string $path, string $mimeType, ?string $id)
{
    if ($id === 'avatar-' . auth()->id()) {
        // This is the avatar photo
    }
}

// Or retrieve last ID from session
$lastId = Camera::getPhoto()->lastId();

Backend Event Listeners

Listen in Laravel using standard listeners:

// app/Listeners/ProcessPhotoUpload.php
namespace App\Listeners;

use Native\Mobile\Events\Camera\PhotoTaken;

class ProcessPhotoUpload
{
    public function handle(PhotoTaken $event): void
    {
        // Process the photo on the backend
        Storage::disk('s3')->put('photos/' . basename($event->path),
            file_get_contents($event->path));
    }
}

Register in EventServiceProvider:

protected $listen = [
    PhotoTaken::class => [
        ProcessPhotoUpload::class,
    ],
];

Event Class Structure

All events are simple POJOs (Plain Old Java Objects pattern):

• Use Dispatchable and SerializesModels traits
• Do NOT implement ShouldBroadcast
• Do NOT use broadcasting channels
• Properties are public for direct access

namespace Native\Mobile\Events\Camera;

use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class PhotoTaken
{
    use Dispatchable, SerializesModels;

    public function __construct(
        public string $path,
        public string $mimeType = 'image/jpeg',
        public ?string $id = null
    ) {}
}

Fetching Live Documentation

For detailed event documentation:

• Events Overview: https://nativephp.com/docs/mobile/2/the-basics/events

Use WebFetch to retrieve the latest event handling patterns.