msgraph: subscription for users

src/Bundle/ChillCalendarBundle/Command/MapAndSubscribeUserCalendarCommand.php

@@ -0,0 +1,164 @@
+<?php
+
+/**
+ * Chill is a software for social workers
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Chill\CalendarBundle\Command;
+
+use Chill\CalendarBundle\RemoteCalendar\Connector\MSGraph\EventsOnUserSubscriptionCreator;
+use Chill\CalendarBundle\RemoteCalendar\Connector\MSGraph\MapCalendarToUser;
+use Chill\CalendarBundle\RemoteCalendar\Connector\MSGraph\MSGraphUserRepository;
+use DateInterval;
+use DateTimeImmutable;
+use Doctrine\ORM\EntityManagerInterface;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class MapAndSubscribeUserCalendarCommand extends Command
+{
+    private EntityManagerInterface $em;
+
+    private EventsOnUserSubscriptionCreator $eventsOnUserSubscriptionCreator;
+
+    private LoggerInterface $logger;
+
+    private MapCalendarToUser $mapCalendarToUser;
+
+    private MSGraphUserRepository $userRepository;
+
+    public function __construct(
+        EntityManagerInterface $em,
+        EventsOnUserSubscriptionCreator $eventsOnUserSubscriptionCreator,
+        LoggerInterface $logger,
+        MapCalendarToUser $mapCalendarToUser,
+        MSGraphUserRepository $userRepository
+    ) {
+        parent::__construct('chill:calendar:msgraph-user-map-subscribe');
+
+        $this->em = $em;
+        $this->eventsOnUserSubscriptionCreator = $eventsOnUserSubscriptionCreator;
+        $this->logger = $logger;
+        $this->mapCalendarToUser = $mapCalendarToUser;
+        $this->userRepository = $userRepository;
+    }
+
+    public function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $this->logger->info(__CLASS__ . ' execute command');
+
+        $limit = 50;
+        $offset = 0;
+        /** @var DateInterval $interval the interval before the end of the expiration */
+        $interval = new DateInterval('P1D');
+        $expiration = (new DateTimeImmutable('now'))->add(new DateInterval('PT15M'));
+        $total = $this->userRepository->countByMostOldSubscriptionOrWithoutSubscriptionOrData($interval);
+        $created = 0;
+        $renewed = 0;
+
+        $this->logger->info(__CLASS__ . ' the number of user to get - renew', [
+            'total' => $total,
+            'expiration' => $expiration->format(DateTimeImmutable::ATOM),
+        ]);
+
+        while ($offset < ($total - 1)) {
+            $users = $this->userRepository->findByMostOldSubscriptionOrWithoutSubscriptionOrData(
+                $interval,
+                $limit,
+                $offset
+            );
+
+            foreach ($users as $user) {
+                if (!$this->mapCalendarToUser->hasUserId($user)) {
+                    $this->mapCalendarToUser->writeMetadata($user);
+                }
+
+                if ($this->mapCalendarToUser->hasUserId($user)) {
+                    // we first try to renew an existing subscription, if any.
+                    // if not, or if it fails, we try to create a new one
+                    if ($this->mapCalendarToUser->hasActiveSubscription($user)) {
+                        $this->logger->debug(__CLASS__ . ' renew a subscription for', [
+                            'userId' => $user->getId(),
+                            'username' => $user->getUsernameCanonical(),
+                        ]);
+
+                        ['secret' => $secret, 'id' => $id, 'expiration' => $expirationTs]
+                            = $this->eventsOnUserSubscriptionCreator->renewSubscriptionForUser($user, $expiration);
+                        $this->mapCalendarToUser->writeSubscriptionMetadata($user, $expirationTs, $id, $secret);
+
+                        if (0 !== $expirationTs) {
+                            ++$renewed;
+                        } else {
+                            $this->logger->warning(__CLASS__ . ' could not renew subscription for a user', [
+                                'userId' => $user->getId(),
+                                'username' => $user->getUsernameCanonical(),
+                            ]);
+                        }
+                    }
+
+                    if (!$this->mapCalendarToUser->hasActiveSubscription($user)) {
+                        $this->logger->debug(__CLASS__ . ' create a subscription for', [
+                            'userId' => $user->getId(),
+                            'username' => $user->getUsernameCanonical(),
+                        ]);
+
+                        ['secret' => $secret, 'id' => $id, 'expiration' => $expirationTs]
+                            = $this->eventsOnUserSubscriptionCreator->createSubscriptionForUser($user, $expiration);
+                        $this->mapCalendarToUser->writeSubscriptionMetadata($user, $expirationTs, $id, $secret);
+
+                        if (0 !== $expirationTs) {
+                            ++$created;
+                        } else {
+                            $this->logger->warning(__CLASS__ . ' could not create subscription for a user', [
+                                'userId' => $user->getId(),
+                                'username' => $user->getUsernameCanonical(),
+                            ]);
+                        }
+                    }
+                }
+
+                ++$offset;
+            }
+
+            $this->em->flush();
+            $this->em->clear();
+        }
+
+        $this->logger->warning(__CLASS__ . ' process executed', [
+            'created' => $created,
+            'renewed' => $renewed,
+        ]);
+
+        return 0;
+    }
+
+    protected function configure()
+    {
+        parent::configure();
+
+        $this
+            ->setDescription('MSGraph: collect user metadata and create subscription on events for users')
+            ->addOption(
+                'renew-before-end-interval',
+                'r',
+                InputOption::VALUE_OPTIONAL,
+                'delay before renewing subscription',
+                'P1D'
+            )
+            ->addOption(
+                'subscription-duration',
+                's',
+                InputOption::VALUE_OPTIONAL,
+                'duration for the subscription',
+                'PT4230M'
+            );
+    }
+}

