Update to stable version of PHPCS Fixer. Made manager more extensible. Added provider to make setup easier. Added more docs.

Author: Daniel LaBarge

.editorconfig

@@ -15,11 +15,11 @@ indent_size = 4
 indent_style = tab
 
 # 4-spaced files
-[**.{js,json,php,xml,md}]
+[**.{js,json,php,xml,md,yml,yaml}]
 indent_size = 4
 
 # 2-spaced files
-[**.{css,less,sass,scss,html,htm,xhtml,yml,blade.php}]
+[**.{css,less,sass,scss,html,htm,xhtml,blade.php}]
 indent_size = 2
 
 [{node_modules,vendor,bower_components}/**]

.php_cs

@@ -14,15 +14,18 @@ return Config::create()
         'not_operator_with_space' => true,
         'ordered_imports' => true,
         'phpdoc_order' => true,
-        'phpdoc_type_to_var' => true,
         'psr0' => false,
-        'short_array_syntax' => true,
-        'unalign_double_arrow' => false,
-        'unalign_equals' => false,
+        'array_syntax' => [
+            'syntax' => 'short',
+        ],
+        'binary_operator_spaces' => [
+            'align_double_arrow' => true,
+            'align_equals' => true,
+        ],
     ])
-    ->finder(
+    ->setFinder(
         Finder::create()
-            ->in(__DIR__.'/src')
             ->in(__DIR__.'/config')
+            ->in(__DIR__.'/src')
             ->in(__DIR__.'/tests')
     );

composer.json

@@ -15,7 +15,7 @@
         "wyrihaximus/react-guzzle-psr7": "~2.0"
     },
     "require-dev": {
-        "friendsofphp/php-cs-fixer": "2.0.0-alpha",
+        "friendsofphp/php-cs-fixer": "~2.2",
         "fzaninotto/faker": "~1.4",
         "mockery/mockery": "0.9.*",
         "phpunit/phpunit": "~5.7"

config/server.php

@@ -1,6 +1,20 @@
 <?php
 
 return [
+    /*
+    |--------------------------------------------------------------------------
+    | Manager Class
+    |--------------------------------------------------------------------------
+    |
+    | The server runs as a singleton instance with with the server being the
+    | main event loop manager, the broker being the connection handler, and
+    | the manager being the kernel of the application. Sometimes you have
+    | to extend the manager and this config lets you customize that.
+    |
+    */
+
+    'manager' => ArtisanSDK\Server\Manager::class,
+
     /*
     |--------------------------------------------------------------------------
     | Server Address Bindings
@@ -65,5 +79,4 @@
     'namespaces' => [
         'ArtianSDK\\Server\\Messages\\',
     ],
-
 ];

readme.md

@@ -2,6 +2,18 @@
 
 A service-based, Laravel PHP implementation of an async, realtime, WebSocket server.
 
+## Table of Contents
+
+- [Installation](#installation)
+    - [Configure the Environment](#configure-the-environment)
+    - [Nginx Websocket Proxy Configuration](#nginx-websocket-proxy-configuration)
+    - [Running the Server (Supervisord)](#running-the-server)
+- [Usage Guide](#usage-guide)
+    - [Extending the Server Manager](#extending-the-server-manager)
+    - [Pushing Messages to the Realtime Queue](#pushing-messages-to-the-realtime-queue)
+    - [Authenticating Client Messages](#authenticating-client-messages)
+- [Licensing](#licensing)
+
 ## Installation
 
 The package installs into a Laravel application like any other Laravel package:
@@ -10,6 +22,14 @@ The package installs into a Laravel application like any other Laravel package:
 composer require artisansdk/server ~1.0
 ```
 
+Then in your Laravel application's `config/app.php` add the `ArtisanSDK\Server\Provider::class`
+to the `providers` key. This will register the configs and Artisan commands provided
+by the package. You can publish these configs to `config/server.php` by running:
+
+```
+php artisan vendor:publish --provider="ArtisanSDK\\Server\\Provider" --tag=config`
+```
+
 > **Show Me:** You can see how to integrate this package by browsing the source
 code of [`larandomizer/app`](http://github.com/larandomizer/app) which powers
 [Larandomizer.com](http://larandomizer.com).
@@ -28,16 +48,6 @@ for server customization:
 - `SERVER_QUEUE_DRIVER` (`beanstalkd`): the driver to use for the realtime message queue
 - `SERVER_KEY` (`password`): the admin password to authenticate connections against admin protected connections
 
-There is a basic auth scheme in place which allows the server to `PromptForAuthentication`
-against a connection and then remember that the connection is authenticated. This
-simplifies further message processing and relies on any `ClientMessage` that must
-be authenticated to implement the `authorize()` method. There are three basic
-traits that can be used on any message to achieve a couple of common strategies:
-
-- `ArtisanSDK\Server\Traits\NoProtection`: always returns true so allows any client to send the message
-- `ArtisanSDK\Server\Traits\ClientProtection`: allows admin connections and a specific related connection to be authorized
-- `ArtisanSDK\Server\Traits\AdminProtection`: allows only admins to be authorized to send the message
-
 ### Nginx Websocket Proxy Configuration
 
 Nginx makes the perfect lightweight frontend server for the Laravel backend
@@ -49,7 +59,7 @@ settings you can host websockets securely with the `wss://` protocol allowing
 Nginx to handle the SSL connection and your websocket server handling basic HTTP.
 
 ```
-location /socket/ {
+location /server/ {
     proxy_pass http://127.0.0.1:8080;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header Host $host;
@@ -63,16 +73,14 @@ location /socket/ {
 
 A quick note on the settings used:
 
-- `location /socket/` directs all traffic going to `/socket/` to the proxy
+- `location /server/` directs all traffic going to `/server/` to the proxy
 - `proxy_pass` passes the traffic to the localhost webserver on port `8080`
 - `proxy_read_timeout` customizes the connection drop to hang up idle connections
 - `proxy_http_version` is the version of the websocket protocol in HTTP
 - `X-Real-IP` header gives your websocket server the real IP of the client connection
 - `Upgrade` and `Connection` headers instruct the browser to upgrade to websocket connection
 
-## Usage Guide
-
-### Starting the Server
+### Running the Server
 
 The websocket server can be ran as an console command using `php artisan server:start`
 and if you pass `--help` to the command you can see additional options. You can
@@ -104,9 +112,56 @@ Forge does not add the `startsecs` by default but in practice this may be needed
 to give the server ample time to start without hard exiting and forcing Supervisor
 to give up on starting the process.
 
+
+## Usage Guide
+
+### Extending the Server Manager
+
+The WebSocket server is a singleton instance that wraps brokers all connections
+and messages between connected clients and the server via `Broker`. While this class
+rarely needs modification, the broker collaborates with the `Manager` class. You
+can think of the manager as the kernel of the application as it maintains the
+initial boot state and event loop the entire time the server is running. It has
+sensible defaults but will likely need extending for anything domain specific.
+
+Simple create a new manager class in your local namespace such and include a `boot()`
+method which will be called to initialize your application's custom listeners:
+
+```php
+<?php
+
+namespace App;
+
+use ArtisanSDK\Server\Manager as BaseManager;
+
+class Manager extends BaseManager
+{
+    public function boot()
+    {
+        parent::boot();
+
+        $this->listener(...);
+    }
+}
+```
+
+As you can see in this example it's a good idea to call the parent `boot()` method
+if you want to maintain the existing behavior and simply add on new behavior. With
+the class extended, you now just need to update the configuration setting in
+`app/server.php` under the key `server.manager` to `App\Manager::class` so the
+server knows which manager to use:
+
+```php
+<?php
+
+return [
+    'manager' => App\Manager::class,
+];
+```
+
 ### Pushing Messages to the Realtime Queue
 
-By default the `ArtisanSDK\Server\Manager@start()` method adds a queue worker to the
+By default the `ArtisanSDK\Server\Manager@boot()` method adds a queue worker to the
 async event loop so that "offline" messages can be sent to the "realtime" connected
 websocket clients. You can use any async driver (basically don't use `sync` as
 the queue driver) but if you are using Laravel Forge it is pretty easy to use
@@ -118,9 +173,22 @@ to your "realtime" code you can `use ArtisanSDK\Server\Traits\WebsocketQueue` tr
 your caller class and then call `$this->queue(new Command)` to push server
 commands into the event loop of the websocket server. Commands should run nearly
 instantly though there can be some lag depending on remaining commands within the
-event loop. You can tweak the timing of the worker in `ArtisanSDK\Server\Manager@start()`
+event loop. You can tweak the timing of the worker in `ArtisanSDK\Server\Manager@boot()`
 method's configuration of the worker.
 
+### Authenticating Client Messages
+
+There is a basic auth scheme in place which allows the server to `PromptForAuthentication`
+against a connection and then remember that the connection is authenticated. This
+simplifies further message processing and relies on any `ClientMessage` that must
+be authenticated to implement the `authorize()` method. There are three basic
+traits that can be used on any message to achieve a couple of common strategies:
+
+- `ArtisanSDK\Server\Traits\NoProtection`: always returns true so allows any client to send the message
+- `ArtisanSDK\Server\Traits\ClientProtection`: allows admin or specific connections to be authorized
+- `ArtisanSDK\Server\Traits\AdminProtection`: allows only admins to be authorized to send the message
+
+
 ## Licensing
 
 Copyright (c) 2017 [Artisans Collaborative](http://artisanscollaborative.com)

src/Broker.php

@@ -284,8 +284,8 @@ protected function maxConnections()
     protected function resolveMessage($message)
     {
         $arguments = (array) json_decode($message, true);
-        $name = array_get($arguments, 'name');
-        $class = $this->resolveMessageClass($name);
+        $name      = array_get($arguments, 'name');
+        $class     = $this->resolveMessageClass($name);
 
         return new $class($arguments);
     }
@@ -295,7 +295,7 @@ protected function resolveMessage($message)
      *
      * @param string $name of class
      *
-     * @throws \InvalidArgumentException if class cannot be found in path.
+     * @throws \InvalidArgumentException if class cannot be found in path
      *
      * @return string
      */

src/Commands/GetJob.php

@@ -12,7 +12,7 @@ class GetJob extends Command
     public function run()
     {
         $dispatcher = $this->dispatcher();
-        $job = $dispatcher->connector()
+        $job        = $dispatcher->connector()
             ->pop($dispatcher->queue());
         if ( ! $job) {
             return;

src/Commands/NotifyConnection.php

@@ -17,7 +17,7 @@ public function __construct(array $arguments = [])
     {
         parent::__construct($arguments);
         $this->receiver = array_get($arguments, 'receiver');
-        $this->sender = array_get($arguments, 'sender');
+        $this->sender   = array_get($arguments, 'sender');
     }
 
     /**
@@ -32,7 +32,7 @@ public function run()
 
         $receiver = $everyone->uuid($this->receiver);
 
-        $notification = new Notification($this->sender);
+        $notification  = new Notification($this->sender);
         $notifications = $receiver->notifications();
         $notifications->put($notification->sender(), $notification);
 

src/Commands/RunQueuedCommands.php

@@ -12,7 +12,7 @@ class RunQueuedCommands extends Command
     public function run()
     {
         $dispatcher = $this->dispatcher();
-        $commands = $dispatcher->commands();
+        $commands   = $dispatcher->commands();
 
         $commands->each(function ($command) use ($dispatcher, $commands) {
             $dispatcher->run($command);

src/Console/ServerStart.php

@@ -2,7 +2,6 @@
 
 namespace ArtisanSDK\Server\Console;
 
-use ArtisanSDK\Server\Manager;
 use ArtisanSDK\Server\Server;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Queue;
@@ -38,7 +37,7 @@ public function __construct()
      */
     protected function makeSignature()
     {
-        $options = [];
+        $options   = [];
         $options[] = '--A|address='.config('server.address').' : The address that the server will bind to for client connections';
         $options[] = '--P|port='.config('server.port').' : The port that the server will listen on for client connections';
         $options[] = '--Q|queue='.config('server.queue').' : The message queue that the server will be responsible for processing';
@@ -58,7 +57,6 @@ public function handle()
     {
         Server::make()
             ->bind($this->option('address'), $this->option('port'))
-            ->uses(new Manager())
             ->uses($this->getOutput())
             ->uses(Queue::connection($this->option('connector')), $this->option('queue'))
             ->password($this->option('key'))