@@ -1897,6 +1897,122 @@ on a case-by-case basis via the :class:`Symfony\\Component\\Messenger\\Stamp\\Se
18971897 provides that control. See `SymfonyCasts' message serializer tutorial `_ for
18981898 details.
18991899
1900+ Running Commands And External Processes
1901+ ---------------------------------------
1902+
1903+ Trigger a Command
1904+ ~~~~~~~~~~~~~~~~~
1905+
1906+ It is possible to trigger any command by dispatching a
1907+ :class: `Symfony\\ Component\\ Console\\ Messenger\\ RunCommandMessage `. Symfony
1908+ will take care of handling this message and execute the command passed
1909+ to the message parameter::
1910+
1911+ use Symfony\Component\Console\Messenger\RunCommandMessage;
1912+ use Symfony\Component\Messenger\MessageBusInterface;
1913+
1914+ class CleanUpService
1915+ {
1916+ public function __construct(private readonly MessageBusInterface $bus)
1917+ {
1918+ }
1919+
1920+ public function cleanUp(): void
1921+ {
1922+ // Long task with some caching...
1923+
1924+ // Once finished, dispatch some clean up commands
1925+ $this->bus->dispatch(new RunCommandMessage('app:my-cache:clean-up'));
1926+ $this->bus->dispatch(new RunCommandMessage('cache:clear'));
1927+ }
1928+ }
1929+
1930+ You can configure the behavior to adopt if something goes wrong during command
1931+ execution. To do so, you can use the ``throwOnFailure `` and ``catchExceptions ``
1932+ parameters when creating your instance of
1933+ :class: `Symfony\\ Component\\ Console\\ Messenger\\ RunCommandMessage `.
1934+
1935+ ..versionadded ::6.4
1936+
1937+ The:class: `Symfony\\ Component\\ Console\\ Messenger\\ RunCommandMessage `
1938+ class was introduced in Symfony 6.4.
1939+
1940+ Trigger An External Process
1941+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1942+
1943+ Messenger comes with a handy helper to run external processes by
1944+ dispatching a message. This takes advantages of the
1945+ :doc: `Process component </components/process >`. By dispatching a
1946+ :class: `Symfony\\ Component\\ Process\\ Messenger\\ RunProcessMessage `, Messenger
1947+ will take care of creating a new process with the parameters you passed::
1948+
1949+ use Symfony\Component\Messenger\MessageBusInterface;
1950+ use Symfony\Component\Process\Messenger\RunProcessMessage;
1951+
1952+ class CleanUpService
1953+ {
1954+ public function __construct(private readonly MessageBusInterface $bus)
1955+ {
1956+ }
1957+
1958+ public function cleanUp(): void
1959+ {
1960+ $this->bus->dispatch(new RunProcessMessage(['rm', '-rf', 'var/log/temp/*'], cwd: '/my/custom/working-dir'));
1961+
1962+ // ...
1963+ }
1964+ }
1965+
1966+ Once handled, the message will contain many useful information such as the exit
1967+ code or the output of the process. You can refer to the page dedicated on
1968+ :doc: `handler results </messenger/handler_results >` for more information.
1969+
1970+ ..versionadded ::6.4
1971+
1972+ The:class: `Symfony\\ Component\\ Process\\ Messenger\\ RunProcessMessage `
1973+ class was introduced in Symfony 6.4.
1974+
1975+ Pinging A Webservice
1976+ --------------------
1977+
1978+ Sometimes, you may need to regularly ping a webservice to get its status, e.g.
1979+ is is up or down. It is possible to do so by dispatching a
1980+ :class: `Symfony\\ Component\\ HttpClient\\ Messenger\\ PingWebhookMessage `::
1981+
1982+ use Symfony\Component\HttpClient\Messenger\RPingWebhookMessage;
1983+ use Symfony\Component\Messenger\MessageBusInterface;
1984+
1985+ class LivenessService
1986+ {
1987+ public function __construct(private readonly MessageBusInterface $bus)
1988+ {
1989+ }
1990+
1991+ public function ping(): void
1992+ {
1993+ // An HttpExceptionInterface is thrown on 3xx/4xx/5xx
1994+ $this->bus->dispatch(new PingWebhookMessage('GET', 'https://example.com/status');
1995+
1996+ // Ping, but does not throw on 3xx/4xx/5xx
1997+ $this->bus->dispatch(new PingWebhookMessage('GET', 'https://example.com/status', throw: false);
1998+
1999+ // Any valid HttpClientInterface option can be used
2000+ $this->bus->dispatch(new PingWebhookMessage('POST', 'https://example.com/status', [
2001+ 'headers' => [
2002+ 'Authorization' => 'Bearer ...'
2003+ ],
2004+ 'json' => [
2005+ 'data' => 'some-data',
2006+ ],
2007+ ]);
2008+ }
2009+ }
2010+
2011+ ..versionadded ::6.4
2012+
2013+ The:class: `Symfony\\ Component\\ HttpClient\\ Messenger\\ PingWebhookMessage `
2014+ class was introduced in Symfony 6.4.
2015+
19002016Customizing Handlers
19012017--------------------
19022018