src/Bundle/ChillCalendarBundle/Command/MapUserCalendarCommand.php

@@ -1,58 +0,0 @@
-<?php
-
-/**
- * Chill is a software for social workers
- *
- * For the full copyright and license information, please view
- * the LICENSE file that was distributed with this source code.
- */
-
-declare(strict_types=1);
-
-namespace Chill\CalendarBundle\Command;
-
-use Chill\CalendarBundle\RemoteCalendar\Connector\MSGraph\MapCalendarToUser;
-use Chill\MainBundle\Repository\UserRepository;
-use Doctrine\ORM\EntityManagerInterface;
-use Symfony\Component\Console\Command\Command;
-use Symfony\Component\Console\Input\InputInterface;
-use Symfony\Component\Console\Output\OutputInterface;
-
-class MapUserCalendarCommand extends Command
-{
-    private EntityManagerInterface $em;
-
-    private MapCalendarToUser $mapCalendarToUser;
-
-    private UserRepository $userRepository;
-
-    public function __construct(EntityManagerInterface $em, MapCalendarToUser $mapCalendarToUser, UserRepository $userRepository)
-    {
-        parent::__construct('chill:calendar:map-user');
-
-        $this->em = $em;
-        $this->mapCalendarToUser = $mapCalendarToUser;
-        $this->userRepository = $userRepository;
-    }
-
-    public function execute(InputInterface $input, OutputInterface $output): int
-    {
-        $limit = 2;
-        $offset = 0;
-        $total = $this->userRepository->countByNotHavingAttribute(MapCalendarToUser::METADATA_KEY);
-
-        while ($offset < $total) {
-            $users = $this->userRepository->findByNotHavingAttribute(MapCalendarToUser::METADATA_KEY, $limit, $offset);
-
-            foreach ($users as $user) {
-                $this->mapCalendarToUser->writeMetadata($user);
-                ++$offset;
-            }
-
-            $this->em->flush();
-            $this->em->clear();
-        }
-
-        return 0;
-    }
-}

src/Bundle/ChillCalendarBundle/Controller/RemoteCalendarMSGraphSyncController.php

