Add documentation

Author: mpociot

.gitattributes

@@ -8,4 +8,5 @@
 /phpunit.xml.dist   export-ignore
 /.scrutinizer.yml   export-ignore
 /tests              export-ignore
+/docs               export-ignore
 /.editorconfig      export-ignore

.gitignore

@@ -1,6 +1,5 @@
 build
 composer.lock
-docs
 vendor
 coverage
 .phpunit.result.cache

docs/_index.md

@@ -0,0 +1,4 @@
+---
+packageName: Laravel Websockets
+githubUrl: https://github.com/beyondcode/laravel-websockets
+---

docs/advanced-usage/_index.md

@@ -0,0 +1,4 @@
+---
+title: Advanced Usage
+order: 4
+---

docs/advanced-usage/app-providers.md

@@ -0,0 +1,104 @@
+# Custom App Providers
+
+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.
+
+> Make sure that you do **not** perform any IO blocking tasks in your `AppProvider`, 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.
+
+This is what it looks like:
+
+```php
+interface AppProvider
+{
+    /**  @return array[BeyondCode\LaravelWebSockets\AppProviders\App] */
+    public function all(): array;
+
+    /**  @return BeyondCode\LaravelWebSockets\AppProviders\App */
+    public function findById($appId): ?App;
+
+    /**  @return BeyondCode\LaravelWebSockets\AppProviders\App */
+    public function findByKey(string $appKey): ?App;
+
+    /**  @return BeyondCode\LaravelWebSockets\AppProviders\App */
+    public function findBySecret(string $appSecret): ?App;
+}
+```
+
+The following is an example AppProvider that utilizes an Eloquent model:
+```php
+namespace App\Providers;
+
+use App\Application;
+use BeyondCode\LaravelWebSockets\Apps\App;
+use BeyondCode\LaravelWebSockets\Apps\AppProvider;
+
+class MyCustomAppProvider implements AppProvider
+{
+    public function all() : array
+    {
+        return Application::all()
+            ->map(function($app) {
+                return $this->instanciate($app->toArray());
+            })
+            ->toArray();
+    }
+
+    public function findById($appId) : ? App
+    {
+        return $this->instanciate(Application::findById($appId)->toArray());
+    }
+
+    public function findByKey(string $appKey) : ? App
+    {
+        return $this->instanciate(Application::findByKey($appKey)->toArray());
+    }
+
+    public function findBySecret(string $appSecret) : ? App
+    {
+        return $this->instanciate(Application::findBySecret($appSecret)->toArray());
+    }
+
+    protected function instanciate(?array $appAttributes) : ? App
+    {
+        if (!$appAttributes) {
+            return null;
+        }
+
+        $app = new App(
+            $appAttributes['id'],
+            $appAttributes['key'],
+            $appAttributes['secret']
+        );
+
+        if (isset($appAttributes['name'])) {
+            $app->setName($appAttributes['name']);
+        }
+
+        if (isset($appAttributes['host'])) {
+            $app->setHost($appAttributes['host']);
+        }
+
+        $app
+            ->enableClientMessages($appAttributes['enable_client_messages'])
+            ->enableStatistics($appAttributes['enable_statistics']);
+
+        return $app;
+    }
+}
+```
+
+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,
+```

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

@@ -0,0 +1,54 @@
+# 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. 
+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`.
+
+Once implemented, you will have a class that looks something like this:
+
+```php
+namespace App;
+
+use Ratchet\ConnectionInterface;
+use Ratchet\RFC6455\Messaging\MessageInterface;
+use Ratchet\WebSocket\MessageComponentInterface;
+
+class MyCustomWebSocketHandler implements MessageComponentInterface
+{
+
+    public function onOpen(ConnectionInterface $connection)
+    {
+        // TODO: Implement onOpen() method.
+    }
+    
+    public function onClose(ConnectionInterface $connection)
+    {
+        // TODO: Implement onClose() method.
+    }
+
+    public function onError(ConnectionInterface $connection, \Exception $e)
+    {
+        // TODO: Implement onError() method.
+    }
+
+    public function onMessage(ConnectionInterface $connection, MessageInterface $msg)
+    {
+        // TODO: Implement onMessage() method.
+    }
+}
+```
+
+In the class itself you have full control over all the lifecycle events of your WebSocket connections and can intercept the incoming messages and react to them.
+
+The only part missing is, that you will need to tell our WebSocket server to load this handler at a specific route endpoint. This can be achieved using the `WebSocketsRouter` facade.
+
+This class takes care of registering the routes with the actual webSocket server. You can use the `webSocket` method to define a custom WebSocket endpoint. The method needs two arguments: the path where the WebSocket handled should be available and the fully qualified classname of the WebSocket handler class.
+
+This could, for example, be done inside your `routes/web.php` file.
+
+```php
+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.

docs/basic-usage/_index.md

@@ -0,0 +1,4 @@
+---
+title: Basic Usage
+order: 2
+---

docs/basic-usage/pusher.md

@@ -0,0 +1,118 @@
+---
+title: Pusher Replacement
+order: 1
+---
+
+# Pusher Replacement
+
+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.
+
+## Requirements
+
+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"
+```
+
+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:
+
+```
+BROADCAST_DRIVER=pusher
+```
+
+## Pusher Configuration
+
+When broadcasting events from your Laravel application to your WebSocket server, the default behavior is to send the event information to the official Pusher server. But since the Laravel WebSockets package comes with its own Pusher API implementation, we need to tell Laravel to send the events to our own server.
+
+To do this, you should add the `host` and `port` configuration key to your `config/broadcasting.php` and add it to the `pusher` section. The default port of the Laravel WebSocket server is 6001.
+
+```php
+'pusher' => [
+    'driver' => 'pusher',
+    'key' => env('PUSHER_APP_KEY'),
+    'secret' => env('PUSHER_APP_SECRET'),
+    'app_id' => env('PUSHER_APP_ID'),
+    'options' => [
+        'cluster' => env('PUSHER_APP_CLUSTER'),
+        'encrypted' => true,
+        'host' => '127.0.0.1',
+        'port' => 6001,
+        'scheme' => 'http'
+    ],
+],
+```
+
+## Configuring WebSocket Apps
+
+The Laravel WebSocket Pusher replacement server comes with multi-tenancy support out of the box. This means that you could host it independently from your current Laravel application and serve multiple WebSocket applications with one server.
+
+To make the move from an existing Pusher setup to this package as easy as possible, the default app simply uses your existing Pusher configuration.
+
+::: warning
+Make sure to use the same app id, key and secret as in your broadcasting configuration section. Otherwise broadcasting events from Laravel will not work.
+:::
+
+::: tip
+When using Laravel WebSockets as a Pusher replacement without having used Pusher before, it does not matter what you set as your `PUSHER_` variables. Just make sure they are unique for each project.
+:::
+
+You may add additional apps in your `config/websockets.php` file.
+
+```php
+'apps' => [
+    [
+        'id' => env('PUSHER_APP_ID'),
+        'name' => env('APP_NAME'),
+        'key' => env('PUSHER_APP_KEY'),
+        'secret' => env('PUSHER_APP_SECRET'),
+        'enable_client_messages' => false,
+        'enable_statistics' => true,
+    ],
+],
+```
+
+### Client Messages
+
+For each app in your configuration file, you can define if this specific app should support a client-to-client messages. Usually all WebSocket messages go through your Laravel application before they will be broadcasted to other users. But sometimes you may want to enable a direct client-to-client communication instead of sending the events over the server. For example, a "typing" event in a chat application.
+
+It is important that you apply additional care when using client messages, since these originate from other users, and could be subject to tampering by a malicious user of your site.
+
+To enable or disable client messages, you can modify the `enable_client_messages` setting. The default value is `false`.
+
+### Statistics
+
+The Laravel WebSockets package comes with an out-of-the-box statistic solution that will give you key insights into the current status of your WebSocket server.
+
+To enable or disable the statistics for one of your apps, you can modify the `enable_statistics` setting. The default value is `true`.
+
+## Usage with Laravel Echo
+
+The Laravel WebSockets package integrates nicely into [Laravel Echo](https://laravel.com/docs/6.0/broadcasting#receiving-broadcasts) to integrate into your frontend application and receive broadcasted events.
+If you are new to Laravel Echo, be sure to take a look at the [official documentation](https://laravel.com/docs/6.0/broadcasting#receiving-broadcasts).
+
+To make Laravel Echo work with Laravel WebSockets, you need to make some minor configuration changes when working with Laravel Echo. Add the `wsHost` and `wsPort` parameters and point them to your Laravel WebSocket server host and port.
+
+By default, the Pusher JavaScript client tries to send statistic information - you should disable this using the `disableStats` option.
+
+::: tip
+When using Laravel WebSockets in combination with a custom SSL certificate, be sure to use the `encrypted` option and set it to `true`.
+:::
+
+```js
+import Echo from "laravel-echo"
+
+window.Pusher = require('pusher-js');
+
+window.Echo = new Echo({
+    broadcaster: 'pusher',
+    key: 'your-pusher-key',
+    wsHost: window.location.hostname,
+    wsPort: 6001,
+    disableStats: true,
+});
+```
+
+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).