[TASK] Create a frontend request in a console command (#5375)

* [TASK] Add information on how to create a frontend request in a console command.

Releases: main, 13.4, 12.4

* Reduce example to FluidEmail only

* Explain problem with linking from CLI

* Update Tutorial.rst

* Replace TSFE with FrontendTyposcriptFactory

---------

Co-authored-by: Stefan Froemken <froemken@gmail.com>

Author: linawolf

Documentation/ApiOverview/CommandControllers/Tutorial.rst

@@ -281,6 +281,69 @@ A backend user can be initialized with this call inside :php:`execute()` method:
 This is necessary when using :ref:`DataHandler <datahandler-basics>`
 or other backend permission handling related tasks.
 
+
+..  _console-command-tutorial-fe-request:
+
+Simulating a Frontend Request in TYPO3 Commands
+===============================================
+
+When executing TYPO3 commands in the CLI, there is no actual frontend (web)
+request. This means that several request attributes required for link generation
+via Fluid or TypoScript are missing by default. While setting the `site`
+attribute in the request is a first step, it does not fully replicate the
+frontend behavior.
+
+..  _console-command-tutorial-fe-request-challenge:
+
+The Challenge
+-------------
+
+In a web request, TYPO3 automatically provides various objects that influence
+link generation:
+
+*   **ContentObjectRenderer (cObj)**: Processes TypoScript-based rendering,
+    including link generation.
+*   **page Attribute**: Holds the current page context.
+*   **PageInformation Object**: Provides additional metadata about the current
+    page.
+*   **Router**: Ensures proper URL resolution.
+*   **FrontendTypoScriptFactory (was part of TSFE at the time)**: Collects
+    TypoScript and provides settings like `linkAccessRestrictedPages` and
+    `typolinkLinkAccessRestrictedPages`.
+
+One critical limitation is that the ContentObjectRenderer (cObj) is only
+available when a TypoScript-based content element, such as `FLUIDTEMPLATE`, is
+rendered. Even if `cObj` is manually instantiated in a CLI command, its data
+array remains empty, meaning it lacks the context of a real `tt_content` record.
+As a result, TypoScript properties like `field = my_field` or `data = my_data`
+will not work as expected.
+
+Similarly, the FrontendTypoScriptFactory is not automatically
+available in CLI. If CLI-generated links should respect settings like
+`linkAccessRestrictedPages`, it would have to be manually instantiated and
+configured.
+
+..  _console-command-tutorial-fe-request-example:
+
+A Minimal Request Example
+-------------------------
+
+In some cases, a minimal request configuration may be sufficient, such as when
+generating simple links or using FluidEmail. The following example demonstrates
+how to set up a basic CLI request with `applicationType` and `site` attributes:
+
+..  literalinclude:: _Tutorial/_InitializeRequest.php
+    :caption: packages/my_extension/Classes/Command/DoBackendRelatedThingsCommand.php
+
+..  note::
+    It is important to understand that there is no simple way to fully simulate
+    a frontend request in CLI. Some aspects, like basic link generation, can
+    work by manually setting request attributes. However, complex
+    TypoScript-based link modifications, access restrictions, and context-aware
+    rendering will not behave identically to a real web request. Developers
+    need to be aware of these limitations when working with link generation in
+    CLI commands.
+
 More information
 ================
 

Documentation/ApiOverview/CommandControllers/_Tutorial/_InitializeRequest.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace T3docs\Examples\Command;
+
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+use TYPO3\CMS\Core\Core\Bootstrap;
+use TYPO3\CMS\Core\Core\SystemEnvironmentBuilder;
+use TYPO3\CMS\Core\Http\ServerRequest;
+use TYPO3\CMS\Core\Mail\FluidEmail;
+use TYPO3\CMS\Core\Mail\MailerInterface;
+use TYPO3\CMS\Core\Site\SiteFinder;
+
+#[AsCommand(
+    name: 'examples:dosomething',
+    description: 'A command that does nothing and always succeeds.',
+    aliases: ['examples:dosomethingalias'],
+)]
+class DoSomethingCommand extends Command
+{
+    public function __construct(
+        private readonly SiteFinder $siteFinder,
+        private readonly MailerInterface $mailer,
+    ) {
+        parent::__construct();
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        Bootstrap::initializeBackendAuthentication();
+
+        // The site has to have a fully qualified domain name
+        $site = $this->siteFinder->getSiteByPageId(1);
+        $request = (new ServerRequest())
+            ->withAttribute('applicationType', SystemEnvironmentBuilder::REQUESTTYPE_FE)
+            ->withAttribute('site', $site);
+        $GLOBALS['TYPO3_REQUEST'] = $request;
+        // Send some mails with FluidEmail
+        $email = new FluidEmail();
+        $email->setRequest($request);
+        // Set receiver etc
+        $this->mailer->send($email);
+        return Command::SUCCESS;
+    }
+}

Documentation/ApiOverview/RequestLifeCycle/Typo3Request.rst

@@ -140,6 +140,16 @@ as first argument for the :php:`process()` method. This object provides a
         }
     }
 
+..  _typo3-request-console-command:
+
+Console command
+---------------
+
+Within a `Console command (CLI) <https://docs.typo3.org/permalink/t3coreapi:symfony-console-commands>`_
+there is no request available. See also https://forge.typo3.org/issues/105554
+
+If a request is needed initialize one as described in
+`Initialize a frontend request in a console command <https://docs.typo3.org/permalink/t3coreapi:console-command-tutorial-fe-request>`_.
 
 ..  _typo3-request-global-variable: