README.md

Hocuspocus for Laravel

Seamlessly integrates a Hocuspocus backend with Laravel.

Installation

You can install the package via composer:

composer require ueberdosis/hocuspocus-laravel

You can publish and run the migrations with:

php artisan vendor:publish --provider="Hocuspocus\HocuspocusServiceProvider" --tag="hocuspocus-laravel-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --provider="Hocuspocus\HocuspocusServiceProvider" --tag="hocuspocus-laravel-config"

Usage

Add the CanCollaborate trait to your user model:

use Illuminate\Foundation\Auth\User as Authenticatable;
use Hocuspocus\Traits\CanCollaborate;

class User extends Authenticatable {
    use CanCollaborate;
}

Add the Collaborative interface and IsCollaborative trait to your documents and configure the collaborativeAttributes:

use Illuminate\Database\Eloquent\Model;
use Hocuspocus\Contracts\Collaborative;
use Hocuspocus\Traits\IsCollaborative;

class TextDocument extends Model implements Collaborative {
    use IsCollaborative;

    protected array $collaborativeAttributes = [
        'title', 'body',
    ];
}

Add policies to your app that handle authorization for your models. The name of the policy method is configurable inside the hocuspocus-laravel.php config file. An example:

use App\Models\TextDocument;
use App\Models\User;
use Illuminate\Auth\Access\HandlesAuthorization;

class TextDocumentPolicy
{
    use HandlesAuthorization;

    public function update(User $user, TextDocument $document)
    {
        return true;
    }
}

In the frontend, add the collaborationAccessToken and collaborationDocumentName to your WebSocket provider:

<script>
  window.collaborationAccessToken = '{{ optional(auth()->user())->getCollaborationAccessToken() }}';
  window.collaborationDocumentName = '{{ $yourTextDocument->getCollaborationDocumentName() }}'
</script>

import { HocuspocusProvider } from '@hocuspocus/provider'
import * as Y from 'yjs'

const provider = new HocuspocusProvider({
  document: new Y.Doc(),
  url: 'ws://localhost:1234',
  name: window.collaborationDocumentName,
  parameters: {
    access_token: window.collaborationAccessToken,
  },
})

Configure a random secret key in your .env:

HOCUSPOCUS_SECRET="459824aaffa928e05f5b1caec411ae5f"

Finally set up Hocuspocus with the webhook extension:

import { Server } from '@hocuspocus/server'
import { Webhook, Events } from '@hocuspocus/extension-webhook'
import { TiptapTransformer } from '@hocuspocus/transformer'

const server = Server.configure({
  extensions: [
    new Webhook({
      // url to your application
      url: 'https://example.com/api/documents',
      // the same secret you configured earlier in your .env
      secret: '459824aaffa928e05f5b1caec411ae5f',

      transformer: TiptapTransformer,
    }),
  ],
})

server.listen()

Credits

• Kris Siepert
• All Contributors

License

The MIT License (MIT). Please see License File for more information.