Skip to main content
NativePHP Mobile dispatches Laravel events throughout the app lifecycle and when native features are used. This allows your application to respond to device-level events just like any other Laravel event.

​
Listening to Events

You can listen to NativePHP events in several ways:

​
Event Listeners

Register listeners in EventServiceProvider: 
use Native\Mobile\Events\Camera\PhotoTaken;
use App\Listeners\ProcessPhoto;

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

​
Livewire Components

Use the #[On] attribute to listen in Livewire components: 
use Livewire\Component;
use Livewire\Attributes\On;
use Native\Mobile\Events\Camera\PhotoTaken;

class PhotoUploader extends Component
{
    #[On('native:Native\\Mobile\\Events\\Camera\\PhotoTaken')]
    public function photoTaken($path, $mimeType, $id)
    {
        // Handle the photo
        $this->uploadPhoto($path);
    }
}
Notice the native: prefix and double-escaped backslashes when using the #[On] attribute with NativePHP events.

​
Closure Listeners

Register inline listeners in a service provider: 
use Illuminate\Support\Facades\Event;
use Native\Mobile\Events\Scanner\CodeScanned;

Event::listen(function (CodeScanned $event) {
    Log::info('QR Code scanned', [
        'data' => $event->data,
        'format' => $event->format,
    ]);
});

​
Application Lifecycle Events

​
UpdateInstalled

Dispatched when an app update is installed on the device. 
namespace Native\Mobile\Events\App;

class UpdateInstalled
{
    public function __construct(
        public readonly string $version,
        public readonly int $timestamp
    ) {}
}
​
version
string
The new version number that was installed
​
timestamp
int
Unix timestamp when the update was installed

​
Camera Events

Events dispatched when using the camera APIs.

​
PhotoTaken

Dispatched when a photo is successfully captured. 
namespace Native\Mobile\Events\Camera;

class PhotoTaken
{
    public function __construct(
        public string $path,
        public string $mimeType = 'image/jpeg',
        public ?string $id = null
    ) {}
}
​
path
string
Path to the captured photo in temp storage
​
mimeType
string
default:"image/jpeg"
MIME type of the image
​
id
string | null
Optional identifier passed when calling the camera

​
PhotoCancelled

Dispatched when the user cancels photo capture. 
namespace Native\Mobile\Events\Camera;

class PhotoCancelled
{
    public function __construct(
        public ?string $id = null
    ) {}
}

​
VideoRecorded

Dispatched when a video is successfully recorded. 
namespace Native\Mobile\Events\Camera;

class VideoRecorded
{
    public function __construct(
        public string $path,
        public string $mimeType = 'video/mp4',
        public ?string $id = null
    ) {}
}

​
VideoCancelled

Dispatched when the user cancels video recording. 
namespace Native\Mobile\Events\Camera;

class VideoCancelled
{
    public function __construct(
        public ?string $id = null
    ) {}
}

​
PermissionDenied

Dispatched when camera permission is denied by the user. 
namespace Native\Mobile\Events\Camera;

class PermissionDenied
{
    public function __construct(
        public ?string $id = null
    ) {}
}

​
Scanner Events

Events for QR code and barcode scanning.

​
CodeScanned

Dispatched when a code is successfully scanned. 
namespace Native\Mobile\Events\Scanner;

class CodeScanned
{
    public function __construct(
        public string $data,
        public string $format,
        public ?string $id = null
    ) {}
}
​
data
string
The scanned data (URL, text, etc.)
​
format
string
Barcode format (e.g., QR_CODE, EAN_13, CODE_128)
​
id
string | null
Optional identifier passed when calling the scanner

​
ScannerCancelled

Dispatched when the user cancels scanning. 
namespace Native\Mobile\Events\Scanner;

class ScannerCancelled
{
    public function __construct(
        public ?string $id = null
    ) {}
}

​
Geolocation Events

​
LocationReceived

Dispatched when location data is received from the device. 
namespace Native\Mobile\Events\Geolocation;

class LocationReceived
{
    public function __construct(
        public bool $success,
        public ?float $latitude = null,
        public ?float $longitude = null,
        public ?float $accuracy = null,
        public ?int $timestamp = null,
        public ?string $provider = null,
        public ?string $error = null,
        public ?string $id = null
    ) {}
}
​
success
bool
Whether location was successfully retrieved
​
latitude
float | null
Latitude coordinate
​
longitude
float | null
Longitude coordinate
​
accuracy
float | null
Accuracy in meters
​
timestamp
int | null
Unix timestamp of the location fix
​
provider
string | null
Location provider (e.g., gps, network)
​
error
string | null
Error message if success is false

