Search by

pushinbr / pam-native-realtime

DavidWilliamBalbino

Laravel Echo style Pusher/Reverb channels and persistent native WebSockets for PAM Native.

Package info

github.com/push-in/pam-native-realtime

Type:pam-native-plugin

pkg:composer/pushinbr/pam-native-realtime

Statistics

Installs: 383

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

v0.4.3 2026-11-19 00:22 UTC

This package is auto-updated.

Last update: 2026-11-19 00:22:27 UTC


README

pam-native-realtime: Laravel Echo style Pusher and Reverb channels on native WebSockets for PAM Native.

Laravel Echo for PAM Native: Pusher and Reverb channels, owned by the platform.
Public, private and presence channels with native reconnects, heartbeats and batched delivery to PHP.

Packagist Latest release PHP 8.5 CI License

Install · Quick example · Platforms · Permissions · Docs · Issues

Install

Inside a PAM Native project, add only this capability:

pam composer require pushinbr/pam-native-realtime
pam doctor --fix

New to PAM? Create a project with pam init my-app --template native (see the PAM Native overview), then come back here. Composer owns the manifest and the lockfile; pam composer runs it on PAM's verified PHP runtime.

Quick example

<?php

declare(strict_types=1);

use Pam\Native\Realtime\PresenceMember;
use Pam\Native\Realtime\Realtime;
use Pam\Native\Realtime\RealtimeMessage;
use Pam\Native\Realtime\RealtimeStatus;
use Pam\Native\Realtime\Secret;

// Once, after sign-in (Laravel Reverb / Pusher Channels / Soketi).
Realtime::pusher('wss://ws.example.com', key: 'app-key')            // or Realtime::reverb('ws.example.com', 'app-key')
    ->auth('https://api.example.com/broadcasting/auth', Secret::value($token))
    ->header('Origin', 'https://example.com')
    ->onConnected(fn (RealtimeStatus $s) => $this->catchUp())        // first connect and every reconnect
    ->connect();

// Echo style channels, from any screen.
Realtime::channel('private-chat.42')                                 // or Realtime::private('chat.42')
    ->listen('message.sent', fn (RealtimeMessage $m) => $this->append($m->json()))
    ->listenForWhisper('typing', fn (RealtimeMessage $m) => $this->typing($m->userId));

Realtime::join('chat-typing.42')                                     // presence-chat-typing.42
    ->here(fn (array $members) => $this->online = count($members))
    ->joining(function (PresenceMember $m): void { /* ... */ })
    ->leaving(function (PresenceMember $m): void { /* ... */ })
    ->whisper('typing', ['typing' => true]);                         // sent as client-typing

Realtime::leave('chat.42');                                          // leaves chat.42, private-… and presence-…
Realtime::token($refreshed);                                         // new bearer; 401/403 channels retry at once
$headers['X-Socket-ID'] = Realtime::socketId() ?? '';                // Laravel toOthers()

The socket, the Pusher protocol, channel auth, heartbeats, reconnects and re-subscription run natively; PHP receives coalesced batches (one render per burst, no polling, no PHP timer). A runnable presence chat room is in example/. Full details: API reference · Batching and connection lifecycle · A real example: Zé Chat.

Platform support

Platform Support Notes
Android API 24+ OkHttp 5.3.0
iOS 15.0+ URLSessionWebSocketTask, NWPathMonitor; not validated on a device yet (see ios/Tests/PusherTests.swift)
PAM Native 1.0.35 to < 2.0.0 From pam-native.plugin.json; PHP 8.5+

Permissions and requirements

Platform Declared by the plugin
Android android.permission.INTERNET, android.permission.ACCESS_NETWORK_STATE (network-change recovery). No runtime permission.
iOS Framework Network (NWPathMonitor); no Info.plist keys.

The package is a PAM Native plugin (module realtime); nothing is added to pam-native.json. The socket does not run while iOS suspends the app; once the app runs again the liveness checks reconnect and re-subscribe (call Realtime::reconnect() on AppState::Active to skip a pending backoff). End-to-end encrypted channels (private-encrypted-*) are rejected.

What you can build

  • Chat, presence and collaborative state
  • Live dashboards and operations consoles
  • Realtime alerts and server-driven updates
Native path OkHttp WebSocket · URLSessionWebSocketTask
Application model Composer package + generated native integration
Design rule Independent module; no feed, vertical or application template bundled

Compatibility

pushinbr/pam-native-realtime pushinbr/pam-native Android iOS
0.4.x >=1.0.35 <2.0.0 (tested with 1.14.x) API 26+ 15+ (Pusher client)
0.3.x >=1.0.35 <2.0.0 API 26+ Raw socket only

Testing

pam tests/run.php                                                    # PHP contracts (fake native transport)
cd android && ANDROID_SERIAL=emulator-5558 \
  ../../../pam-native/android/gradlew -p . connectedDebugAndroidTest   # Pusher protocol suite against MockWebServer

Production rules

  • Accept only authenticated wss:// endpoints and an https:// auth endpoint.
  • Refresh credentials with Realtime::token() instead of reconnecting.
  • Resynchronize from your API in onConnected (reconnects) and onDropped.
  • Run pam doctor, pam test and a signed release build on every supported platform.

Security vulnerabilities should be reported through the repository security policy or GitHub private vulnerability reporting, not a public issue.

Docs

Part of the PAM ecosystem

PAM

PAM runs PHP natively on servers, desktops and phones. This repository is one piece of it.

PAM PAM Desktop PAM Native Ecosystem
the runtime and CLI native desktop apps in PHP native Android and iOS apps in PHP every official package and plugin

Docs: push-in.github.io/pam-docs · Issues

Apache License 2.0 · Made in Brazil by Pushin