@@ -0,0 +1,54 @@
+<?php
+
+/**
+ * Chill is a software for social workers
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Chill\CalendarBundle\Controller;
+
+use Chill\CalendarBundle\Messenger\Message\MSGraphChangeNotificationMessage;
+use JsonException;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+use Symfony\Component\Messenger\MessageBusInterface;
+use Symfony\Component\Routing\Annotation\Route;
+use const JSON_THROW_ON_ERROR;
+
+class RemoteCalendarMSGraphSyncController
+{
+    private MessageBusInterface $messageBus;
+
+    public function __construct(MessageBusInterface $messageBus)
+    {
+        $this->messageBus = $messageBus;
+    }
+
+    /**
+     * @Route("/public/incoming-hook/calendar/msgraph/events/{userId}", name="chill_calendar_remote_msgraph_incoming_webhook_events",
+     * methods={"POST"})
+     */
+    public function webhookCalendarReceiver(int $userId, Request $request): Response
+    {
+        if ($request->query->has('validationToken')) {
+            return new Response($request->query->get('validationToken'), Response::HTTP_OK, [
+                'content-type' => 'text/plain',
+            ]);
+        }
+
+        try {
+            $body = json_decode($request->getContent(), true, 512, JSON_THROW_ON_ERROR);
+        } catch (JsonException $e) {
+            throw new BadRequestHttpException('could not decode json', $e);
+        }
+
+        $this->messageBus->dispatch(new MSGraphChangeNotificationMessage($body));
+
+        return new Response('', Response::HTTP_ACCEPTED);
+    }
+}

src/Bundle/ChillCalendarBundle/Messenger/Message/MSGraphChangeNotificationMessage.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * Chill is a software for social workers
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Chill\CalendarBundle\Messenger\Message;
+
+class MSGraphChangeNotificationMessage
+{
+    private array $content = [];
+
+    public function __construct(array $content)
+    {
+        $this->content = $content;
+    }
+
+    public function getContent(): array
+    {
+        return $this->content;
+    }
+}

src/Bundle/ChillCalendarBundle/RemoteCalendar/Connector/MSGraph/EventsOnUserSubscriptionCreator.php

