From 22f872f119150e86e558a2f9f6161f6985fca06f Mon Sep 17 00:00:00 2001 From: Sybille Peters Date: Tue, 16 Jul 2019 16:06:23 +0200 Subject: [PATCH] Update and move page for Command Line Dispatcher (Symfony) - remove deprecated description about Extbase command controllers - add new option for schedulable --- .../BackendModules/CliScripts/Index.rst | 159 ------------------ .../ApiOverview/BackendModules/Index.rst | 2 +- .../ApiOverview/CommandControllers/Index.rst | 98 +++++++++++ Documentation/ApiOverview/Index.rst | 1 + 4 files changed, 100 insertions(+), 160 deletions(-) delete mode 100644 Documentation/ApiOverview/BackendModules/CliScripts/Index.rst create mode 100644 Documentation/ApiOverview/CommandControllers/Index.rst diff --git a/Documentation/ApiOverview/BackendModules/CliScripts/Index.rst b/Documentation/ApiOverview/BackendModules/CliScripts/Index.rst deleted file mode 100644 index 46803b4b8e..0000000000 --- a/Documentation/ApiOverview/BackendModules/CliScripts/Index.rst +++ /dev/null @@ -1,159 +0,0 @@ -.. include:: ../../../Includes.txt - - -.. _cli-mode: - -================================== -TYPO3 CMS Shell Scripts (CLI Mode) -================================== - -Besides the backend, it is also possible to run some TYPO3 CMS -scripts from the command line. This makes it possible - for -example - to set up cronjobs. There are two ways to register -CLI scripts: - -#. Using the TYPO3 command-line dispatcher based on Symfony Commands. -#. Creating an Extbase command controller (`deprecated since TYPO3 v9 `_). - - -.. _cli-mode-dispatcher: - -1. The Command-line Dispatcher (Symfony) -======================================== - -TYPO3 uses Symfony commands to provide an easy to use, well-documented API for -writing CLI commands. - -Creating a new Symfony Command in Your Extension ------------------------------------------------- - -Symfony commands should extend the class :php:`Symfony\Component\Console\Command\Command`. - -TYPO3 looks in a file :file:`Commands.php` in the :file:`Configuration` folder of extensions for configured commands. -The :file:`Commands.php` file returns a simple array with the command name and class. - -For example to add a command which can be called via :code:`bin/typo3 yourext:dothings` add the following: - -.. code-block:: php - - return [ - 'yourext:dothings' => [ - 'class' => \Vendor\Extension\Command\DoThingsCommand::class - ], - ]; - -The command should implement at least a :php:`configure` and an :php:`execute` method. - -:php:`configure` as the name would suggest allows to configure the command. -Via :php:`configure` a description or a help text can be added, or mandatory and optional arguments and parameters defined. - -A simple example can be found in the :php:`ListSysLogCommand`: - -.. code-block:: php - - /** - * Configure the command by defining the name, options and arguments - */ - protected function configure() - { - $this->setDescription('Show entries from the sys_log database table of the last 24 hours.'); - $this->setHelp('Prints a list of recent sys_log entries.' . LF . 'If you want to get more detailed information, use the --verbose option.'); - } - - -The :php:`execute` method contains the logic you want to execute when executing the command. - -A detailed description and an example can be found at `the Symfony Command Documentation `_. - - -.. _cli-mode-command-controllers: - -2. Extbase Command Controllers -============================== - -.. warning:: - - Extbase command controllers are deprecated since TYPO3 v9. Use symfony commands as - outlined above. - -Creating an Extbase Command Controller --------------------------------------- - -First of all, the command controller must be registered in an extension's -:file:`ext_localconf.php` file (example taken from the "lang" system -extension): - -.. code-block:: php - - // Register language update command controller - $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['extbase']['commandControllers'][] = \TYPO3\CMS\Lang\Command\LanguageCommandController::class; - -The class itself must extend the :code:`\TYPO3\CMS\Extbase\Mvc\Controller\CommandController` -class. Each action that should be available from the command line must -be named following the pattern "[action name]Command". The PHPdoc information -will be shown as help text on the command line. - -Some commands need to be flexible and therefore need some arguments which may be optional or required. -To make an argument optional, provide a default value. - -You can define them the following way: - -.. code-block:: php - - /** - * @param int $required - * @param bool $optional - */ - public function argumentsCommand($required, $optional = false) - { - - } - - -Example -~~~~~~~ - -Here's an extract from the command controller class of the "lang" -extension: - -.. note:: - - This command controller no longer exists in the TYPO3 core in TYPO3 9. - -.. code-block:: php - - /** - * Language command controller updates translation packages - */ - class LanguageCommandController extends \TYPO3\CMS\Extbase\Mvc\Controller\CommandController - { - // ... - - /** - * Update language file for each extension - * - * @param string $localesToUpdate Comma separated list of locales that needs to be updated - * @return void - */ - public function updateCommand($localesToUpdate = '') - { - // ... - } - } - -Calling an Extbase Command Controller From the Command Line ------------------------------------------------------------ - -This command would be called by using: - -.. code-block:: shell - - $ /path/to/php bin/typo3 extbase language:update fr - -which would update translation packages for the French language. - -Show help: - -.. code-block:: shell - - $ /path/to/php bin/typo3 extbase help language:update \ No newline at end of file diff --git a/Documentation/ApiOverview/BackendModules/Index.rst b/Documentation/ApiOverview/BackendModules/Index.rst index d957e090fd..d2ebafe3f0 100644 --- a/Documentation/ApiOverview/BackendModules/Index.rst +++ b/Documentation/ApiOverview/BackendModules/Index.rst @@ -19,5 +19,5 @@ backend. They are described in this chapter. Structure/Index TemplateClass/Index BackendModuleApi/Index - CliScripts/Index + diff --git a/Documentation/ApiOverview/CommandControllers/Index.rst b/Documentation/ApiOverview/CommandControllers/Index.rst new file mode 100644 index 0000000000..be6f54818c --- /dev/null +++ b/Documentation/ApiOverview/CommandControllers/Index.rst @@ -0,0 +1,98 @@ +.. include:: ../../Includes.txt + + +.. _cli-mode: +.. _cli-mode-dispatcher: +.. _cli-mode-command-controllers: + +================================== +Command Line Dispatcher (Symfony) +================================== + +It is possible to run some TYPO3 CMS scripts from the +command line. This makes it possible - for example - +to set up cronjobs. + +TYPO3 uses Symfony commands to provide an easy to use, well-documented API for +writing CLI (command line interface) commands. + + +Creating a new Symfony Command in Your Extension +------------------------------------------------ + +.. rst-class:: bignums-xxl + +#. Add :file:`Configuration/Commands.php` to your extension + + TYPO3 looks in this file for configured commands. It should + return a simple array with the command name and class. + + For example to add a command named **yourext:dothings**:: + + return [ + 'yourext:dothings' => [ + 'class' => \Vendor\Extension\Command\DoThingsCommand::class + ], + ]; + + By default, the command can be used in the scheduler too. You can deactivate + this by setting `schedulable` to `false`:: + + return [ + 'yourext:dothings' => [ + 'class' => \Vendor\Extension\Command\DoThingsCommand::class, + 'schedulable' => false, + ] + ]; + + +#. Create the corresponding class file: :file:`Classes/Command/DoThingsCommand.php` + + Symfony commands should extend the class :php:`Symfony\Component\Console\Command\Command`. + + The command should implement at least a :php:`configure` and an :php:`execute` method. + + + **configure()** as the name would suggest allows to configure the command. + Via :php:`configure()`, a description or a help text can be added, or mandatory and optional arguments and parameters defined. + + A simple example can be found in the :php:`ListSysLogCommand`: + + .. code-block:: php + + /** + * Configure the command by defining the name, options and arguments + */ + protected function configure() + { + $this->setDescription('Show entries from the sys_log database table of the last 24 hours.'); + $this->setHelp('Prints a list of recent sys_log entries.' . LF . 'If you want to get more detailed information, use the --verbose option.'); + } + + + + **execute()** contains the logic you want to execute when executing the command. + +.. seealso:: + + A detailed description and an example can be found in `the Symfony Command Documentation `_. + +Running the Command From the Command Line +----------------------------------------- + +The above example can be run via command line: + +.. code-block:: bash + + bin/typo3 yourext:dothings + + +Running the Command From the Scheduler +-------------------------------------- + +By default, it is possible to run the command from the +`TYPO3 scheduler `__ as well +if (`schedulable` is not set to false). + +In the backend: :guilabel:`SYSTEM > Scheduler` + diff --git a/Documentation/ApiOverview/Index.rst b/Documentation/ApiOverview/Index.rst index 7ab58b47bf..466182872e 100644 --- a/Documentation/ApiOverview/Index.rst +++ b/Documentation/ApiOverview/Index.rst @@ -28,6 +28,7 @@ This chapter describes the most important elements of the API. BackendModules/Index BackendRouting/Index BackendUserObject/Index + CommandControllers/Index Context/Index Typo3CoreEngine/Index FormEngine/Index