Tether NativePHP Client#

Laravel Tether is an offline-first synchronization framework for Laravel. It allows applications to continue working with local data while offline, then automatically synchronize changes with your server when connectivity returns or whenever it suits your system best.

Learn more: https://laravel-tether.com/

tether/nativephp-client extends Laravel Tether for NativePHP Mobile by automatically triggering synchronization when your app resumes or the device reconnects to the network.

Built on top of open source tether/client, it adds mobile lifecycle and connectivity awareness while keeping the entire synchronization engine in PHP. With optional background sync support, your app can continue synchronizing even when it isn't actively in use.

Detailed documentation: https://laravel-tether.com/docs/v1/nativephp/overview

Tether Packages#

Laravel Tether is split into focused packages, each with a specific responsibility:

Package	Purpose
`tether/server`	Hosts the synchronization API, receives client mutations, resolves conflicts, and provides server-side synchronization logic.
`tether/client`	Records local mutations and provides the offline-first synchronization engine used by every client application.
`tether/nativephp-client`	Integrates `tether/client` with NativePHP Mobile lifecycle and connectivity events.

If you're new to Laravel Tether, start with tether/server and tether/client. This package is an optional add-on for NativePHP Mobile applications.

What It Does#

Automatically triggers tether/client data synchronization when the app resumes or when network connectivity is restored.
Exposes mobile application lifecycle events and connectivity changes as standard Laravel events.
Automatically integrates with nativephp/mobile-background-tasks if it's present in the project and runs data synchronization as a background task.
Supports both Android and iOS without requiring application-specific Kotlin or Swift.

Requirements#

PHP ^8.2
Laravel ^12.0 or newer
NativePHP Mobile ^3.0
Optional: nativephp/mobile-background-tasks

Installation#

Copied!

composer require tether/nativephp-client
php artisan native:plugin:register tether/nativephp-client
php artisan vendor:publish --tag=tether-nativephp-config

composer require tether/nativephp-client
php artisan native:plugin:register tether/nativephp-client
php artisan vendor:publish --tag=tether-nativephp-config

Configuration#

Publishing the configuration creates config/tether-nativephp.php.

Copied!

return [
    'auto_sync_on_resume' => env('TETHER_NATIVE_AUTO_SYNC_ON_RESUME', true),
    'resume_cooldown' => (int) env('TETHER_NATIVE_RESUME_COOLDOWN', 30),
 
    'auto_sync_on_connectivity' => env('TETHER_NATIVE_AUTO_SYNC_ON_CONNECTIVITY', true),
 
    'background_sync' => env('TETHER_NATIVE_BACKGROUND_SYNC', false),
    'background_interval' => (int) env('TETHER_NATIVE_BACKGROUND_INTERVAL', 60),
    'background_network' => env('TETHER_NATIVE_BACKGROUND_NETWORK', 'any'),
    'background_long_running' => env('TETHER_NATIVE_BACKGROUND_LONG_RUNNING', false),
];

return [
    'auto_sync_on_resume' => env('TETHER_NATIVE_AUTO_SYNC_ON_RESUME', true),
    'resume_cooldown' => (int) env('TETHER_NATIVE_RESUME_COOLDOWN', 30),

    'auto_sync_on_connectivity' => env('TETHER_NATIVE_AUTO_SYNC_ON_CONNECTIVITY', true),

    'background_sync' => env('TETHER_NATIVE_BACKGROUND_SYNC', false),
    'background_interval' => (int) env('TETHER_NATIVE_BACKGROUND_INTERVAL', 60),
    'background_network' => env('TETHER_NATIVE_BACKGROUND_NETWORK', 'any'),
    'background_long_running' => env('TETHER_NATIVE_BACKGROUND_LONG_RUNNING', false),
];

The default configuration is suitable for most applications.

Resume and connectivity sync are enabled by default.

Sync Triggers#

App Resume#

When the app returns to the foreground, the package dispatches AppResumed event.

If auto_sync_on_resume is enabled, \Tether\Client\Jobs\PushJob is automatically queued.

resume_cooldown prevents repeated sync attempts when users rapidly switch between apps. The cooldown timestamp survives normal app restarts.

Connectivity Restored#

When network connectivity is restored, the package dispatches NetworkStatusChanged.

If auto_sync_on_connectivity is enabled and the device is online, a \Tether\Client\Jobs\PushJob is automatically queued.

Going offline never triggers synchronization.

Background Sync#

When background_sync is enabled, the package registers the tether:sync Artisan command with nativephp/mobile-background-tasks.

Copied!

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

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

Resume and connectivity triggers only push pending local mutations.

Background sync executes the full tether:sync command, performing both push and pull synchronization.

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

Laravel Events#

The package exposes NativePHP lifecycle events so your application can react to app resume and connectivity changes independently of Tether's automatic synchronization.

Copied!

use Tether\NativephpClient\Events\AppResumed;
 
class RefreshLocalDashboard
{
    public function handle(AppResumed $event): void
    {
        // The app became active again.
    }
}

use Tether\NativephpClient\Events\AppResumed;

class RefreshLocalDashboard
{
    public function handle(AppResumed $event): void
    {
        // The app became active again.
    }
}

Copied!

use Tether\NativephpClient\Events\NetworkStatusChanged;
 
class UpdateConnectionState
{
    public function handle(NetworkStatusChanged $event): void
    {
        $event->connected;     // bool
        $event->type;          // wifi, cellular, unknown, etc.
        $event->isExpensive;   // metered connection
        $event->isConstrained; // low data mode
    }
}

use Tether\NativephpClient\Events\NetworkStatusChanged;

class UpdateConnectionState
{
    public function handle(NetworkStatusChanged $event): void
    {
        $event->connected;     // bool
        $event->type;          // wifi, cellular, unknown, etc.
        $event->isExpensive;   // metered connection
        $event->isConstrained; // low data mode
    }
}

Your listeners run alongside the package's built-in synchronization listeners.

Package Position#

tether/nativephp-client complements tether/client; it does not replace it.

tether/client owns local mutation tracking and the offline-first synchronization engine.
tether/nativephp-client decides when that engine should synchronize based on application's lifecycle and connectivity events.

This separation keeps synchronization deterministic while allowing mobile applications to respond naturally to operating system events.

Licensing#

tether/nativephp-client is a commercial Tether add-on distributed through private Composer repositories.

Once you've purchased it via https://laravel-tether.com/ or NativePHP Plugin marketplace, you can use it on any number of projects without any limitations.