@@ -0,0 +1,133 @@
+<?php
+
+/**
+ * Chill is a software for social workers
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Chill\CalendarBundle\RemoteCalendar\Connector\MSGraph;
+
+use Chill\MainBundle\Entity\User;
+use DateTimeImmutable;
+use LogicException;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
+use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
+
+/**
+ * Create a subscription for a user.
+ */
+class EventsOnUserSubscriptionCreator
+{
+    private LoggerInterface $logger;
+
+    private MachineHttpClient $machineHttpClient;
+
+    private MapCalendarToUser $mapCalendarToUser;
+
+    private UrlGeneratorInterface $urlGenerator;
+
+    public function __construct(
+        LoggerInterface $logger,
+        MachineHttpClient $machineHttpClient,
+        MapCalendarToUser $mapCalendarToUser,
+        UrlGeneratorInterface $urlGenerator
+    ) {
+        $this->logger = $logger;
+        $this->machineHttpClient = $machineHttpClient;
+        $this->mapCalendarToUser = $mapCalendarToUser;
+        $this->urlGenerator = $urlGenerator;
+    }
+
+    /**
+     * @throws ClientExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\DecodingExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\RedirectionExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\ServerExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface
+     *
+     * @return array<secret: string, id: string, expiration: int>
+     */
+    public function createSubscriptionForUser(User $user, DateTimeImmutable $expiration): array
+    {
+        if (null === $userId = $this->mapCalendarToUser->getUserId($user)) {
+            throw new LogicException('no user id');
+        }
+
+        $subscription = [
+            'changeType' => 'deleted,updated',
+            'notificationUrl' => $this->urlGenerator->generate(
+                'chill_calendar_remote_msgraph_incoming_webhook_events',
+                ['userId' => $user->getId()],
+                UrlGeneratorInterface::ABSOLUTE_URL
+            ),
+            'resource' => "/users/{$userId}/calendar/events",
+            'clientState' => $secret = base64_encode(openssl_random_pseudo_bytes(92, $cstrong)),
+            'expirationDateTime' => $expiration->format(DateTimeImmutable::ATOM),
+        ];
+
+        try {
+            $subs = $this->machineHttpClient->request(
+                'POST',
+                '/v1.0/subscriptions',
+                [
+                    'json' => $subscription,
+                ]
+            )->toArray();
+        } catch (ClientExceptionInterface $e) {
+            $this->logger->error('could not create subscription for user events', [
+                'body' => $e->getResponse()->getContent(false),
+            ]);
+
+            return ['secret' => '', 'id' => '', 'expiration' => 0];
+        }
+
+        return ['secret' => $secret, 'id' => $subs['id'], 'expiration' => $expiration->getTimestamp()];
+    }
+
+    /**
+     * @throws ClientExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\DecodingExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\RedirectionExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\ServerExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface
+     *
+     * @return array<secret: string, id: string, expiration: int>
+     */
+    public function renewSubscriptionForUser(User $user, DateTimeImmutable $expiration): array
+    {
+        if (null === $userId = $this->mapCalendarToUser->getUserId($user)) {
+            throw new LogicException('no user id');
+        }
+
+        if (null === $subscriptionId = $this->mapCalendarToUser->getActiveSubscriptionId($user)) {
+            throw new LogicException('no user id');
+        }
+
+        $subscription = [
+            'expirationDateTime' => $expiration->format(DateTimeImmutable::ATOM),
+        ];
+
+        try {
+            $subs = $this->machineHttpClient->request(
+                'PATCH',
+                "/v1.0/subscriptions/{$subscriptionId}",
+                [
+                    'json' => $subscription,
+                ]
+            )->toArray();
+        } catch (ClientExceptionInterface $e) {
+            $this->logger->error('could not patch subscription for user events', [
+                'body' => $e->getResponse()->getContent(false),
+            ]);
+
+            return ['secret' => '', 'id' => '', 'expiration' => 0];
+        }
+
+        return ['secret' => $subs['clientState'], 'id' => $subs['id'], 'expiration' => $expiration->getTimestamp()];
+    }
+}

src/Bundle/ChillCalendarBundle/RemoteCalendar/Connector/MSGraph/MSGraphUserRepository.php

@@ -0,0 +1,77 @@
+<?php
+
+/**
+ * Chill is a software for social workers
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Chill\CalendarBundle\RemoteCalendar\Connector\MSGraph;
+
+use Chill\MainBundle\Entity\User;
+use DateInterval;
+use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\Query\ResultSetMapping;
+use Doctrine\ORM\Query\ResultSetMappingBuilder;
+use function strtr;
+
+/**
+ * Contains classes and methods for fetching users with some calendar metadatas.
+ */
+class MSGraphUserRepository
+{
+    private const MOST_OLD_SUBSCRIPTION_OR_ANY_MS_GRAPH = <<<'SQL'
+        select
+            {select}
+        from users u
+        where
+            NOT attributes ?? 'msgraph'
+            OR NOT attributes->'msgraph' ?? 'subscription_events_expiration'
+            OR (attributes->'msgraph' ?? 'subscription_events_expiration' AND (attributes->'msgraph'->>'subscription_events_expiration')::int < EXTRACT(EPOCH FROM (NOW() + :interval::interval)))
+        LIMIT :limit OFFSET :offset
+        ;
+        SQL;
+
+    private EntityManagerInterface $entityManager;
+
+    public function __construct(EntityManagerInterface $entityManager)
+    {
+        $this->entityManager = $entityManager;
+    }
+
+    public function countByMostOldSubscriptionOrWithoutSubscriptionOrData(DateInterval $interval): int
+    {
+        $rsm = new ResultSetMapping();
+        $rsm->addScalarResult('c', 'c');
+
+        $sql = strtr(self::MOST_OLD_SUBSCRIPTION_OR_ANY_MS_GRAPH, [
+            '{select}' => 'COUNT(u) AS c',
+            'LIMIT :limit OFFSET :offset' => '',
+        ]);
+
+        return $this->entityManager->createNativeQuery($sql, $rsm)->setParameters([
+            'interval' => $interval,
+        ])->getSingleScalarResult();
+    }
+
+    /**
+     * @return array|User[]
+     */
+    public function findByMostOldSubscriptionOrWithoutSubscriptionOrData(DateInterval $interval, int $limit = 50, int $offset = 0): array
+    {
+        $rsm = new ResultSetMappingBuilder($this->entityManager);
+        $rsm->addRootEntityFromClassMetadata(User::class, 'u');
+
+        return $this->entityManager->createNativeQuery(
+            strtr(self::MOST_OLD_SUBSCRIPTION_OR_ANY_MS_GRAPH, ['{select}' => $rsm->generateSelectClause()]),
+            $rsm
+        )->setParameters([
+            'interval' => $interval,
+            'limit' => $limit,
+            'offset' => $offset,
+        ])->getResult();
+    }
+}

