Merge pull request #468 from beyondcode/feature/docs

[2.x] Docs

Author: rennokki

docs/advanced-usage/app-providers.md

@@ -1,69 +1,74 @@
-# Custom App Providers
+---
+title: Custom App Managers
+order: 1
+---
+
+# Custom App Managers
 
 With the multi-tenancy support of Laravel WebSockets, the default way of storing and retrieving the apps is by using the `websockets.php` config file.
 
-Depending on your setup, you might have your app configuration stored elsewhere and having to keep the configuration in sync with your app storage can be tedious. To simplify this, you can create your own `AppProvider` class that will take care of retrieving the WebSocket credentials for a specific WebSocket application.
+Depending on your setup, you might have your app configuration stored elsewhere and having to keep the configuration in sync with your app storage can be tedious. To simplify this, you can create your own `AppManager` class that will take care of retrieving the WebSocket credentials for a specific WebSocket application.
 
-> Make sure that you do **not** perform any IO blocking tasks in your `AppProvider`, as they will interfere with the asynchronous WebSocket execution.
+> Make sure that you do **not** perform any IO blocking tasks in your `AppManager`, as they will interfere with the asynchronous WebSocket execution.
 
-In order to create your custom `AppProvider`, create a class that implements the `BeyondCode\LaravelWebSockets\AppProviders\AppProvider` interface.
+In order to create your custom `AppManager`, create a class that implements the `BeyondCode\LaravelWebSockets\Apps\AppManager` interface.
 
 This is what it looks like:
 
 ```php
-interface AppProvider
+interface AppManager
 {
-    /**  @return array[BeyondCode\LaravelWebSockets\AppProviders\App] */
+    /**  @return array[BeyondCode\LaravelWebSockets\Apps\App] */
     public function all(): array;
 
-    /**  @return BeyondCode\LaravelWebSockets\AppProviders\App */
+    /**  @return BeyondCode\LaravelWebSockets\Apps\App */
     public function findById($appId): ?App;
 
-    /**  @return BeyondCode\LaravelWebSockets\AppProviders\App */
+    /**  @return BeyondCode\LaravelWebSockets\Apps\App */
     public function findByKey(string $appKey): ?App;
 
-    /**  @return BeyondCode\LaravelWebSockets\AppProviders\App */
+    /**  @return BeyondCode\LaravelWebSockets\Apps\App */
     public function findBySecret(string $appSecret): ?App;
 }
 ```
 
-The following is an example AppProvider that utilizes an Eloquent model:
+The following is an example AppManager that utilizes an Eloquent model:
 ```php
-namespace App\Providers;
+namespace App\Appmanagers;
 
 use App\Application;
 use BeyondCode\LaravelWebSockets\Apps\App;
-use BeyondCode\LaravelWebSockets\Apps\AppProvider;
+use BeyondCode\LaravelWebSockets\Apps\AppManager;
 
-class MyCustomAppProvider implements AppProvider
+class MyCustomAppManager implements AppManager
 {
     public function all() : array
     {
         return Application::all()
             ->map(function($app) {
-                return $this->instanciate($app->toArray());
+                return $this->normalize($app->toArray());
             })
             ->toArray();
     }
 
     public function findById($appId) : ? App
     {
-        return $this->instanciate(Application::findById($appId)->toArray());
+        return $this->normalize(Application::findById($appId)->toArray());
     }
 
     public function findByKey(string $appKey) : ? App
     {
-        return $this->instanciate(Application::findByKey($appKey)->toArray());
+        return $this->normalize(Application::findByKey($appKey)->toArray());
     }
 
     public function findBySecret(string $appSecret) : ? App
     {
-        return $this->instanciate(Application::findBySecret($appSecret)->toArray());
+        return $this->normalize(Application::findBySecret($appSecret)->toArray());
     }
 
-    protected function instanciate(?array $appAttributes) : ? App
+    protected function normalize(?array $appAttributes) : ? App
     {
-        if (!$appAttributes) {
+        if (! $appAttributes) {
             return null;
         }
 
@@ -90,15 +95,28 @@ class MyCustomAppProvider implements AppProvider
 }
 ```
 
