diff --git a/.gitignore b/.gitignore index 3c61077..cda9316 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ node_modules vendor dist composer.lock +.env diff --git a/README.md b/README.md index a602fbb..61973d8 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Collaboration -> Realtime collaboration and multi-user authoring for Statamic Pro. +> Real-time collaboration and multi-user authoring for Statamic Pro. ## Features @@ -12,40 +12,81 @@ ## Installation -Require it using Composer, as well as the Pusher library. +You can install and configure the Collaboration addon using a single command: ``` -composer require statamic/collaboration -composer require pusher/pusher-php-server "^5.0" +php please install:collaboration ``` -Uncomment `BroadcastServiceProvider` from `config/app.php`'s `providers` array if it isn't already. +The command will install the `statamic/collaboration` addon, setup Laravel's broadcast scaffolding and prompt you to select which broadcast driver you wish to use. -``` php -'providers' => [ - // ... - App\Providers\BroadcastServiceProvider::class, - // ... -] -``` +For more information on the specifics for each broadcast driver, please review the following: + +### Laravel Reverb + +The `install:collaboration` command will install Laravel Reverb into your application. After installation, run `php artisan reverb:start` to run Reverb's WebSockets server, then the Collaboration addon should start working in the Control Panel. + +When you deploy your application to a server, you will need to run the Reverb WebSockets server as a daemon (`php artisan reverb:start`). If you're using Laravel Forge, there's a Reverb toggle in your site's "Application" panel. + +For further information on Reverb, please review the [Laravel documentation](https://laravel.com/docs/master/reverb#introduction). -In your `.env` file, make sure the `pusher` broadcast driver is used: +### Pusher + +The `install:collaboration` command will install [Pusher](https://pusher.com/)'s PHP SDK into your application. After installation, you should add your Pusher credentials to your `.env` file: ``` -BROADCAST_DRIVER=pusher +PUSHER_APP_ID="your-pusher-app-id" +PUSHER_APP_KEY="your-pusher-key" +PUSHER_APP_SECRET="your-pusher-secret" +PUSHER_HOST= +PUSHER_PORT=443 +PUSHER_SCHEME="https" +PUSHER_APP_CLUSTER="mt1" ``` -Create an app inside your [Pusher account](https://pusher.com). +You should also ensure you have enabled the "Client Events" setting (found under the "App Settings" page in the Pusher Dashboard). + +### Other + +If you're planning on using a different broadcasting driver, there are a few additional steps you'll need to take to get it working: + +1. Install & configure your broadcasting driver (obviously) +2. Update the `BROADCAST_DRIVER` in your `.env` +3. Create a `resources/js/cp.js` file and add it to the Control Panel. + * [For more information, follow this guide on our documentation site](https://statamic.dev/extending/control-panel#adding-css-and-js-assets). +4. In your `resources/js/cp.js` file, register a callback to override Statamic's [Echo](https://laravel.com/docs/10.x/broadcasting#client-side-installation) config: + +```js +Statamic.booting(() => { + Statamic.$echo.config(() => ({ + broadcaster: "pusher", + key: Statamic.$config.get('broadcasting.pusher.key'), + cluster: Statamic.$config.get('broadcasting.pusher.cluster'), + wsHost: Statamic.$config.get('broadcasting.pusher.host'), + wsPort: Statamic.$config.get('broadcasting.pusher.port'), + wssPort: Statamic.$config.get('broadcasting.pusher.port'), + forceTLS: false, + encrypted: true, + disableStats: true, + enabledTransports: ["ws", "wss"], + })); +}); +``` -Be sure to enable the "Client Events" setting (under the "App Settings" page in your Pusher App Dashboard). +## Configuration -Add your Pusher app credentials to your `.env` file: +### Sound Effects -``` -PUSHER_APP_ID= -PUSHER_APP_KEY= -PUSHER_APP_SECRET= -PUSHER_APP_CLUSTER= +By default, the Collaboration addon plays sound effects when other users join & leave entries. + +If you wish to disable these, you may publish the configuration file (via `php artisan vendor:publish --tag=collaboration`) and set `sound_effects` to `false`. + +```php +// config/collaboration.php + +return [ + 'sound_effects' => false, +]; ``` ## Configuration diff --git a/composer.json b/composer.json index ad960ff..3ef25c2 100644 --- a/composer.json +++ b/composer.json @@ -1,10 +1,10 @@ { "name": "statamic/collaboration", "type": "statamic-addon", - "description": "Collaboration tools for Statamic 3", + "description": "Real-time collaboration and multi-user authoring for Statamic Pro.", "license": "proprietary", "require": { - "statamic/cms": "^4.0", + "statamic/cms": "^5.0", "pixelfear/composer-dist-plugin": "^0.1.4" }, "extra": { @@ -15,7 +15,7 @@ }, "statamic": { "name": "Collaboration", - "description": "Collaboration tools" + "description": "Real-time collaboration and multi-user authoring for Statamic Pro." }, "download-dist": { "url": "https://github.com/statamic/collaboration/releases/download/{$version}/dist.tar.gz",