Lifecycle & Events

tether/nativephp-client turns NativePHP mobile lifecycle and connectivity changes into normal Laravel events and automatic offline sync jobs:

• app resumes -> AppResumed event -> optional PushJob
• network returns -> NetworkStatusChanged event -> optional PushJob
• background schedule runs -> tether:sync

Configure the triggers you want, then handle the Laravel events only if your app needs custom behaviour.

App resume sync

When the app is opened again after being in the background, the package can dispatch PushJob.

This is controlled by:

'auto_sync_on_resume' => true,
'resume_cooldown' => 30,

resume_cooldown prevents repeated push jobs when the user switches between apps quickly. The cooldown is stored in SyncStateStore, so it survives normal app restarts.

PushJob performs a push sync. It sends pending local mutations to the server without blocking the user from continuing to use the app.

Connectivity sync

When the device gets network access after being offline, the package can dispatch PushJob.

This is controlled by:

'auto_sync_on_connectivity' => true,

Only reconnection triggers a push job. Losing network access does not dispatch one.

Background sync

Background sync is optional. When enabled, Tether schedules the tether:sync Artisan command through nativephp/mobile-background-tasks:

'background_sync' => true,
'background_interval' => 60,
'background_network' => 'any',
'background_long_running' => false,

Unlike resume and connectivity sync, background sync runs the full tether:sync command, so it performs push and pull.

If nativephp/mobile-background-tasks is not installed, Tether logs a warning and continues without background sync.

Listening to events

You can listen to the package events from your Laravel app if you want to update local UI state, write logs, or trigger your own application logic.

AppResumed

use Tether\NativephpClient\Events\AppResumed;

class RefreshLocalDashboard
{
    public function handle(AppResumed $event): void
    {
        // Refresh local state after the app becomes active again.
    }
}

AppResumed is a signal event and has no additional properties.

NetworkStatusChanged

use Tether\NativephpClient\Events\NetworkStatusChanged;

class UpdateConnectionState
{
    public function handle(NetworkStatusChanged $event): void
    {
        $event->connected;     // bool - true when network is available
        $event->type;          // string - wifi, cellular, unknown, etc.
        $event->isExpensive;   // bool - true for metered connections
        $event->isConstrained; // bool - true when low data mode is active
    }
}

The package's own sync listeners are registered alongside yours, so adding custom listeners does not disable automatic sync.