README

collaborate

Live collaboration for Symfony and Drupal admin pages.
Shared form drafts · presence and cursors · saved-view refresh · notifications · over Mercure or WebSockets, no Node service

Documentation · Getting started · Configuration · Rich text · EasyAdmin · Drupal · drupal.org

janalis/collaborate is a Symfony bundle that lets several people work on the same admin page at once:

Shared drafts. Editors of the same record share one durable draft. Text, rich text (CKEditor 5's own operations and transformations, undo included), choices and collections stay in sync. Save goes through the form's usual validation and persistence; a conflicting save elsewhere opens a review, and Discard resets the draft for everyone.
Presence and cursors. The header shows who else is on the page; their pointers, carets, selections and the field each one is in are drawn in their color.
Saved-view refresh. Lists and detail pages reload when a save elsewhere changes what they show.
Notifications. A bell on every page, topics each user subscribes to, Messenger delivery, and web push when no page of the application is open.

It runs on PHP and a hub: a Mercure hub (FrankenPHP's built-in hub works), or the WebSocket server the bundle ships (bin/console collaborate:hub:serve, on ReactPHP). Draft content lives in your database (MariaDB, MySQL, PostgreSQL or SQLite); the hub only carries invalidations and presence, never form content. The bundle is a framework-level core plus admin bridges: EasyAdmin's, loaded when its bundle is registered, and a Drupal module (janalis/collaborate_drupal) for Drupal's administration. Without either, a small form-context service is all a page needs.

Install

composer require janalis/collaborate

Requirements: PHP 8.4+, Symfony 7.4 or 8, Doctrine ORM 3 on MariaDB, MySQL 8, PostgreSQL 13+ or SQLite 3.35+, Symfony AssetMapper, and a hub: symfony/mercure-bundle and a Mercure hub, or the bundled WebSocket server (react/http, react/socket, react/stream, ratchet/rfc6455). See Installation for the routes, the tables, the purge cron and the hub.

Quick start

// config/routes/collaborate.php
return static function (RoutingConfigurator $routes): void {
    $routes->import('@CollaborateBundle/config/routes.php')->prefix('/admin');
};

# config/packages/collaborate.yaml
collaborate:
    drafts:
        enabled: true
        rich_text:
            block_prefixes: [rich_text]   # form types rendered as CKEditor fields

{# in the admin layout #}
{{ collaborate_presence() }}   {# where the avatars go, e.g. the header #}
{{ collaborate_layer() }}      {# once, before </body> #}

// the page's script, before anything that wraps window.fetch
import '@janalis/collaborate/easyadmin.js';

With EasyAdmin, edit and new pages then share drafts. Rich-text editors get the Collaborate CKEditor plugin and the draft's configuration from sessionFor(field); see Getting started and Rich text and scripts.

Configuration

Every option lives under the collaborate key, with defaults that work on a standard admin: who a user is and what they may edit, the hub and its topics, cursor timing, draft limits, compaction, purge and locks, and the saved-view refresh. See Configuration for the full reference and Identity and access for the two services most applications provide.

Contributing

Contributions are welcome: bug reports with the smallest page or form that shows the problem, fixes and tests. Read CONTRIBUTING.md and the contributor guide.

make install        # Composer, npm and the test applications' assets
make verify         # composer validate, mago fmt/lint/analyze, PHPUnit, Vitest

License

MIT.

janalis / collaborate

Package info

Security

Statistics