​
PermissionRequestResult

Dispatched after requesting location permission. 
namespace Native\Mobile\Events\Geolocation;

class PermissionRequestResult
{
    public function __construct(
        public bool $granted,
        public ?string $id = null
    ) {}
}

​
PermissionStatusReceived

Dispatched when checking current location permission status. 
namespace Native\Mobile\Events\Geolocation;

class PermissionStatusReceived
{
    public function __construct(
        public bool $granted,
        public ?string $id = null
    ) {}
}

​
Alert Events

​
ButtonPressed

Dispatched when a user taps a button in a native alert dialog. 
namespace Native\Mobile\Events\Alert;

class ButtonPressed
{
    public function __construct(
        public int $index,
        public string $label,
        public ?string $id = null
    ) {}
}
​
index
int
Zero-based index of the pressed button
​
label
string
Text label of the pressed button

​
Biometric Events

​
Completed

Dispatched after biometric authentication attempt. 
namespace Native\Mobile\Events\Biometric;

class Completed
{
    public function __construct(
        public bool $success,
        public ?string $error = null,
        public ?string $id = null
    ) {}
}

​
MediaSelected

Dispatched when user selects media from the gallery. 
namespace Native\Mobile\Events\Gallery;

class MediaSelected
{
    public function __construct(
        public array $files,
        public ?string $id = null
    ) {}
}

​
Microphone Events

​
MicrophoneRecorded

Dispatched when audio recording is completed. 
namespace Native\Mobile\Events\Microphone;

class MicrophoneRecorded
{
    public function __construct(
        public string $path,
        public ?string $id = null
    ) {}
}

​
MicrophoneCancelled

Dispatched when user cancels audio recording. 
namespace Native\Mobile\Events\Microphone;

class MicrophoneCancelled
{
    public function __construct(
        public ?string $id = null
    ) {}
}

​
Push Notification Events

​
TokenGenerated

Dispatched when a push notification token is generated. 
namespace Native\Mobile\Events\PushNotification;

class TokenGenerated
{
    public function __construct(
        public string $token,
        public ?string $id = null
    ) {}
}

​
Wallet Events

Events for mobile payment processing (Apple Pay, Google Pay).

​
PaymentCompleted

Dispatched when payment is successfully completed. 
namespace Native\Mobile\Events\Wallet;

class PaymentCompleted
{
    public function __construct(
        public array $data,
        public ?string $id = null
    ) {}
}

​
PaymentCancelled

Dispatched when user cancels payment. 
namespace Native\Mobile\Events\Wallet;

class PaymentCancelled
{
    public function __construct(
        public ?string $id = null
    ) {}
}

​
PaymentFailed

Dispatched when payment fails. 
namespace Native\Mobile\Events\Wallet;

class PaymentFailed
{
    public function __construct(
        public string $error,
        public ?string $id = null
    ) {}
}

​
Event ID Pattern

Most events include an optional $id parameter. Use this to track which action triggered the event when you have multiple instances: 
// Trigger camera with ID
Camera::takePhoto(['id' => 'profile-photo']);

// Listen for that specific photo
#[On('native:Native\\Mobile\\Events\\Camera\\PhotoTaken')]
public function photoTaken($path, $mimeType, $id)
{
    if ($id === 'profile-photo') {
        $this->updateProfilePhoto($path);
    }
}

​
Best Practices

Queue long-running tasks: Event listeners should be fast. If you need to process large files or make API calls, dispatch a queued job instead.
use Native\Mobile\Events\Camera\PhotoTaken;
use App\Jobs\ProcessPhoto;

Event::listen(function (PhotoTaken $event) {
    ProcessPhoto::dispatch($event->path);
});
Handle failures gracefully: Native events can fail (permissions denied, user cancels, etc.). Always implement cancellation and error event handlers.
use Native\Mobile\Events\Camera\PhotoTaken;
use Native\Mobile\Events\Camera\PhotoCancelled;
use Native\Mobile\Events\Camera\PermissionDenied;

// Success case
Event::listen(fn(PhotoTaken $e) => $this->processPhoto($e->path));

// User cancelled
Event::listen(fn(PhotoCancelled $e) => $this->showMessage('Photo cancelled'));

// Permission denied
Event::listen(fn(PermissionDenied $e) => $this->promptForPermission());

​
Next Steps

Camera

Learn about camera APIs and events

Scanner

QR code and barcode scanning

Geolocation

Access device location

Configuration

Configure app behavior

Build docs developers (and LLMs) love

Get started for freeTalk to us