webman/push

webman/push is a free server-side push plugin, with a client based on the subscription model, compatible with pusher. It has many clients such as JS, Android (Java), iOS (Swift), iOS (Obj-C), uniapp, .NET, Unity, Flutter, AngularJS, etc. The backend push SDK supports PHP, Node, Ruby, Asp, Java, Python, Go, Swift, etc. The client also comes with heartbeats and automatic reconnection, making it very simple and stable to use. It is suitable for various instant communication scenarios such as message pushing and chatting.

The plugin includes a web js client push.js and a uniapp client uniapp-push.js. Clients in other languages can be downloaded from https://pusher.com/docs/channels/channels_libraries/libraries/.

Installation

composer require webman/push

Client (JavaScript)

Import the JavaScript client

<script src="/plugin/webman/push/push.js"> </script>

Client usage (public channel)

// Establish connection
var connection = new Push({
    url: 'ws://127.0.0.1:3131', // WebSocket address
    app_key: '<app_key, get it from config/plugin/webman/push/app.php>',
    auth: '/plugin/webman/push/auth' // Subscription authentication (for private channels only)
});
// Assume user uid is 1
var uid = 1;
// Browser listens for messages on user-1 channel, which are messages for user with uid 1
var user_channel = connection.subscribe('user-' + uid);

// When there is a message event on the user-1 channel
user_channel.on('message', function(data) {
    // data contains the message content
    console.log(data);
});
// When there is a friendApply event on the user-1 channel
user_channel.on('friendApply', function (data) {
    // data contains information related to the friend request
    console.log(data);
});

// Assume group id is 2
var group_id = 2;
// Browser listens for messages on group-2 channel, which are group messages for group 2
var group_channel = connection.subscribe('group-' + group_id);
// When there is a message event on group 2
group_channel.on('message', function(data) {
    // data contains the message content
    console.log(data);
});

Tips
In the example above, subscribe implements channel subscription, and message friendApply are events on the channel. Channels and events are arbitrary strings and do not need to be pre-configured on the server.

Server-side Push (PHP)

use Webman\Push\Api;
$api = new Api(
    // In webman, you can directly use config to get the configuration; non-webman environments need to manually write the corresponding configuration
    'http://127.0.0.1:3232',
    config('plugin.webman.push.app.app_key'),
    config('plugin.webman.push.app.app_secret')
);
// Push message event to all clients subscribed to user-1
$api->trigger('user-1', 'message', [
    'from_uid' => 2,
    'content'  => 'Hello, this is the message content'
]);

Private Channels

In the example above, any user can subscribe to information through Push.js, which is not secure if the information is sensitive.

webman/push supports subscribing to private channels, which start with private-. For example

var connection = new Push({
    url: 'ws://127.0.0.1:3131', // WebSocket address
    app_key: '<app_key>',
    auth: '/plugin/webman/push/auth' // Subscription authentication (for private channels only)
});

// Assume user uid is 1
var uid = 1;
// Browser listens for messages on the private-user-1 channel
var user_channel = connection.subscribe('private-user-' + uid);

When the client subscribes to a private channel (a channel starting with private-), the browser will initiate an AJAX authentication request (the AJAX address is the one configured in the auth parameter when creating new Push), and developers can check whether the current user has permission to listen to this channel. This ensures the security of the subscription.

For authentication, refer to the code in config/plugin/webman/push/route.php.

Client Push

The above examples illustrate how clients subscribe to a channel and the server calls the API interface to push. webman/push also supports clients to push messages directly.

Note
Client-to-client push only supports private channels (channels starting with private-), and clients can only trigger events starting with client-.

Example of client triggering event push

var user_channel = connection.subscribe('private-user-1');
user_channel.on('client-message', function (data) {
    // 
});
user_channel.trigger('client-message', {form_uid:2, content:"hello"});

Note
The above code pushes data of the client-message event to all clients subscribed to private-user-1 (the pushing client will not receive its own pushed data).

Webhooks

Webhooks are used to receive certain events from channels.

Currently, there are mainly 2 events:

    1. channel_added
      Triggered when a channel transitions from having no clients online to having clients online, also known as the online event
    1. channel_removed
      Triggered when all clients of a channel go offline, also known as the offline event

Tips
These events are very useful for maintaining user online status.

Note
The webhook address is configured in config/plugin/webman/push/app.php.
The code for receiving and handling webhook events refers to the logic in config/plugin/webman/push/route.php.
User disconnections due to page refresh should not be counted as offline; webman/push will perform delayed checks, so there will be a 1-3 second delay for online/offline events.

WSS Proxy (SSL)

You cannot use ws connections under https, you need to use wss connections. In this case, you can use Nginx to proxy wss, with a configuration similar to the following:

server {
    # .... other configurations omitted ...

    location /app/<app_key>
    {
        proxy_pass http://127.0.0.1:3131;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Note: The <app_key> in the above configuration can be obtained from config/plugin/webman/push/app.php.

After restarting Nginx, connect to the server using the following method:

var connection = new Push({
    url: 'wss://example.com',
    app_key: '<app_key, get it from config/plugin/webman/push/app.php>',
    auth: '/plugin/webman/push/auth' // Subscription authentication (for private channels only)
});

Note

  1. The request address should start with wss
  2. Do not specify a port
  3. Must connect using the domain corresponding to the SSL certificate

push-vue.js Usage Instructions

  1. Copy the file push-vue.js to your project directory, e.g., src/utils/push-vue.js.

  2. Import it within your Vue page



## Other Client Addresses
`webman/push` is compatible with pusher, and you can download clients in other languages (Java, Swift, .NET, Objective-C, Unity, Flutter, Android, iOS, AngularJS, etc.) from:
https://pusher.com/docs/channels/channels_libraries/libraries/