IBX-9737: Collaborative editing - configuration for v5.0

code_samples/back_office/notifications/src/Notification/ListRenderer.php

@@ -13,17 +13,8 @@
 
 class ListRenderer implements NotificationRenderer, TypedNotificationRendererInterface
 {
-    protected Environment $twig;
-
-    protected RouterInterface $router;
-
-    protected RequestStack $requestStack;
-
-    public function __construct(Environment $twig, RouterInterface $router, RequestStack $requestStack)
+    public function __construct(protected Environment $twig, protected RouterInterface $router, protected RequestStack $requestStack)
     {
-        $this->twig = $twig;
-        $this->router = $router;
-        $this->requestStack = $requestStack;
     }
 
     public function render(Notification $notification): string

code_samples/collaboration/src/Command/ManageSessionsCommand.php

@@ -0,0 +1,158 @@
+<?php
+
+/**
+ * @copyright Copyright (C) Ibexa AS. All rights reserved.
+ * @license For full copyright and license information view LICENSE file distributed with this source code.
+ */
+declare(strict_types=1);
+
+namespace App\Command;
+
+use Ibexa\Contracts\Collaboration\Invitation\InvitationCreateStruct;
+use Ibexa\Contracts\Collaboration\Invitation\InvitationQuery;
+use Ibexa\Contracts\Collaboration\Invitation\InvitationStatus;
+use Ibexa\Contracts\Collaboration\Invitation\InvitationUpdateStruct;
+use Ibexa\Contracts\Collaboration\Invitation\Query\Criterion\Session;
+use Ibexa\Contracts\Collaboration\InvitationServiceInterface;
+use Ibexa\Contracts\Collaboration\Participant\ExternalParticipantCreateStruct;
+use Ibexa\Contracts\Collaboration\Participant\InternalParticipantCreateStruct;
+use Ibexa\Contracts\Collaboration\Participant\InternalParticipantUpdateStruct;
+use Ibexa\Contracts\Collaboration\Session\Query\Criterion\Token;
+use Ibexa\Contracts\Collaboration\Session\SessionQuery;
+use Ibexa\Contracts\Collaboration\SessionServiceInterface;
+use Ibexa\Contracts\Core\Repository\ContentService;
+use Ibexa\Contracts\Core\Repository\PermissionResolver;
+use Ibexa\Contracts\Core\Repository\UserService;
+use Ibexa\Contracts\Share\Collaboration\ContentSessionCreateStruct;
+use Ibexa\Contracts\Share\Collaboration\ContentSessionScope;
+use Ibexa\Contracts\Share\Collaboration\ContentSessionUpdateStruct;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+#[AsCommand(name: 'app:manage-sessions')]
+final class ManageSessionsCommand extends Command
+{
+    public function __construct(
+        private readonly InvitationServiceInterface $invitationService,
+        private readonly SessionServiceInterface $sessionService,
+        private readonly ContentService $contentService,
+        private readonly UserService $userService,
+        private readonly PermissionResolver $permissionResolver
+    ) {
+        parent::__construct();
+    }
+
+    public function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $this->permissionResolver->setCurrentUserReference(
+            $this->userService->loadUserByLogin('admin')
+        );
+
+        // Create a sharing session for Content
+        $versionInfo = $this->contentService->loadContent(52)->getVersionInfo();
+        $createStruct = new ContentSessionCreateStruct(
+            $versionInfo,
+            $versionInfo->getInitialLanguage()
+        );
+        $createStruct->setHasPublicLink(false);
+
+        $token = 'my-secret-token-12345';
+        $createStruct->setToken($token);
+
+        $sessionId = $this->sessionService->createSession($createStruct)->getId();
+
+        // Get a session by ID or token
+        $session = $this->sessionService->getSession($sessionId);
+        $session = $this->sessionService->getSessionByToken($token);
+
+        // Find sessions
+        $sessionQuery = new SessionQuery(new Token($token));
+        $session = $this->sessionService->findSessions($sessionQuery)->getFirst();
+
+        // Update a session
+        $updateStruct = new ContentSessionUpdateStruct();
+        $updateStruct->setHasPublicLink(true);
+
+        $this->sessionService->updateSession($session, $updateStruct);
+
+        // Deactivate a session
+        $updateStruct = new ContentSessionUpdateStruct();
+        $updateStruct->setIsActive(false);
+
+        $this->sessionService->updateSession($session, $updateStruct);
+
+        // Manage participants
+        $user = $this->userService->loadUserByLogin('another_user');
+        $internalParticipantCreateStruct = new InternalParticipantCreateStruct(
+            $user,
+            ContentSessionScope::VIEW
+        );
+        $externalParticipantCreateStruct = new ExternalParticipantCreateStruct(
+            'external@example.com',
+            ContentSessionScope::VIEW,
+            'personal-secret-token-12345'
+        );
+
+        $internalParticipant = $this->sessionService->addParticipant($session, $internalParticipantCreateStruct);
+        $externalParticipant = $this->sessionService->addParticipant($session, $externalParticipantCreateStruct);
+
+        // Get and update participants
+        $participant = $this->sessionService
+            ->getSession($session->getId())
+            ->getParticipants()
+            ->getByEmail($user->email);
+
+        $internalParticipantUpdateStruct = new InternalParticipantUpdateStruct(ContentSessionScope::EDIT);
+        $this->sessionService->updateParticipant($session, $participant, $internalParticipantUpdateStruct);
+
+        // Remove participant
+        $this->sessionService->removeParticipant($session, $externalParticipant);
+
+        // Check ownerships. If no user is provided, current user is used.
+        $this->sessionService->isSessionOwner(
+            $session,
+            $this->userService->loadUserByLogin('another_user')
+        );
+
+        // Check participation
+        $this->sessionService->isSessionParticipant(
+            $session,
+            $this->permissionResolver->getCurrentUserReference()
+        );
+
+        // Manage invitations
+        $invitationQuery = new InvitationQuery(new Session($session));
+        $invitations = $this->invitationService->findInvitations($invitationQuery)->getInvitations();
+
+        foreach ($invitations as $invitation) {
+            $output->writeln('Invitation ID: ' . $invitation->getId() . ' Status: ' . $invitation->getStatus());
+        }
+
+        $invitation = $this->invitationService->getInvitationByParticipant($participant);
+
+        // Create invitation - use when auto-inviting participants is not enabled
+        $invitationCreateStruct = new InvitationCreateStruct(
+            $session,
+            $internalParticipant
+        );
+
+        $this->invitationService->createInvitation($invitationCreateStruct);
+
+        // Update invitation
+        $invitationUpdateStruct = new InvitationUpdateStruct();
+        $invitationUpdateStruct->setStatus(InvitationStatus::STATUS_REJECTED);
+
+        $this->invitationService->updateInvitation($invitation, $invitationUpdateStruct);
+
+        // Delete invitation
+        $invitation = $this->invitationService->getInvitation(2);
+        $this->invitationService->deleteInvitation($invitation);
+
+        // Delete a session
+        $this->sessionService->deleteSession($session);
+
+        return Command::SUCCESS;
+    }
+}