-Once you have implemented your own AppProvider, you need to set it in the `websockets.php` configuration file:
-
-```php	
-/**
- * This class is responsible for finding the apps. The default provider
- * will use the apps defined in this config file.
- *
- * You can create a custom provider by implementing the
- * `AppProvider` interface.
- */
-'app_provider' => MyCustomAppProvider::class,
+Once you have implemented your own AppManager, you need to set it in the `websockets.php` configuration file:
+
+```php
+'managers' => [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Application Manager
+    |--------------------------------------------------------------------------
+    |
+    | An Application manager determines how your websocket server allows
+    | the use of the TCP protocol based on, for example, a list of allowed
+    | applications.
+    | By default, it uses the defined array in the config file, but you can
+    | anytime implement the same interface as the class and add your own
+    | custom method to retrieve the apps.
+    |
+    */
+
+    'app' => \App\Managers\MyCustomAppManager::class,
+
+    ...
+
+],
 ```

docs/advanced-usage/custom-websocket-handlers.md

@@ -1,6 +1,11 @@
+---
+title: Custom WebSocket Handlers
+order: 2
+---
+
 # Custom WebSocket Handlers
 
-While this package's main purpose is to make the usage of either the Pusher JavaScript client or Laravel Echo as easy as possible, you are not limited to the Pusher protocol at all. 
+While this package's main purpose is to make the usage of either the Pusher JavaScript client or Laravel Echo as easy as possible, you are not limited to the Pusher protocol at all.
 There might be situations where all you need is a simple, bare-bone, WebSocket server where you want to have full control over the incoming payload and what you want to do with it - without having "channels" in the way.
 
 You can easily create your own custom WebSocketHandler class. All you need to do is implement Ratchets `Ratchet\WebSocket\MessageComponentInterface`.
@@ -21,7 +26,7 @@ class MyCustomWebSocketHandler implements MessageComponentInterface
     {
         // TODO: Implement onOpen() method.
     }
-    
+
     public function onClose(ConnectionInterface $connection)
     {
         // TODO: Implement onClose() method.
@@ -51,4 +56,4 @@ This could, for example, be done inside your `routes/web.php` file.
 WebSocketsRouter::webSocket('/my-websocket', \App\MyCustomWebSocketHandler::class);
 ```
 
-Once you've added the custom WebSocket route, be sure to restart our WebSocket server for the changes to take place.
+Once you've added the custom WebSocket route, be sure to restart our WebSocket server for the changes to take place.

docs/advanced-usage/webhooks.md

