NativePHP Live Activities#

Keep users up to date on deliveries and ongoing tasks while your background is in the background. NativePHP Live Activities provides local iOS Live Activities and Android ongoing progress notifications, with optional Android promotion where the system allows it.

Features include:

Managing activities -> show when your app starts, updates, or ends an activity.
Icons -> use the bundled icons, pass your own custom icons, or create them at runtime.
Deep links -> allow users to navigate to the activity with a single tap.

... and more:

Full documentation

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.

iOS demo

Read the full docs for iOS setup and signing.

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.

Android demo

Read the full docs for Android permissions and Live Update promotion.

Quick start#

In an existing NativePHP Mobile app:

Copied!

composer require vos/nativephp-live-activities
php artisan vendor:publish --tag=nativephp-plugins-provider
php artisan native:plugin:register vos/nativephp-live-activities
php artisan native:plugin:list

composer require vos/nativephp-live-activities
php artisan vendor:publish --tag=nativephp-plugins-provider
php artisan native:plugin:register vos/nativephp-live-activities
php artisan native:plugin:list

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

Rebuild your app for your chosen platform after registration. On Android 13+, request notification permission before starting an activity.

Read the full docs for installation and your first activity.

PHP API#

Copied!

use Vos\LiveActivities\ActivityContent;
use Vos\LiveActivities\Icons\LucideUtensils;
use Vos\LiveActivities\Icons\LucideTruck;
use Vos\LiveActivities\Facades\LiveActivities;
use Vos\LiveActivities\LiveActivity;
 
$activity = LiveActivity::make('delivery-42',
    ActivityContent::make('Preparing your order')->subtitle('In the kitchen')
        ->icon(new LucideUtensils)->color('#F97316')
)->withLink('myapp://orders/42'); // optional
$activity->start();
 
$activity->update(
    ActivityContent::make('On the way')->progress(0.5)
        ->icon(new LucideTruck)->color('#06B6D4')
);
 
LiveActivity::all();
LiveActivities::capabilities();
$activity->end();

use Vos\LiveActivities\ActivityContent;
use Vos\LiveActivities\Icons\LucideUtensils;
use Vos\LiveActivities\Icons\LucideTruck;
use Vos\LiveActivities\Facades\LiveActivities;
use Vos\LiveActivities\LiveActivity;

$activity = LiveActivity::make('delivery-42',
    ActivityContent::make('Preparing your order')->subtitle('In the kitchen')
        ->icon(new LucideUtensils)->color('#F97316')
)->withLink('myapp://orders/42'); // optional
$activity->start();

$activity->update(
    ActivityContent::make('On the way')->progress(0.5)
        ->icon(new LucideTruck)->color('#06B6D4')
);

LiveActivity::all();
LiveActivities::capabilities();
$activity->end();

Give each activity a unique key. Call start() to show it, update() to replace what it shows, and end() to remove it. Progress ranges from 0.0 to 1.0.

ETA and countdowns#

Show how much time is left until a task is expected to finish:

Copied!

$readyAt = now()->addMinutes(8);
 
$activity = LiveActivity::make('pasta-timer',
    ActivityContent::make('Cooking pasta')->countdown($readyAt)
);
$activity->start();

$readyAt = now()->addMinutes(8);

$activity = LiveActivity::make('pasta-timer',
    ActivityContent::make('Cooking pasta')->countdown($readyAt)
);
$activity->start();

start() shows the countdown; it does not reset the clock. In this example, the eight minutes begin when $readyAt is calculated. If you wait two minutes before calling start(), it shows about six minutes remaining. Once visible, the countdown keeps ticking even when the app is in the background.

To show the expected finish time instead (such as “18:30”), use eta():

Copied!

$activity->update(
    ActivityContent::make('Cooking pasta')->eta($readyAt)
);

$activity->update(
    ActivityContent::make('Cooking pasta')->eta($readyAt)
);

Using the same $readyAt keeps the original deadline. The time is shown in the user's local time zone.

Reaching zero does not end the activity or sound an alarm. iOS leaves the countdown at zero; Android shows negative time once the deadline passes. When the task is done, call $activity->end() while your app is running to remove it.

Read the full docs for the PHP API and lifecycle, deep links, and capability checks.

Icons#

Use bundled Lucide icons as shown above, or register your own:

Create a class marked by an #[Icon] attribute:

Copied!

namespace App\Icons;
 
use Vos\LiveActivities\Attributes\Icon;
use Vos\LiveActivities\IconArtwork;
 
#[Icon]
final class DeliveryBike
{
    public function source(): IconArtwork
    {
        return IconArtwork::template(
            resource_path('path/to/image/delivery-bike.png'),
        );
    }
}

namespace App\Icons;

use Vos\LiveActivities\Attributes\Icon;
use Vos\LiveActivities\IconArtwork;

#[Icon]
final class DeliveryBike
{
    public function source(): IconArtwork
    {
        return IconArtwork::template(
            resource_path('path/to/image/delivery-bike.png'),
        );
    }
}

Publish the configuration, then list the icon classes to bundle:

Copied!

php artisan vendor:publish --tag=live-activities-config

php artisan vendor:publish --tag=live-activities-config

Copied!

// config/live-activities.php
'icons' => [
    App\Icons\DeliveryBike::class,
],

// config/live-activities.php
'icons' => [
    App\Icons\DeliveryBike::class,
],

Prepare the platform sizes and commit the generated directory:

Copied!

php artisan live-activities:prepare-icons

php artisan live-activities:prepare-icons

Copied!

use App\Icons\DeliveryBike;
 
$content = ActivityContent::make('On the way')
    ->icon(new DeliveryBike)
    ->color('#06B6D4');

use App\Icons\DeliveryBike;

$content = ActivityContent::make('On the way')
    ->icon(new DeliveryBike)
    ->color('#06B6D4');

Committing resources/live-activities/prepared lets builds reuse the prepared PNGs.

Read the full docs for bundled icons, SVG conversion, runtime artwork, and rendering modes.

Testing your application#

The plugin provides response and assertion helpers for NativePHP’s FakeBridge, with ActivityFixture for scripted native responses.

Read the full docs for application testing and all bridge helpers.

Platform support#

Requires PHP 8.4+, Laravel 12, NativePHP Mobile 4.5+, iOS 18+ or Android 10+. Local updates require your app to be executing; a visible activity does not keep PHP running in the background. Android Live Update promotion depends on system support and user settings. Server-driven updates are planned.

Read the full docs for platform support and limitations, configuration, and the roadmap.