composer.json

@@ -75,7 +75,9 @@
         "ibexa/discounts-codes": "~5.0.x-dev",
         "ibexa/core-search": "~5.0.x-dev",
         "ibexa/product-catalog-symbol-attribute": "~5.0.x-dev",
-        "ibexa/messenger": "~5.0.x-dev"
+        "ibexa/messenger": "~5.0.x-dev",
+        "ibexa/collaboration": "~5.0.x-dev",
+        "ibexa/share": "~5.0.x-dev"
     },
     "scripts": {
         "fix-cs": "php-cs-fixer fix --config=.php-cs-fixer.php -v --show-progress=dots",

docs/content_management/collaborative_editing/collaborative_editing.md

@@ -0,0 +1,22 @@
+---
+description: Collaborative editing enables multiple users to work on the same content simultaneously.
+page_type: landing_page
+month_change: true
+---
+
+# Collaborative editing
+
+With Collaborative editing feature multiple users can work on the same content created in [[= product_name =]] simultaneously, streamlining the content creation and review process.
+
+Users can invite both internal and external collaborators to a session, giving them access for editing or previewing.
+
+Additionaly, they can collaborate using a Real-time collaboration, an advanced part of the collaboration feature, to write and review content in a live mode thanks to CKEditor.
+Real-time collaboration syncs changes instantly and shows user avatars and colored tags to indicate who is editing specific part of the Rich Text field.
+
+This feature also introduces new dashboard tabs for managing shared drafts and joining collaboration sessions easily.
+
+[[= cards([
+"content_management/collaborative_editing/collaborative_editing_guide",
+"content_management/collaborative_editing/configure_collaborative_editing",
+"content_management/collaborative_editing/collaborative_editing_api"
+], columns=3) =]]

docs/content_management/collaborative_editing/collaborative_editing_api.md

@@ -0,0 +1,158 @@
+---
+description: Use PHP API to manage invitations, sessions, and participants while using collaborative editing feature.
+month_change: true
+---
+
+# Collaborative editing API
+
+[[= product_name =]]'s Collaborative editing API provides two services for managing sessions and invitations, which differ in function:
+
+- [`InvitationServiceInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html) is used to manage collaboration sessions invitations
+- [`SessionServiceInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html) is used to manage collaboration sessions
+
+## Managing sessions
+
+### Create session
+
+You can create new collaboration session with [`SessionService::createSession()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_createSession):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 53, 65) =]]
+```
+
+### Get session
+
+You can get an existing collaboration session with [`SessionService::getSession()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_getSession):
+
+- using given id - with [`SessionService::getSession()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_getSession)
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 66, 67) =]]
+```
+
+- using given token - with [`SessionService::getSessionByToken()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_getSessionByToken)
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 67, 68) =]]
+```
+
+### Find sessions
+
+You can find an existing session with [`SessionService::findSessions()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_findSessions) by passing a SessionQuery object:
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 70, 73) =]]
+```
+
+### Update session
+
+You can update existing invitation with [`SessionService::updateSession()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_updateSession):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 74, 79) =]]
+```
+
+### Delete session
+
+You can delete session with [`SessionService::deleteSession()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_deleteSession):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 153, 154) =]]
+```
+
+## Managing participants
+
+### Add participant
+
+You can add participant to the collaboration session with [`SessionService::addParticipant()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_addParticipant):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 86, 100) =]]
+```
+
+### Get and update participant
+
+You can update participant added to the collaboration session with [`SessionService::updateParticipant()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_updateParticipant):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 101, 109) =]]
+```
+
+The example below updates participant's permissions to allow for editing of shared content, not only previewing.
+
+### Remove participant
+
+You can remove participant from the collaboration session with [`SessionService::removeParticipant()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_removeParticipant):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 110, 111) =]]
+```
+
+### Check session owner
+
+You can check whether a user belongs to a collaboration session with [`SessionService::isSessionOwner()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceDecorator.html#method_isSessionOwner):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 113, 118) =]]
+```
+
+If no user is provided, current user is used.
+
+### Check session participant
+
+You can check the participant of the collaboration session with [`SessionService::isSessionParticipant()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_isSessionParticipant):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 119, 124) =]]
+```
+
+## Managing invitations
+
+### Manage invitation
+
+You can get an invitation with [`InvitationService::getInvitation()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#method_getInvitation):
+
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 125, 134) =]]
+```
+
+### Create invitation
+
+You can create new invitation for the collaborative session using the [`InvitationService::createInvitation()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#method_createInvitation) method:
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 135, 142) =]]
+```
+
+You can use it when auto-inviting participants is not enabled.
+
+### Update invitation
+
+You can update existing invitation with [`InvitationService::updateInvitation()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#method_updateInvitation):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 143, 148) =]]
+```
+
+### Delete invitation
+
+You can delete an invitation with [`InvitationService::deleteInvitation()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#method_deleteInvitation):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 149, 152) =]]
+```
+
+### Find invitations
+
+You can find an invitation with [`InvitationService::findInvitations()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#method_findInvitations).
+
+To learn more about the available search options, see Search Criteria and Sort Clauses for Collaborative editing.
+
+## Example API usage
+
+Below you can see an example of API usage for Collaborative editing:
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php') =]]
+```