Hi guys,<\/p>\n
Every TYPO3 project I touch sooner or later needs a CLI command. A data import from a partner system, a cleanup after a migration, a report for an editor. In the old days that meant a scheduler task class with a lot of boilerplate, later an Extbase command controller. Today a TYPO3 command is just a Symfony console command, and in TYPO3 v14 you need almost no configuration for it.<\/p>\n
This post builds one small but real command, step by step, and ends with a functional test. The example comes from my hoja.in migration: after importing old content into TYPO3 v14, I wanted to be sure that no “External link” page is left without a link target (the old Your extension needs the usual The Symfony attribute is accepted by TYPO3 since 12.4 (Important #101567). Before that you had to tag every command in Some decisions in there:<\/p>\n After a cache flush the command is listed under its namespace:<\/p>\n If EXT:scheduler is installed, every command is schedulable by default. You create a task of type “Execute console commands” and pick your command in the “Schedulable Command” field; arguments and options can be set after saving the task once. That is all, no separate task class.<\/p>\n Some commands should never run unattended, for example an import that needs a fresh file from a person. Before v14 you had to go back to the The core uses it itself: A command that changes data deserves a test with a real database. The TYPO3 testing framework (version 9 supports v13 and v14) gives you a fresh instance per test case. The fixture has one healthy link page and one broken one:<\/p>\n Cheers!<\/p>\n A small cleanup command for TYPO3 v14: #[AsCommand] with autoconfiguration, ConnectionPool injected, SymfonyStyle output, scheduler support and a functional test with CommandTester.<\/p>\n","protected":false},"author":1,"featured_media":103,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[17],"tags":[37,30,32,31,24],"class_list":["post-102","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-typo3","tag-automation","tag-extension-development","tag-php-8","tag-testing","tag-typo3-v14"],"yoast_head":"\npages.url<\/code> field was replaced by pages.link<\/code>, Breaking #17406). The command lists such pages and can hide them.<\/p>\nStep 1: Services.yaml with autoconfiguration<\/h2>\n
Configuration\/Services.yaml<\/code>. With autoconfigure: true<\/code>, every class that carries #[AsCommand]<\/code> is registered as a console command. No extra tag needed.<\/p>\n# EXT:sitepackage\/Configuration\/Services.yaml\nservices:\n _defaults:\n autowire: true\n autoconfigure: true\n public: false\n\n HarvisoftSitepackage:\n resource: '..\/Classes\/*'<\/code><\/pre>\nServices.yaml<\/code> with console.command<\/code>. The old way still works, but there is no reason to write it for new code.<\/p>\nStep 2: the command class<\/h2>\n
<?php\n\ndeclare(strict_types=1);\n\nnamespace HarvisoftSitepackageCommand;\n\nuse SymfonyComponentConsoleAttributeAsCommand;\nuse SymfonyComponentConsoleCommandCommand;\nuse SymfonyComponentConsoleInputInputInterface;\nuse SymfonyComponentConsoleInputInputOption;\nuse SymfonyComponentConsoleOutputOutputInterface;\nuse SymfonyComponentConsoleStyleSymfonyStyle;\nuse TYPO3CMSCoreDatabaseConnection;\nuse TYPO3CMSCoreDatabaseConnectionPool;\nuse TYPO3CMSCoreDomainRepositoryPageRepository;\n\n#[AsCommand(\n name: 'sitepackage:links:hide-empty',\n description: 'Hides \"External link\" pages that have no link target.',\n)]\nfinal class HideEmptyLinkPagesCommand extends Command\n{\n public function __construct(private readonly ConnectionPool $connectionPool)\n {\n parent::__construct();\n }\n\n protected function configure(): void\n {\n $this->addOption('dry-run', null, InputOption::VALUE_NONE, 'Only report, change nothing');\n }\n\n protected function execute(InputInterface $input, OutputInterface $output): int\n {\n $io = new SymfonyStyle($input, $output);\n $rows = $this->findLinkPagesWithoutTarget();\n\n if ($rows === []) {\n $io->success('Every external link page has a target.');\n return Command::SUCCESS;\n }\n\n $io->table(['uid', 'title'], array_map(\n static fn(array $row): array => [$row['uid'], $row['title']],\n $rows\n ));\n\n if ($input->getOption('dry-run')) {\n $io->note(sprintf('%d page(s) would be hidden.', count($rows)));\n return Command::SUCCESS;\n }\n\n $connection = $this->connectionPool->getConnectionForTable('pages');\n $io->progressStart(count($rows));\n foreach ($rows as $row) {\n $connection->update('pages', ['hidden' => 1], ['uid' => (int)$row['uid']]);\n $io->progressAdvance();\n }\n $io->progressFinish();\n $io->success(sprintf('%d page(s) hidden.', count($rows)));\n\n return Command::SUCCESS;\n }\n\n \/**\n * @return list<array{uid: int, title: string}>\n *\/\n private function findLinkPagesWithoutTarget(): array\n {\n $queryBuilder = $this->connectionPool->getQueryBuilderForTable('pages');\n \/\/ Default restrictions already skip deleted and hidden pages\n return $queryBuilder\n ->select('uid', 'title')\n ->from('pages')\n ->where(\n $queryBuilder->expr()->eq(\n 'doktype',\n $queryBuilder->createNamedParameter(PageRepository::DOKTYPE_LINK, Connection::PARAM_INT)\n ),\n $queryBuilder->expr()->eq('link', $queryBuilder->createNamedParameter(''))\n )\n ->orderBy('uid')\n ->executeQuery()\n ->fetchAllAssociative();\n }\n}<\/code><\/pre>\n\n
ConnectionPool<\/code> comes through the constructor, no GeneralUtility::makeInstance()<\/code>. Do not forget parent::__construct()<\/code>, otherwise Symfony never calls configure()<\/code> and your options are missing.<\/li>\n--dry-run<\/code> option.<\/strong> Every command that changes data should have one. You run it first on production, read the table, and only then run it for real.<\/li>\ntable()<\/code>, progressStart()<\/code>, success()<\/code> and note()<\/code> give readable output for free. When the scheduler runs the command, the output is not shown to anybody, so the return code is what counts. Return Command::FAILURE<\/code> when something went wrong, never just print a red line.<\/li>\nhidden<\/code> on a handful of records this is fine, but it bypasses the DataHandler: no history entry, no cache clearing, no hooks. When editors must see the change in the history or other extensions react to it, use the DataHandler instead; on the CLI that needs a backend user, which you get with Bootstrap::initializeBackendAuthentication()<\/code>.<\/li>\n<\/ul>\nStep 3: run it<\/h2>\n
ddev exec vendor\/bin\/typo3 cache:flush\nddev exec vendor\/bin\/typo3 list sitepackage\nddev exec vendor\/bin\/typo3 sitepackage:links:hide-empty --dry-run<\/code><\/pre>\nStep 4: the scheduler<\/h2>\n
Services.yaml<\/code> tag and set schedulable: false<\/code>. TYPO3 v14.0 added an attribute for this (Feature #107151):<\/p>\nuse SymfonyComponentConsoleAttributeAsCommand;\nuse TYPO3CMSCoreAttributeAsNonSchedulableCommand;\n\n#[AsCommand('sitepackage:import:partners', 'Imports the partner list from a CSV file')]\n#[AsNonSchedulableCommand]\nfinal class ImportPartnersCommand extends Command\n{\n}<\/code><\/pre>\nextension:setup<\/code> carries #[AsNonSchedulableCommand]<\/code>. If you do not use the scheduler at all, a plain cron entry with vendor\/bin\/typo3 sitepackage:links:hide-empty<\/code> works just as well. On hoja.in there is no scheduler installed, so that would be the way.<\/p>\nStep 5: a functional test<\/h2>\n
SymfonyComponentConsoleTesterCommandTester<\/code> runs the command without a shell. Commands are public services in TYPO3, so the container hands you the real, injected object:<\/p>\n<?php\n\ndeclare(strict_types=1);\n\nnamespace HarvisoftSitepackageTestsFunctionalCommand;\n\nuse HarvisoftSitepackageCommandHideEmptyLinkPagesCommand;\nuse PHPUnitFrameworkAttributesTest;\nuse SymfonyComponentConsoleTesterCommandTester;\nuse TYPO3TestingFrameworkCoreFunctionalFunctionalTestCase;\n\nfinal class HideEmptyLinkPagesCommandTest extends FunctionalTestCase\n{\n protected array $testExtensionsToLoad = ['harvisoft\/sitepackage'];\n\n #[Test]\n public function dryRunChangesNothing(): void\n {\n $this->importCSVDataSet(__DIR__ . '\/Fixtures\/pages.csv');\n $tester = new CommandTester($this->get(HideEmptyLinkPagesCommand::class));\n\n $tester->execute(['--dry-run' => true]);\n\n $tester->assertCommandIsSuccessful();\n self::assertStringContainsString('1 page(s) would be hidden', $tester->getDisplay());\n $this->assertCSVDataSet(__DIR__ . '\/Fixtures\/pages.csv');\n }\n\n #[Test]\n public function hidesOnlyLinkPagesWithoutTarget(): void\n {\n $this->importCSVDataSet(__DIR__ . '\/Fixtures\/pages.csv');\n $tester = new CommandTester($this->get(HideEmptyLinkPagesCommand::class));\n\n $tester->execute([]);\n\n $tester->assertCommandIsSuccessful();\n $this->assertCSVDataSet(__DIR__ . '\/Fixtures\/pages_hidden.csv');\n }\n}<\/code><\/pre>\n\"pages\"\n,\"uid\",\"pid\",\"doktype\",\"title\",\"link\",\"hidden\"\n,1,0,1,\"Home\",\"\",0\n,2,1,3,\"Blog\",\"\/blog\/\",0\n,3,1,3,\"Old link\",\"\",0<\/code><\/pre>\npages_hidden.csv<\/code> is the same file with hidden<\/code> set to 1 on uid 3. The first test is the one I care about most: a dry run that writes something is a nasty surprise on production.<\/p>\nSummary<\/h2>\n
\n
#[AsCommand]<\/code> on the class and keep autoconfigure: true<\/code> in Services.yaml<\/code>.<\/li>\nparent::__construct()<\/code>.<\/li>\n--dry-run<\/code> to everything that writes.<\/li>\n#[AsNonSchedulableCommand]<\/code> (v14).<\/li>\nCommandTester<\/code> and CSV fixtures.<\/li>\n<\/ol>\nFurther reading<\/h2>\n
\n