src/Bundle/ChillCalendarBundle/RemoteCalendar/Connector/MSGraph/MapCalendarToUser.php

@@ -12,15 +12,24 @@ declare(strict_types=1);
 namespace Chill\CalendarBundle\RemoteCalendar\Connector\MSGraph;
 
 use Chill\MainBundle\Entity\User;
+use DateTimeImmutable;
+use LogicException;
 use Psr\Log\LoggerInterface;
+use function array_key_exists;
 
 /**
  * Write metadata to user, which allow to find his default calendar.
  */
 class MapCalendarToUser
 {
+    public const EXPIRATION_SUBSCRIPTION_EVENT = 'subscription_events_expiration';
+
+    public const ID_SUBSCRIPTION_EVENT = 'subscription_events_id';
+
     public const METADATA_KEY = 'msgraph';
 
+    public const SECRET_SUBSCRIPTION_EVENT = 'subscription_events_secret';
+
     private LoggerInterface $logger;
 
     private MachineHttpClient $machineHttpClient;
@@ -33,6 +42,19 @@ class MapCalendarToUser
         $this->logger = $logger;
     }
 
+    public function getActiveSubscriptionId(User $user): string
+    {
+        if (!array_key_exists(self::METADATA_KEY, $user->getAttributes())) {
+            throw new LogicException('do not contains msgraph metadata');
+        }
+
+        if (!array_key_exists(self::ID_SUBSCRIPTION_EVENT, $user->getAttributes()[self::METADATA_KEY])) {
+            throw new LogicException('do not contains metadata for subscription id');
+        }
+
+        return $user->getAttributes()[self::METADATA_KEY][self::ID_SUBSCRIPTION_EVENT];
+    }
+
     public function getCalendarId(User $user): ?string
     {
         if (null === $msKey = ($user->getAttributes()[self::METADATA_KEY] ?? null)) {
@@ -69,16 +91,39 @@ class MapCalendarToUser
         return $msKey['id'] ?? null;
     }
 
+    public function hasActiveSubscription(User $user): bool
+    {
+        if (!array_key_exists(self::METADATA_KEY, $user->getAttributes())) {
+            return false;
+        }
+
+        if (!array_key_exists(self::EXPIRATION_SUBSCRIPTION_EVENT, $user->getAttributes()[self::METADATA_KEY])) {
+            return false;
+        }
+
+        return $user->getAttributes()[self::METADATA_KEY][self::EXPIRATION_SUBSCRIPTION_EVENT]
+            >= (new DateTimeImmutable('now'))->getTimestamp();
+    }
+
+    public function hasUserId(User $user): bool
+    {
+        if (!array_key_exists(self::METADATA_KEY, $user->getAttributes())) {
+            return false;
+        }
+
+        return array_key_exists('id', $user->getAttributes()[self::METADATA_KEY]);
+    }
+
     public function writeMetadata(User $user): User
     {
         if (null === $userData = $this->getUserByEmail($user->getEmailCanonical())) {
-            $this->logger->warning('[MapCalendarToUser] could find user on msgraph', ['userId' => $user->getId(), 'email' => $user->getEmailCanonical()]);
+            $this->logger->warning('[MapCalendarToUser] could not find user on msgraph', ['userId' => $user->getId(), 'email' => $user->getEmailCanonical()]);
 
             return $this->writeNullData($user);
         }
 
         if (null === $defaultCalendar = $this->getDefaultUserCalendar($userData['id'])) {
-            $this->logger->warning('[MapCalendarToUser] could find default calendar', ['userId' => $user->getId(), 'email' => $user->getEmailCanonical()]);
+            $this->logger->warning('[MapCalendarToUser] could not find default calendar', ['userId' => $user->getId(), 'email' => $user->getEmailCanonical()]);
 
             return $this->writeNullData($user);
         }
@@ -90,6 +135,26 @@ class MapCalendarToUser
         ]]);
     }
 