@@ -0,0 +1,53 @@
+---
+title: Webhooks
+order: 3
+---
+
+# Webhooks
+
+While you can create any custom websocket handlers, you might still want to intercept and run your own custom business logic on each websocket connection.
+
+In Pusher, there are [Pusher Webhooks](https://pusher.com/docs/channels/server_api/webhooks) that do this job. However, since the implementation is a pure controller,
+you might want to extend it and update the config file to reflect the changes:
+
+For example, running your own business logic on connection open and close:
+
+```php
+namespace App\Controllers\WebSockets;
+
+use BeyondCode\LaravelWebSockets\WebSockets\WebSocketHandler as BaseWebSocketHandler;
+use Ratchet\ConnectionInterface;
+
+class WebSocketHandler extends BaseWebSocketHandler
+{
+    public function onOpen(ConnectionInterface $connection)
+    {
+        parent::onOpen($connection);
+
+        // Run code on open
+        // $connection->app contains the app details
+        // $this->channelManager is accessible
+    }
+
+    public function onClose(ConnectionInterface $connection)
+    {
+        parent::onClose($connection);
+
+        // Run code on close.
+        // $connection->app contains the app details
+        // $this->channelManager is accessible
+    }****
+}
+```
+
+Once you implemented it, replace the `handlers.websocket` class name in config:
+
+```php
+'handlers' => [
+
+    'websocket' => App\Controllers\WebSockets\WebSocketHandler::class,
+
+],
+```
+
+A server restart is required afterwards.

docs/basic-usage/pusher.md

@@ -7,14 +7,16 @@ order: 1
 
 The easiest way to get started with Laravel WebSockets is by using it as a [Pusher](https://pusher.com) replacement. The integrated WebSocket and HTTP Server has complete feature parity with the Pusher WebSocket and HTTP API. In addition to that, this package also ships with an easy to use debugging dashboard to see all incoming and outgoing WebSocket requests.
 
+To make it clear, the package does not restrict connections numbers or depend on the Pusher's service. It does comply with the Pusher protocol to make it easy to use the Pusher SDK with it.
+
 ## Requirements
 
-To make use of the Laravel WebSockets package in combination with Pusher, you first need to install the official Pusher PHP SDK. 
+To make use of the Laravel WebSockets package in combination with Pusher, you first need to install the official Pusher PHP SDK.
 
 If you are not yet familiar with the concept of Broadcasting in Laravel, please take a look at the [Laravel documentation](https://laravel.com/docs/6.0/broadcasting).
 
 ```bash
-composer require pusher/pusher-php-server "~3.0"
+composer require pusher/pusher-php-server "~4.0"
 ```
 
 Next, you should make sure to use Pusher as your broadcasting driver. This can be achieved by setting the `BROADCAST_DRIVER` environment variable in your `.env` file:
@@ -40,7 +42,7 @@ To do this, you should add the `host` and `port` configuration key to your `conf
         'encrypted' => true,
         'host' => '127.0.0.1',
         'port' => 6001,
-        'scheme' => 'http'
+        'scheme' => 'http',
     ],
 ],
 ```
@@ -68,6 +70,8 @@ You may add additional apps in your `config/websockets.php` file.
         'name' => env('APP_NAME'),
         'key' => env('PUSHER_APP_KEY'),
         'secret' => env('PUSHER_APP_SECRET'),
+        'path' => env('PUSHER_APP_PATH'),
+        'capacity' => null,
         'enable_client_messages' => false,
         'enable_statistics' => true,
     ],
@@ -113,7 +117,8 @@ window.Echo = new Echo({
     wsPort: 6001,
     forceTLS: false,
     disableStats: true,
+    enabledTransports: ['ws', 'wss'],
 });
 ```
 
-Now you can use all Laravel Echo features in combination with Laravel WebSockets, such as [Presence Channels](https://laravel.com/docs/6.0/broadcasting#presence-channels), [Notifications](https://laravel.com/docs/6.0/broadcasting#notifications) and [Client Events](https://laravel.com/docs/6.0/broadcasting#client-events).
+Now you can use all Laravel Echo features in combination with Laravel WebSockets, such as [Presence Channels](https://laravel.com/docs/7.x/broadcasting#presence-channels), [Notifications](https://laravel.com/docs/7.x/broadcasting#notifications) and [Client Events](https://laravel.com/docs/7.x/broadcasting#client-events).

docs/basic-usage/restarting.md

@@ -0,0 +1,14 @@
+---
+title: Restarting Server
+order: 4
+---
+
+# Restarting Server
+
+If you use Supervisor to keep your server alive, you might want to restart it just like `queue:restart` does.
+
+To do so, consider using the `websockets:restart`. In a maximum of 10 seconds, the server will be restarted automatically.
+
+```bash
+php artisan websockets:restart
+```

docs/basic-usage/ssl.md

@@ -14,24 +14,19 @@ The default configuration has a SSL section that looks like this:
 
 ```php
 'ssl' => [
-    /*
-     * Path to local certificate file on filesystem. It must be a PEM encoded file which
-     * contains your certificate and private key. It can optionally contain the
-     * certificate chain of issuers. The private key also may be contained
-     * in a separate file specified by local_pk.
-     */
-    'local_cert' => null,
-
-    /*
-     * Path to local private key file on filesystem in case of separate files for
-     * certificate (local_cert) and private key.
-     */
-    'local_pk' => null,
-
-    /*
-     * Passphrase with which your local_cert file was encoded.
-     */
-    'passphrase' => null
+
+    'local_cert' => env('LARAVEL_WEBSOCKETS_SSL_LOCAL_CERT', null),
+
+    'capath' => env('LARAVEL_WEBSOCKETS_SSL_CA', null),
+
+    'local_pk' => env('LARAVEL_WEBSOCKETS_SSL_LOCAL_PK', null),
+
+    'passphrase' => env('LARAVEL_WEBSOCKETS_SSL_PASSPHRASE', null),
+
+    'verify_peer' => env('APP_ENV') === 'production',
+
+    'allow_self_signed' => env('APP_ENV') !== 'production',
+
 ],
 ```
 
@@ -62,7 +57,8 @@ window.Echo = new Echo({
     wsHost: window.location.hostname,
     wsPort: 6001,
     disableStats: true,
-    forceTLS: true
+    forceTLS: true,
+    enabledTransports: ['ws', 'wss'],
 });
 ```
 
@@ -78,9 +74,10 @@ When broadcasting events from your Laravel application to the WebSocket server,
     'app_id' => env('PUSHER_APP_ID'),
     'options' => [
         'cluster' => env('PUSHER_APP_CLUSTER'),
+        'encrypted' => true,
         'host' => '127.0.0.1',
         'port' => 6001,
-        'scheme' => 'https'
+        'scheme' => 'https',
     ],
 ],
 ```
@@ -98,26 +95,19 @@ Make sure that you replace `YOUR-USERNAME` with your Mac username and `VALET-SIT
 
 ```php
 'ssl' => [
-    /*
-     * Path to local certificate file on filesystem. It must be a PEM encoded file which
-     * contains your certificate and private key. It can optionally contain the
-     * certificate chain of issuers. The private key also may be contained
-     * in a separate file specified by local_pk.
-     */
+
     'local_cert' => '/Users/YOUR-USERNAME/.config/valet/Certificates/VALET-SITE.TLD.crt',
 
-    /*
-     * Path to local private key file on filesystem in case of separate files for
-     * certificate (local_cert) and private key.
-     */
-    'local_pk' => '/Users/YOUR-USERNAME/.config/valet/Certificates/VALET-SITE.TLD.key',
+    'capath' => env('LARAVEL_WEBSOCKETS_SSL_CA', null),
+
+    'local_pk' => 'local_pk' => '/Users/YOUR-USERNAME/.config/valet/Certificates/VALET-SITE.TLD.key',
+
+    'passphrase' => env('LARAVEL_WEBSOCKETS_SSL_PASSPHRASE', null),
+
+    'verify_peer' => env('APP_ENV') === 'production',
 
-    /*
-     * Passphrase with which your local_cert file was encoded.
-     */
-    'passphrase' => null,
+    'allow_self_signed' => env('APP_ENV') !== 'production',
 
-    'verify_peer' => false,
 ],
 ```
 
@@ -133,6 +123,7 @@ You also need to disable SSL verification.
     'app_id' => env('PUSHER_APP_ID'),
     'options' => [
         'cluster' => env('PUSHER_APP_CLUSTER'),
+        'encrypted' => true,
         'host' => '127.0.0.1',
         'port' => 6001,
         'scheme' => 'https',