NativePHP Live Activities#

Keep users up to date on deliveries and ongoing tasks with one PHP API. NativePHP Live Activities provides local iOS Live Activities and Android ongoing progress notifications, with optional Android promotion where the system allows it.

iOS#

Show a title, subtitle, progress, and a colored icon on the Lock Screen and in the Dynamic Island on supported devices. Activities remain visible while your app is in the background.

Android#

Show an ongoing progress notification. On supported Android versions, the plugin also requests promotion to a Live Update, including a status-bar chip. Promotion depends on system support and user settings and is never guaranteed.

Quick start#

In an existing NativePHP Mobile app:

composer require vos/nativephp-live-activities
php artisan native:plugin:register vos/nativephp-live-activities

Remember to configure your NativePHP Composer repository and purchase credentials before running composer require.

Registration adds Vos\LiveActivities\LiveActivitiesServiceProvider to your app's App\Providers\NativeServiceProvider::plugins() list. Then rebuild:

php artisan native:run ios
# Or:
php artisan native:run android

The build hook installs the iOS widget extension automatically. Signed iOS device builds need provisioning for both the host app and its extension; simulator builds need no Apple developer account. On Android 13+, your app must request notification permission before starting an activity. This plugin does not display permission prompts.

PHP API#

use Vos\LiveActivities\ActivityContent;
use Vos\LiveActivities\ActivityIcon;
use Vos\LiveActivities\Facades\LiveActivities;
 
$activity = LiveActivities::start('delivery-42',
    ActivityContent::make('Preparing your order')->subtitle('In the kitchen')
        ->icon(ActivityIcon::Utensils)->color('#F97316')
);
 
LiveActivities::update($activity->id,
    ActivityContent::make('On the way')->progress(0.5)
        ->icon(ActivityIcon::Truck)->color('#06B6D4')
);
 
LiveActivities::all();
LiveActivities::capabilities();
LiveActivities::end($activity->id);

Use a unique key for each active activity and the returned native ID for updates and completion. Updates replace the content; ending removes the presentation immediately. Content builders are immutable, and progress ranges from 0.0 to 1.0.

Icons and accent colors#

Choose an icon using the ActivityIcon enum or its Lucide name:

$content = ActivityContent::make('Delivered')
    ->progress(1)
    ->icon('circle-check')
    ->color('#22C55E');

The bundled set includes circle-dashed, utensils, truck, circle-check, package, clock, download, and navigation. These are local Lucide icons; no network requests or additional runtime dependencies are needed. Their license notices ship in resources/icons/LICENSE.

Colors must use six-digit #RRGGBB hex notation. Unknown icon names and invalid colors throw ActivityException. Both settings are optional: the default icon is circle-dashed, with white on iOS and the system's default notification accent on Android. Updates replace the entire content, including icon and color, so include them in each update to retain your styling.

On iOS, the accent colors the icon, progress bar, and percentage. On Android, it sets the notification accent; status-bar icons stay monochrome and the system controls their tint and final presentation. Custom icon files are not supported yet.

Check availability before offering the feature:

$capabilities = LiveActivities::capabilities();
 
if ($capabilities->supported && $capabilities->enabled) {
    // The platform supports activities and the required permission is enabled.
}

promoted reports whether Android promotion can be requested, not whether an individual notification was promoted. push is currently false on both platforms.

Platform support#

Requires PHP 8.4+, Laravel 12, and NativePHP Mobile 4.5+. The OS minimums above match the package manifest, even where underlying native APIs support older versions.

The current content API supports a title, subtitle, numeric progress, a bundled icon, and an accent color with a fixed native layout. Custom images, timers, and activity-specific deep links are planned. Local updates require your app to be executing; a visible activity does not keep PHP running in the background.

Roadmap#

• More customization: presentation presets and custom icon/image support.
• Open the right screen: activity-specific deep links to an order or task.
• Show what's next: timers, ETA, indeterminate progress, freshness deadlines, and completion states with configurable dismissal.
• Stay current after users leave the app: server-driven updates with a Laravel companion package for token registration, queued updates, and remote completion.
• Integrate with less setup: permission/settings helpers, lifecycle events, and a testing fake for your application tests.

These are planned directions, not features included in the current release. Scope and release order may change; no delivery dates are committed.