Ws

a WebSocket module for Emvicy2 (2.x) PHP Framework: https://github.com/emvicy/Emvicy/tree/2.x

---

Installation

cd into the modules folder of your Emvicy copy; e.g.:

cd /var/www/html/modules/;

git clone

git clone --branch 2.x https://github.com/emvicy/Ws.git Ws;

run install bash script

cd Ws/; \
./_install.sh

add styles and scripts to your (primary module) routes

$oDTRoutingAdditional = DTRoutingAdditional::create()
    ...
    ->set_aStyle(array (
        ...    
        // WS
        '/Ws_old/assets/pnotify.min.css',
        '/Ws_old/assets/pnotify.brighttheme.min.css',
    ))
    ->set_aScript(array (
        ...
        // WS
        '/Ws_old/assets/pnotify.min.js',
        '/Ws_old/assets/pnotify.desktop.min.js',
        
        // contains the `WsProcess` function
        '/Ws_old/scripts/pnotify.min.js',
        
        // ddev:        '/Ws/scripts/wss.domain.port.min.js'
        // production:  '/Ws/scripts/wss.domain.min.js'
        //              see 'apache2 vHost Config for `production` Environment' below
        #'/Ws/scripts/ws.domain.port.min.js',
        '/Ws/scripts/wss.domain.port.min.js',
        #'/Ws/scripts/wss.domain.min.js',
    ));

ddev

if you are using ddev:

add to your .ddev/config.yaml

# WebSocket
web_extra_exposed_ports:
    - name: websocket
      container_port: 8000
      http_port: 7999
      https_port: 8000

---

Content-Security-Policy

make sure the policy connect-src is also set to your WebSocket domain. This depends on your setup; It may be one of these

• connect-src ws://emaxple.com:8000;
• connect-src wss://emaxple.com:8000;
• connect-src wss://emaxple.com;

---

Templating

add WebSocket Server Status somewhere (maybe <footer>) to your HTML

<!--WS-->
<div class="float-end" style="position: fixed; bottom: 20px; right: 10px; margin: 0 10px !important;">
    <small><kbd>WebSocket</kbd></small>
    <span id="wsSocketStatusInfo">
		<a class="badge text-danger" title="WebSocket Server"><i class="fa fa-exclamation-triangle"></i></a>
	</span>
</div>

---

modifying JS Behaviour WsProcess

• instead of using /Ws_old/scripts/pnotify.min.js of the example, you can write your own WsProcess function in any JS script.
• just make sure it is loaded and accessible before /Ws/scripts/wss.*.min.js

---

WebSocket

Server

start

there are several ways to start the websocket server.

Once the server is running, you cannot start it again. If you try to, nothing happens, because the start routine always checks if the server already runs. And if it is already running, the code will exit.

start via cronjob

# WebSocket Server; start in background
# change the cd Path to your Application
* * * * * cd /var/www/html/public; /usr/bin/php index.php '/ws/serve/' > /dev/null 2>/dev/null & echo $!

start via Command in a Controller

Process::callRoute('/ws/serve/');

or

Process::callRoute(
    Route::getOnTag('WsServe')->get_path()
);

start by hand on command line

php index.php '/ws/serve/'

stop

remove the WebSocket pid from the pid folder; usually this is application/pid/

or

set Application to maintainance mode

or

just kill the process by hand

---

Message

push Message to WebSocket Server

\Ws\Model\Ws::init()->push(
    DTWsPackage::create()->set_sData(json_encode(array(
        'receiver' => 'PNnotify',
        'PNotifyType' => 'notice',
        'user' => 'robot',
        'message' => __METHOD__ . "\n**PUSH TEST** at " . date('Y-m-d H:i:s') . "\npid: " . getmypid() . "\n",
        'datetime' => date("Y-m-d H:i:s", time())
    ))), 
    bParsedown: false
);

• possible PNotifyType: info, success, notice, error
• if you want to get message markdown already get parsed on serverside before processing in JS, set bParsedown: true

Customizing

WS config file

modules/Ws/etc/config/config.php

overwrite those config settings in your primary module.

---

apache2 vHost Config for production Environment

Requirements

a2enmod proxy
a2enmod proxy_http
a2enmod proxy_wstunnel

systemctl restart apache2

In the application that is to access the WebSocket, a ProxyPass to the local WebSocket must be declared.

ProxyPass to WebSocket

    ...
    # WebSocket
    RewriteEngine On
    # if WebSocket Request ...
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    # ...then pass through to local WebSocket server
    RewriteRule /(.*) ws://127.0.0.1:8000/$1 [P,L]
    ...

complete real-life example

<IfModule mod_ssl.c>
<VirtualHost example.com:443>
    ServerAdmin webmaster@mediafinanz.de
    DocumentRoot /var/www/example.com/public
    ServerName example.com

    <Directory /var/www/example.com/public>
        Options FollowSymlinks
        AllowOverride All
    </Directory>

    CustomLog       /var/log/apache2/example.com.log combined
    ErrorLog        /var/log/apache2/example.com.error.log

    SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf

    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    RewriteRule /(.*) ws://127.0.0.1:8000/$1 [P,L]

</VirtualHost>
</IfModule>