Download the PHP package nativephp/mobile-vibe without Composer

Vibe — websockets for NativePHP Mobile

Vibe brings live server events into your NativePHP Mobile app over the Pusher protocol — so it works with Vask, Laravel Reverb, or Pusher without changing your code. Your PHP components subscribe to channels and react to broadcasts, exactly like Laravel Echo does in the browser.

The websocket lives on the native side (Swift/Kotlin, via the official Pusher SDKs); PHP just declares what to subscribe to and handles the events.

Requirements

• PHP 8.3+, nativephp/mobile v4 with Edge components (NativeComponent) — v3 is not supported: the plugin's native event pipeline (NativeElementBridge) only exists in the v4 core
• A Pusher-protocol websocket server: Vask, Laravel Reverb, or Pusher

Install

Configure

Use the standard Laravel PUSHER_* vars in your app's .env (they're bundled into the app at build time):

The app secret is never shipped to the device.

If PUSHER_APP_KEY / PUSHER_HOST are missing when you subscribe on-device, Vibe throws a VibeException immediately rather than failing silently.

Public channels

Events arrive as native events and re-render the component. Match the event name to what your server broadcasts — without broadcastAs() that's the full class name (App\Events\OrderShipped), so use broadcastAs() to keep it short. Unlike Laravel Echo, do not prefix the name with a dot: Vibe matches the raw broadcast name ('OrderShipped', not '.OrderShipped').

Listeners are channel-scoped: an OrderShipped listener on orders never fires for a different channel that happens to broadcast the same event name.

You can also use an attribute instead of the fluent ->on() — pass the channel so the listener is scoped (use the full name as subscribed, e.g. private-orders.42 for Vibe::private('orders.42')):

Private channels

Private (private-) and presence (presence-) channels require a signed authorization from your remote Laravel backend. The default /broadcasting/auth route is session-guarded, which won't work for a mobile bearer token — register it under your API middleware instead:

Then point Vibe at it and give it the current bearer token:

Subscribing to a private/presence channel without VIBE_AUTH_ENDPOINT set throws a VibeException.

After a re-login / token refresh, push the new token to the live connection:

Presence channels

Presence channels track who's online. The auth response carries channel_data (user id + info); Vibe surfaces the roster and member changes:

On reconnect the SDKs re-subscribe and the here roster is delivered again — you don't need to rebuild presence state manually.

Whispers (client events)

Send ephemeral events directly to the other subscribers of a private/presence channel (no server round-trip, not persisted) — typing indicators, cursors:

Connection lifecycle & errors

• onReconnect / onDisconnect / onError are connection-level — they fire regardless of which subscription registered them.
• onError receives { type, channel, message } for failed channel auth (e.g. a 403 from /broadcasting/auth), failed subscriptions, and connection errors — the failures that are otherwise invisible on a device.

Lifecycle

• Subscriptions are torn down automatically when the component unmounts — including attribute-only usage (Vibe::channel(...) in mount() + #[OnEcho]).
• Channels are refcounted natively: if two components subscribe to the same channel, it stays open until the last one leaves. The socket disconnects when no channels remain.
• Listeners must be registered from within a NativeComponent (typically mount()); registering elsewhere throws a VibeException.

On your server

The app is a plain Pusher-protocol subscriber, so the server side is standard Laravel broadcasting. The three pieces Vibe cares about:

Whispers require client events to be enabled on your websocket server (Pusher: app settings → "Enable client events"; check your Reverb/Vask config).

Troubleshooting

Nothing arrives:

• Event name mismatch — no broadcastAs() means the name is the FQCN (App\Events\OrderShipped); and no leading dot, unlike Echo.
• #[OnEcho] channel mismatch — use the full channel name as subscribed: channel: 'private-orders.42', not channel: 'orders.42'.
• The app is backgrounded — the OS suspends the socket; events are foreground-only.
• Queued broadcasts need a running queue worker on the server (or ShouldBroadcastNow).

Private/presence fails: attach ->onError() — auth rejections arrive as auth_failed / subscription_failed with the reason. Usual suspects: expired bearer token, VIBE_AUTH_ENDPOINT pointing at a dead tunnel/host, or the backend route not guarded by an API (token) middleware.

Misconfiguration throws: missing PUSHER_APP_KEY/PUSHER_HOST, or a private/presence subscribe without VIBE_AUTH_ENDPOINT, throws VibeException at subscribe-time rather than failing silently.

Notes

• Websockets are foreground-only on mobile (the OS suspends the socket in the background). For delivery while the app is closed, use push notifications.
• Websocket events signal liveness, not source of truth — on reconnect, refetch authoritative state (onReconnect is built for exactly this).