From fbf9255c67889b8135e34990d7fdaf129baf9b2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Fri, 10 Jul 2026 16:26:32 +0200 Subject: [PATCH 1/5] Described stamps for Ibexa Messenger (#3272) * Described stamps for Ibexa Messenger * Fixed typos * Link to Symfony messages --- mkdocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 835467c4bc..7c6d1de7c7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -989,8 +989,9 @@ extra: latest_tag_5_0: '5.0.9' symfony_doc: 'https://symfony.com/doc/5.x' + symfony_version: '5.6' + user_doc: 'https://doc.ibexa.co/projects/userguide/en/4.6' - symfony_version: '5.4' connect_doc: 'https://doc.ibexa.co/projects/connect/en/latest' extra_css: From 62b9391faab6535f83bf6f2e4507e486ef1ccf9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 4 Aug 2026 12:50:37 +0200 Subject: [PATCH 2/5] Added doc for SiteAccess stamp --- .../background_tasks.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/infrastructure_and_maintenance/background_tasks.md b/docs/infrastructure_and_maintenance/background_tasks.md index 8a9b476530..298cba2bc0 100644 --- a/docs/infrastructure_and_maintenance/background_tasks.md +++ b/docs/infrastructure_and_maintenance/background_tasks.md @@ -137,7 +137,11 @@ Use a process manager of your choice to run the following command, or make it st php bin/console messenger:consume ibexa.messenger.transport --bus=ibexa.messenger.bus --siteaccess=` ``` -In [multi-repository setups](repository_configuration.md), the worker process always works for a [SiteAccess](multisite_configuration.md#siteaccess-configuration) that you indicate by using the `--siteaccess` option, therefore you may need to run multiple workers, one for each SiteAccess. +Use the `--siteaccess` option to set the [SiteAccess](multisite_configuration.md#siteaccess-configuration) and [repository](repository_configuration.md#defining-custom-connection) for the worker process. +The [`SiteAccessStamp`](#siteaccessstamp) sets the correct SiteAccess configuration for processing the message and one worker process can handle messages coming from different SiteAccesses. + +In [multi-repository setups](repository_configuration.md), run one worker process for each repository. +With this setup, each worker process can connect to the right database. !!! caution "Multi-repository setups" @@ -184,6 +188,7 @@ You can use the following Symfony stamps: On top of the supported Symfony stamps, [[= product_name =]] provides the following ones: - [`DeduplicateStamp`](#deduplicatestamp) +- [`SiteAccessStamp`](#siteaccessstamp) #### DeduplicateStamp @@ -193,6 +198,14 @@ When you attach it to a message, the system uses a lock to ensure that only one This stamp is backported from Symfony 7. For more information, see [Symfony 7.4 documentation about message deduplication](https://symfony.com/doc/7.4//messenger.html#message-deduplication). +#### SiteAccessStamp + +[`Ibexa\Contracts\Messenger\Stamp\SiteAccessStamp`](https://example.com/add-link-when-php-api-reference-is-generated) contains the name of the [SiteAccess](multisite_configuration.md#siteaccess-configuration) that dispatched the message. + +You don't need to add this stamp manually, [[= product_name_base =]] Messenger attaches this stamp to each dispatched message automatically. + +When processing the message, the worker sets the SiteAccess configuration named in the stamp before calling the handler. + ## Extend Ibexa Messenger ### Register custom message and handler From 3efd324fbfea5706d2b0b98a6736200eaa2a364b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 4 Aug 2026 15:55:28 +0200 Subject: [PATCH 3/5] Selfreview: SiteAccessStamp + MessageProvider --- .../src/Messenger/SomeMessageProvider.php | 14 ++++ .../configuration/dynamic_configuration.md | 4 +- .../background_tasks.md | 72 +++++++++++++++---- 3 files changed, 73 insertions(+), 17 deletions(-) create mode 100644 code_samples/background_tasks/src/Messenger/SomeMessageProvider.php diff --git a/code_samples/background_tasks/src/Messenger/SomeMessageProvider.php b/code_samples/background_tasks/src/Messenger/SomeMessageProvider.php new file mode 100644 index 0000000000..98f53c7123 --- /dev/null +++ b/code_samples/background_tasks/src/Messenger/SomeMessageProvider.php @@ -0,0 +1,14 @@ +` +php bin/console messenger:consume ibexa.messenger.transport --bus=ibexa.messenger.bus --siteaccess= ``` -Use the `--siteaccess` option to set the [SiteAccess](multisite_configuration.md#siteaccess-configuration) and [repository](repository_configuration.md#defining-custom-connection) for the worker process. -The [`SiteAccessStamp`](#siteaccessstamp) sets the correct SiteAccess configuration for processing the message and one worker process can handle messages coming from different SiteAccesses. +Use the `--siteaccess` option to set the default [SiteAccess](multisite_configuration.md#siteaccess-configuration) and [repository](repository_configuration.md#defining-custom-connection) for the worker process. +The worker uses this SiteAccess for every message that does not have a [`SiteAccessStamp`](#siteaccessstamp). + +If a message has a `SiteAccessStamp`, the worker uses the SiteAccess from the stamp instead to processes this message. +Thanks to this, one worker process can handle messages coming from different SiteAccesses. In [multi-repository setups](repository_configuration.md), run one worker process for each repository. With this setup, each worker process can connect to the right database. @@ -158,19 +161,21 @@ To have a task processed in the background by [[= product_name_base =]] Messenge 1. Inject the `ibexa.messenger.bus` service as an object implementing the `Symfony\Component\Messenger\MessageBusInterface` interface. 2. Dispatch an appropriate message by using the `MessageBusInterface::dispatch()` method, exactly as described in [Symfony Messenger documentation]([[= symfony_doc =]]/messenger.html#dispatching-the-message). -``` yaml -services: - SomeClassThatSchedulesExecutionInTheBackground: - arguments: - $bus: '@ibexa.messenger.bus' -``` + ``` yaml + services: + SomeClassThatSchedulesExecutionInTheBackground: + arguments: + $bus: '@ibexa.messenger.bus' + ``` -``` php -[[= include_code('code_samples/background_tasks/src/Dispatcher/SomeClassThatSchedulesExecutionInTheBackground.php', 1, 19, remove_indent=True) =]] -[[= include_code('code_samples/background_tasks/src/Dispatcher/SomeClassThatSchedulesExecutionInTheBackground.php', 23, 24, remove_indent=True) =]] -``` + ``` php + [[= include_code('code_samples/background_tasks/src/Dispatcher/SomeClassThatSchedulesExecutionInTheBackground.php', 1, 19, indent_level=1) =]] + [[= include_code('code_samples/background_tasks/src/Dispatcher/SomeClassThatSchedulesExecutionInTheBackground.php', 23, 24, indent_level=1) =]] + ``` + +3. [Route the message to the background queue](#route-message-to-background-queue). -Additionally, attach message metadata by using [stamps](#stamps). +4. Additionally, attach message metadata by using [stamps](#stamps). ### Stamps @@ -203,8 +208,18 @@ For more information, see [Symfony 7.4 documentation about message deduplication [`Ibexa\Contracts\Messenger\Stamp\SiteAccessStamp`](https://example.com/add-link-when-php-api-reference-is-generated) contains the name of the [SiteAccess](multisite_configuration.md#siteaccess-configuration) that dispatched the message. You don't need to add this stamp manually, [[= product_name_base =]] Messenger attaches this stamp to each dispatched message automatically. +The stamp contains the SiteAccess that is current at the moment of dispatch. + +Before the worker calls the handler, it changes the configuration scope to the SiteAccess from the stamp. +The handler then reads [SiteAccess-aware configuration](multisite_configuration.md#siteaccess-configuration) for the SiteAccess that dispatched the message, and not for the SiteAccess that the worker process started with. -When processing the message, the worker sets the SiteAccess configuration named in the stamp before calling the handler. +!!! caution "The stamp doesn't change the current SiteAccess" + + The stamp changes the configuration scope only. + It doesn't change the SiteAccess in the `Ibexa\Core\MVC\Symfony\SiteAccess\SiteAccessServiceInterface` service. + `SiteAccessServiceInterface::getCurrent()` always returns the SiteAccess that the worker process started with, for all messages. + + To get a SiteAccess-aware value in a handler, use the [`ConfigResolverInterface` service](dynamic_configuration.md). ## Extend Ibexa Messenger @@ -229,3 +244,30 @@ services: - name: messenger.message_handler bus: ibexa.messenger.bus ``` + +### Route message to background queue + +To have a message processed in the background, it must be sent to a transport queue. +[[= product_name_base =]] Messenger uses message providers instead of [Symfony `framework.messenger.routing` configuration]([[= symfony_doc =]]/messenger.html#routing-messages-to-a-transport). + +A message provider is a service that implements the [`MessageProviderInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Messenger-Transport-MessageProviderInterface.html) interface, and the `getHandledClasses()` method must return the list of message classes that [[= product_name_base =]] Messenger must send to the queue to process in the background. + +The `getHandledClasses()` method can also return a parent class or an interface. +In this case, all messages that extend this class, or implement this interface, go to the background queue. + +If no message provider returns the class of your message, the bus calls the handler immediately, in the same process that dispatches the message. + +To send `SomeMessage` to the background queue, create the following provider: + +``` php hl_lines="12" +[[= include_file("code_samples/background_tasks/src/Messenger/SomeMessageProvider.php") =]] +``` + +If you're not using service autoconfiguration, add the `ibexa.messenger.sender_message_provider` tag to the service: + +``` yaml hl_lines="4" +services: + App\Messenger\SomeMessageProvider: + tags: + - name: ibexa.messenger.sender_message_provider +``` From c0457e767a110393a9c3411c3b40f44db1f475bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 4 Aug 2026 16:08:03 +0200 Subject: [PATCH 4/5] Fixed link --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 7c6d1de7c7..77248d6c0d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -989,7 +989,7 @@ extra: latest_tag_5_0: '5.0.9' symfony_doc: 'https://symfony.com/doc/5.x' - symfony_version: '5.6' + symfony_version: '5.4' user_doc: 'https://doc.ibexa.co/projects/userguide/en/4.6' connect_doc: 'https://doc.ibexa.co/projects/connect/en/latest' From ec0ac6ab81543397d106f3e3f46669303641ba6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 4 Aug 2026 16:16:16 +0200 Subject: [PATCH 5/5] Selfreview --- docs/infrastructure_and_maintenance/background_tasks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/infrastructure_and_maintenance/background_tasks.md b/docs/infrastructure_and_maintenance/background_tasks.md index 716cb9e49b..fd9c995cfc 100644 --- a/docs/infrastructure_and_maintenance/background_tasks.md +++ b/docs/infrastructure_and_maintenance/background_tasks.md @@ -94,7 +94,7 @@ The process works as follows: 1. A message PHP object is dispatched, for example, `ProductPriceReindex`. 2. The message is wrapped in an envelope, which may contain additional metadata, called [stamps](#stamps). -3. The message is placed in the transport queue. +3. The message is placed in the [transport queue](#route-message-to-background-queue). It can be a Doctrine table, a Redis/Valkey queue, and so on. 4. A worker process continuously reads messages from the queue, pulls them into the default bus `ibexa.messenger.bus` and assigns them to the right handler. 5. A handler service processes the message (executes the command). @@ -138,7 +138,7 @@ php bin/console messenger:consume ibexa.messenger.transport --bus=ibexa.messenge ``` Use the `--siteaccess` option to set the default [SiteAccess](multisite_configuration.md#siteaccess-configuration) and [repository](repository_configuration.md#defining-custom-connection) for the worker process. -The worker uses this SiteAccess for every message that does not have a [`SiteAccessStamp`](#siteaccessstamp). +The worker uses this SiteAccess for every message that doesn't have a [`SiteAccessStamp`](#siteaccessstamp). If a message has a `SiteAccessStamp`, the worker uses the SiteAccess from the stamp instead to processes this message. Thanks to this, one worker process can handle messages coming from different SiteAccesses. @@ -205,7 +205,7 @@ For more information, see [Symfony 7.4 documentation about message deduplication #### SiteAccessStamp -[`Ibexa\Contracts\Messenger\Stamp\SiteAccessStamp`](https://example.com/add-link-when-php-api-reference-is-generated) contains the name of the [SiteAccess](multisite_configuration.md#siteaccess-configuration) that dispatched the message. +[`Ibexa\Contracts\Messenger\Stamp\SiteAccessStamp`](https://example.com/add-link-when-php-api-reference-is-generated) contains the name of the [SiteAccess](siteaccess.md) that dispatched the message. You don't need to add this stamp manually, [[= product_name_base =]] Messenger attaches this stamp to each dispatched message automatically. The stamp contains the SiteAccess that is current at the moment of dispatch.