+    /**
+     * @param int $expiration the expiration time as unix timestamp
+     */
+    public function writeSubscriptionMetadata(
+        User $user,
+        int $expiration,
+        ?string $id = null,
+        ?string $secret = null
+    ): void {
+        $user->setAttributeByDomain(self::METADATA_KEY, self::EXPIRATION_SUBSCRIPTION_EVENT, $expiration);
+
+        if (null !== $id) {
+            $user->setAttributeByDomain(self::METADATA_KEY, self::ID_SUBSCRIPTION_EVENT, $id);
+        }
+
+        if (null !== $secret) {
+            $user->setAttributeByDomain(self::METADATA_KEY, self::SECRET_SUBSCRIPTION_EVENT, $secret);
+        }
+    }
+
     private function writeNullData(User $user): User
     {
         return $user->unsetAttribute(self::METADATA_KEY);

src/Bundle/ChillCalendarBundle/RemoteCalendar/DependencyInjection/RemoteCalendarCompilerPass.php

@@ -12,7 +12,7 @@ declare(strict_types=1);
 namespace Chill\CalendarBundle\RemoteCalendar\DependencyInjection;
 
 use Chill\CalendarBundle\Command\AzureGrantAdminConsentAndAcquireToken;
-use Chill\CalendarBundle\Command\MapUserCalendarCommand;
+use Chill\CalendarBundle\Command\MapAndSubscribeUserCalendarCommand;
 use Chill\CalendarBundle\Controller\RemoteCalendarConnectAzureController;
 use Chill\CalendarBundle\RemoteCalendar\Connector\MSGraphRemoteCalendarConnector;
 use Chill\CalendarBundle\RemoteCalendar\Connector\NullRemoteCalendarConnector;
@@ -37,7 +37,7 @@ class RemoteCalendarCompilerPass implements CompilerPassInterface
             $connector = MSGraphRemoteCalendarConnector::class;
         } else {
             // remove services which cannot be loaded
-            $container->removeDefinition(MapUserCalendarCommand::class);
+            $container->removeDefinition(MapAndSubscribeUserCalendarCommand::class);
             $container->removeDefinition(AzureGrantAdminConsentAndAcquireToken::class);
             $container->removeDefinition(RemoteCalendarConnectAzureController::class);
         }

src/Bundle/ChillMainBundle/Entity/User.php

@@ -359,10 +359,17 @@ class User implements AdvancedUserInterface
         }
     }
 
+    public function setAttributeByDomain(string $domain, string $key, $value): self
+    {
+        $this->attributes[$domain][$key] = $value;
+
+        return $this;
+    }
+
     /**
      * Merge the attributes with existing attributes.
      *
-     * Only the key provided will be created or updated.
+     * Only the key provided will be created or updated. For a two-level array, use @see{User::setAttributeByDomain}
      */
     public function setAttributes(array $attributes): self
     {