Added doc for SiteAccessStamp

[mnocon]

Documentation for ibexa/messenger#13

Turns out we didn't have the "send the message to the transport" covered - adding this as well.

One TODO left: add the missing link once PHP API reference is regenerated

[github-actions]

Preview of modified files

Preview of modified Markdown:

• docs/administration/configuration/dynamic_configuration.md
• docs/infrastructure_and_maintenance/background_tasks.md

[Steveb-p]

Side note: Will be fixed in ibexa/core#798 / 6.0.

We could also make SiteAccessService to listen to CONFIG_SCOPE_CHANGE events in 5.x and react accordingly, and backport the stack feature from 6.0. In theory this is a bug (SiteAccessService::getCurrent() returning wrong site access), so we would not exactly break BC promise - but initially I thought we shouldn't.

@konradoboza @alongosz @ibexa/php-dev ?

[mnocon]

So, if I understand correctly, this note can be removed in 5.0 and 6.0 when ibexa/core#805 is merged? Depending on whether it gets merged before or after the release, in this PR or in a follow-up.

[adriendupuis]

As a SomeMessage object isn't created and dispatched, the doc seems incomplete.
"Route message to background queue" should be more clearly mandatory and a follow up of handler creation in previous section. An handler alone doesn't sent to background tasks queue? No, you need a message provider tagged properly to forward the message to background. Maybe a little summary of the needed elements before entering into code examples?

[adriendupuis]

Do we hare reco about what should be the default SiteAccess?
I don't remember why I used admin in https://doc.ibexa.co/en/5.0/getting_started/install_with_ddev/#configure-background-tasks-optional

[mnocon]

@Steveb-p what do you think, which SiteAccess should the worker use by default - can we recommend something?

I guess it doesn't matter, as long it's one SA per each repository configured and SiteAccess stamps are added correctly

[adriendupuis]

Again, which siteaccess to pick-up? A random front or the back office?

[mnocon]

@adriendupuis please have a look at fe4b1b3 - I've changed the example to create a custom message, and added more info about the need for sending to transport.

[github-actions]

code_samples/ change report

Before (on target branch)	After (in current PR)
code_samples/background_tasks/src/Dispatcher/SomeClassThatSchedulesExecutionInTheBackground.php	code_samples/background_tasks/src/Dispatcher/SomeClassThatSchedulesExecutionInTheBackground.php
docs/infrastructure_and_maintenance/background_tasks.md@164:``` php docs/infrastructure_and_maintenance/background_tasks.md@165:[[= include_code('code_samples/background_tasks/src/Dispatcher/SomeClassThatSchedulesExecutionInTheBackground.php', 1, 19, remove_indent=True) =]] docs/infrastructure_and_maintenance/background_tasks.md@166:[[= include_code('code_samples/background_tasks/src/Dispatcher/SomeClassThatSchedulesExecutionInTheBackground.php', 23, 24, remove_indent=True) =]] docs/infrastructure_and_maintenance/background_tasks.md@167:```	docs/infrastructure_and_maintenance/background_tasks.md@171: ``` php docs/infrastructure_and_maintenance/background_tasks.md@172: [[= include_code('code_samples/background_tasks/src/Dispatcher/SomeClassThatSchedulesExecutionInTheBackground.php', 1, 5, indent_level=1) =]] docs/infrastructure_and_maintenance/background_tasks.md@173: [[= include_code('code_samples/background_tasks/src/Dispatcher/SomeClassThatSchedulesExecutionInTheBackground.php', 7, 20, indent_level=1) =]] docs/infrastructure_and_maintenance/background_tasks.md@174: [[= include_code('code_samples/background_tasks/src/Dispatcher/SomeClassThatSchedulesExecutionInTheBackground.php', 24, 25, indent_level=1) =]] docs/infrastructure_and_maintenance/background_tasks.md@175: ```
001⫶<?php declare(strict_types=1);	001⫶ <?php declare(strict_types=1);
002⫶ 003⫶namespace App\Dispatcher; 004⫶	002⫶ 003⫶namespace App\Dispatcher; 004⫶
005⫶use Ibexa\Bundle\Messenger\Stamp\DeduplicateStamp; 006⫶use Symfony\Component\Messenger\MessageBusInterface;	005⫶use App\Message\SomeMessage; 006⫶ use Symfony\Component\Messenger\MessageBusInterface;
007⫶ 008⫶final class SomeClassThatSchedulesExecutionInTheBackground 009⫶{ 010⫶ private MessageBusInterface $bus; 011⫶ 012⫶ public function __construct(MessageBusInterface $bus) 013⫶ { 014⫶ $this->bus = $bus; 015⫶ } 016⫶	007⫶ 008⫶final class SomeClassThatSchedulesExecutionInTheBackground 009⫶{ 010⫶ private MessageBusInterface $bus; 011⫶ 012⫶ public function __construct(MessageBusInterface $bus) 013⫶ { 014⫶ $this->bus = $bus; 015⫶ } 016⫶
017⫶ public function schedule(object $message): void	017⫶ public function schedule(): void
018⫶ {	018⫶ {
019⫶ $this->bus->dispatch($message); 020⫶ }	019⫶ $this->bus->dispatch(new SomeMessage()); 020⫶ }
021⫶} code_samples/background_tasks/src/Messenger/SomeMessageProvider.php	021⫶} code_samples/background_tasks/src/Messenger/SomeMessageProvider.php
	docs/infrastructure_and_maintenance/background_tasks.md@274:``` php hl_lines="12" docs/infrastructure_and_maintenance/background_tasks.md@275:[[= include_file('code_samples/background_tasks/src/Messenger/SomeMessageProvider.php') =]] docs/infrastructure_and_maintenance/background_tasks.md@276:``` 001⫶<?php declare(strict_types=1); 002⫶ 003⫶namespace App\Messenger; 004⫶ 005⫶use App\Message\SomeMessage; 006⫶use Ibexa\Contracts\Messenger\Transport\MessageProviderInterface; 007⫶ 008⫶final class SomeMessageProvider implements MessageProviderInterface 009⫶{ 010⫶ public function getHandledClasses(): iterable 011⫶ { 012❇️ return [SomeMessage::class]; 013⫶ } 014⫶}

Download colorized diff

[adriendupuis]

Could be nice to have an additional note about what to consider when picking up a default SiteAccess to run the background worker.
But my main previous concern is solved and this is mergeable.