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.

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();

Use a unique key for each active activity. start(): void stores the native ID on the same instance; update() and end() operate on that ID. Updates replace the content; ending removes the presentation immediately. Content builders are immutable, and progress ranges from 0.0 to 1.0.

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.