From craft-workspace-webconsulting-skills
Guides TYPO3 v14.x extension development with version constraints in composer.json/ext_emconf.php, PHP 8.2+ features, core APIs, patterns, and upgrade workflows. For v14 updates, migrations, LTS core work.
npx claudepluginhub dirnbauer/webconsulting-skillsThis skill uses the workspace's default tool permissions.
> **Strategy:** This collection targets **TYPO3 v14.x only**. Patterns here assume a v14 codebase.
Automates TYPO3 v14 PHP code upgrades using Rector refactoring rules, level sets, and migration workflows. Use for TYPO3 upgrades, rector runs, refactoring, deprecations.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Share bugs, ideas, or general feedback.
Strategy: This collection targets TYPO3 v14.x only. Patterns here assume a v14 codebase. For migrating from older majors, use
typo3-rector,typo3-extension-upgrade, Fractor, and the official upgrade guide first.
TYPO3 API First: Always use TYPO3's built-in APIs, core features, and established conventions before creating custom implementations. Do not reinvent what TYPO3 already provides. Always verify that the APIs and methods you use exist and are not deprecated in TYPO3 v14 by checking the official TYPO3 documentation.
| Version | Role for this collection |
|---|---|
| v14.x | Supported target — examples and constraints assume TYPO3 v14 |
| Older majors | Not targeted — complete a core upgrade, then use these patterns |
Best Practice: Declare TYPO3 v14-only constraints in composer.json and ext_emconf.php for new work.
<?php
// ext_emconf.php — TYPO3 v14
$EM_CONF[$_EXTKEY] = [
'title' => 'My Extension',
'version' => '2.0.0',
'state' => 'stable',
'constraints' => [
'depends' => [
'typo3' => '14.0.0-14.99.99',
'php' => '8.2.0-8.5.99',
],
'conflicts' => [],
'suggests' => [],
],
];
// composer.json — TYPO3 v14
{
"name": "vendor/my-extension",
"type": "typo3-cms-extension",
"require": {
"php": "^8.2",
"typo3/cms-core": "^14.0"
},
"extra": {
"typo3/cms": {
"extension-key": "my_extension"
}
}
}
Content Blocks:
friendsoftypo3/content-blocksmay requiretypo3/cms-core^14.1 or higher — match the Packagist constraint before pinning^14.0only.
TYPO3 v14 requires PHP 8.2+. Use modern PHP features:
<?php
declare(strict_types=1);
namespace Vendor\Extension\Service;
// ✅ Constructor property promotion (PHP 8.0+)
final class MyService
{
public function __construct(
private readonly SomeDependency $dependency,
private readonly AnotherService $anotherService,
) {}
}
// ✅ Named arguments (PHP 8.0+)
$result = $this->doSomething(
name: 'value',
options: ['key' => 'value'],
);
// ✅ Match expressions (PHP 8.0+)
$type = match ($input) {
'a' => 'Type A',
'b' => 'Type B',
default => 'Unknown',
};
// ✅ Enums (PHP 8.1+)
enum Status: string
{
case Draft = 'draft';
case Published = 'published';
}
<?php
declare(strict_types=1);
namespace Vendor\Extension\Controller;
use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
use Vendor\Extension\Domain\Repository\ItemRepository;
final class ItemController extends ActionController
{
public function __construct(
private readonly ItemRepository $itemRepository,
) {}
// ✅ Must return ResponseInterface (required in TYPO3 v14)
public function listAction(): ResponseInterface
{
$items = $this->itemRepository->findAll();
$this->view->assign('items', $items);
return $this->htmlResponse();
}
public function showAction(int $item): ResponseInterface
{
$item = $this->itemRepository->findByUid($item);
$this->view->assign('item', $item);
return $this->htmlResponse();
}
// ✅ JSON response
public function apiAction(): ResponseInterface
{
$data = ['success' => true, 'items' => []];
return $this->jsonResponse(json_encode($data));
}
// ✅ Redirect
public function createAction(): ResponseInterface
{
// Process creation...
$this->addFlashMessage('Item created');
return $this->redirect('list');
}
}
<?php
declare(strict_types=1);
namespace Vendor\Extension\Controller;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Backend\Attribute\AsController;
use TYPO3\CMS\Backend\Template\ModuleTemplateFactory;
#[AsController]
final class BackendModuleController
{
public function __construct(
private readonly ModuleTemplateFactory $moduleTemplateFactory,
) {}
public function indexAction(ServerRequestInterface $request): ResponseInterface
{
$moduleTemplate = $this->moduleTemplateFactory->create($request);
$moduleTemplate->assign('items', []);
return $moduleTemplate->renderResponse('Backend/Index');
}
}
<?php
declare(strict_types=1);
namespace Vendor\Extension\Service;
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Core\View\ViewFactoryData;
use TYPO3\CMS\Core\View\ViewFactoryInterface;
final class RenderingService
{
public function __construct(
private readonly ViewFactoryInterface $viewFactory,
) {}
public function renderEmail(ServerRequestInterface $request, array $data): string
{
$viewFactoryData = new ViewFactoryData(
templateRootPaths: ['EXT:my_extension/Resources/Private/Templates/Email'],
partialRootPaths: ['EXT:my_extension/Resources/Private/Partials'],
layoutRootPaths: ['EXT:my_extension/Resources/Private/Layouts'],
request: $request,
);
$view = $this->viewFactory->create($viewFactoryData);
$view->assignMultiple($data);
return $view->render('Notification');
}
}
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
xmlns:core="http://typo3.org/ns/TYPO3/CMS/Core/ViewHelpers"
data-namespace-typo3-fluid="true">
<f:layout name="Default" />
<f:section name="Main">
<div class="content">
<!-- ✅ Auto-escaped output -->
<h1>{item.title}</h1>
<!-- ✅ Explicit HTML (use with caution) -->
<f:format.html>{item.bodytext}</f:format.html>
<!-- ✅ Conditional rendering -->
<f:if condition="{items}">
<f:then>
<f:for each="{items}" as="item">
<f:render partial="Item" arguments="{item: item}" />
</f:for>
</f:then>
<f:else>
<p>No items found.</p>
</f:else>
</f:if>
<!-- ✅ Link building -->
<f:link.action action="show" arguments="{item: item.uid}">
View Details
</f:link.action>
</div>
</f:section>
</html>
PSR-14 events are the standard in TYPO3 v14. Always prefer events over hooks.
<?php
declare(strict_types=1);
namespace Vendor\Extension\EventListener;
use TYPO3\CMS\Core\Attribute\AsEventListener;
use TYPO3\CMS\Frontend\Event\ModifyCacheLifetimeForPageEvent;
#[AsEventListener(identifier: 'vendor-extension/modify-cache-lifetime')]
final class ModifyCacheLifetimeListener
{
public function __invoke(ModifyCacheLifetimeForPageEvent $event): void
{
// Reduce cache lifetime for certain pages
if ($event->getPageId() === 123) {
$event->setCacheLifetime(300); // 5 minutes
}
}
}
| Event | Purpose |
|---|---|
ModifyPageLinkConfigurationEvent | Modify link building |
ModifyCacheLifetimeForPageEvent | Adjust page cache |
BeforeStdWrapFunctionsInitializedEvent | Modify stdWrap |
| (DataHandler) | Core ships no generic BeforeRecordOperationEvent / AfterRecordOperationEvent; use SC_OPTIONS DataHandler hooks or documented TYPO3\CMS\Core\DataHandling\Event\* only (list) |
# Configuration/Services.yaml
services:
_defaults:
autowire: true
autoconfigure: true
public: false
Vendor\Extension\:
resource: '../Classes/*'
exclude:
- '../Classes/Domain/Model/*'
# Event listener (alternative to #[AsEventListener] attribute)
Vendor\Extension\EventListener\MyListener:
tags:
- name: event.listener
identifier: 'vendor-extension/my-listener'
<?php
// Configuration/Backend/Modules.php
return [
'web_myextension' => [
'parent' => 'content',
'position' => ['after' => 'records'],
'access' => 'user,group',
'iconIdentifier' => 'myextension-module',
'path' => '/module/content/myextension',
'labels' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang_mod.xlf',
'extensionName' => 'MyExtension',
'controllerActions' => [
\Vendor\MyExtension\Controller\BackendController::class => [
'index',
'list',
'show',
],
],
],
];
<?php
// Configuration/Icons.php
return [
'myextension-module' => [
'provider' => \TYPO3\CMS\Core\Imaging\IconProvider\SvgIconProvider::class,
'source' => 'EXT:my_extension/Resources/Public/Icons/module.svg',
],
];
In v14, runtime TCA modifications are forbidden. Always use static files:
<?php
// Configuration/TCA/tx_myext_domain_model_item.php
return [
'ctrl' => [
'title' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang_db.xlf:tx_myext_domain_model_item',
'label' => 'title',
'tstamp' => 'tstamp',
'crdate' => 'crdate',
'delete' => 'deleted',
'enablecolumns' => [
'disabled' => 'hidden',
'starttime' => 'starttime',
'endtime' => 'endtime',
],
// v14: ctrl `searchFields` removed (Breaking #106972) — mark searchable columns in `columns` instead.
'iconIdentifier' => 'myextension-item',
],
'palettes' => [
'visibility' => [
'showitem' => 'hidden',
],
'access' => [
'showitem' => 'starttime, endtime',
],
],
'types' => [
'1' => [
'showitem' => '
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:general,
title, description,
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:access,
--palette--;;visibility,
--palette--;;access,
',
],
],
'columns' => [
'title' => [
'label' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang_db.xlf:tx_myext_domain_model_item.title',
'config' => [
'type' => 'input',
'size' => 50,
'max' => 255,
'required' => true,
'searchable' => true,
],
],
'description' => [
'label' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang_db.xlf:tx_myext_domain_model_item.description',
'config' => [
'type' => 'text',
'cols' => 40,
'rows' => 5,
'enableRichtext' => true,
'searchable' => true,
],
],
],
];
Since TYPO3 v13.3+, column definitions for fields referenced in ctrl are auto-created by the Core. You no longer need explicit 'columns' entries for:
enablecolumns fields: hidden/disabled, starttime, endtime, fe_groupsys_language_uid, l10n_parent, l10n_diffsourceeditlock, description (if set as descriptionColumn)Convention fields don't need ext_tables.sql -- all fields referenced by ctrl properties (deleted, hidden, starttime, endtime, fe_group, sorting, tstamp, crdate, sys_language_uid, l10n_parent, l10n_diffsource) are added to the database automatically. Defining them in ext_tables.sql may cause problems.
Fields that never need columns definitions:
deleted -- handled by DataHandler, not shown in formststamp, crdate, t3_origuid -- managed by DataHandler, never displayedsorting -- managed by DataHandler, should NOT be in columnsStill required:
ctrl properties themselves (tstamp, crdate, delete, enablecolumns, etc.)showitem / palettes (auto-created columns must still be added to types manually)visibility for hidden, access for starttime, endtimeOverride auto-created columns in Configuration/TCA/Overrides/ if needed:
<?php
// Configuration/TCA/Overrides/pages.php
// New pages are disabled by default
$GLOBALS['TCA']['pages']['columns']['disabled']['config']['default'] = 1;
Important: Auto-creation only works for
ctrlproperties in baseConfiguration/TCA/files, NOT inConfiguration/TCA/Overrides/.
<?php
// Configuration/TCA/Overrides/tt_content.php
defined('TYPO3') or die();
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTcaSelectItem(
'tt_content',
'CType',
[
'label' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:ctype.title',
'value' => 'myextension_element',
'icon' => 'content-text',
'group' => 'default',
]
);
$GLOBALS['TCA']['tt_content']['types']['myextension_element'] = [
'showitem' => '
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:general,
--palette--;;general,
header,
bodytext,
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:access,
--palette--;;hidden,
',
];
<?php
declare(strict_types=1);
namespace Vendor\Extension\Repository;
use TYPO3\CMS\Core\Database\Connection;
use TYPO3\CMS\Core\Database\ConnectionPool;
use TYPO3\CMS\Core\Database\Query\QueryBuilder;
final class CustomRepository
{
public function __construct(
private readonly ConnectionPool $connectionPool,
) {}
public function findByStatus(string $status): array
{
$queryBuilder = $this->connectionPool->getQueryBuilderForTable('tx_myext_items');
return $queryBuilder
->select('*')
->from('tx_myext_items')
->where(
$queryBuilder->expr()->eq(
'status',
$queryBuilder->createNamedParameter($status)
)
)
->orderBy('title', 'ASC')
->executeQuery()
->fetchAllAssociative();
}
public function countByPid(int $pid): int
{
$queryBuilder = $this->connectionPool->getQueryBuilderForTable('tx_myext_items');
return (int)$queryBuilder
->count('uid')
->from('tx_myext_items')
->where(
$queryBuilder->expr()->eq(
'pid',
$queryBuilder->createNamedParameter($pid, Connection::PARAM_INT)
)
)
->executeQuery()
->fetchOne();
}
}
<?php
declare(strict_types=1);
namespace Vendor\Extension\Domain\Repository;
use TYPO3\CMS\Extbase\Persistence\QueryInterface;
use TYPO3\CMS\Extbase\Persistence\Repository;
final class ItemRepository extends Repository
{
protected $defaultOrderings = [
'sorting' => QueryInterface::ORDER_ASCENDING,
];
public function findPublished(): array
{
$query = $this->createQuery();
$query->matching(
$query->logicalAnd(
$query->equals('hidden', false),
$query->lessThanOrEqual('starttime', time()),
$query->logicalOr(
$query->equals('endtime', 0),
$query->greaterThan('endtime', time())
)
)
);
return $query->execute()->toArray();
}
}
<?php
declare(strict_types=1);
namespace Vendor\Extension\Command;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;
use TYPO3\CMS\Core\Core\Bootstrap;
#[AsCommand(
name: 'myext:process',
description: 'Process items in the extension',
)]
final class ProcessCommand extends Command
{
protected function configure(): void
{
$this
->addArgument('type', InputArgument::REQUIRED, 'The type to process')
->addOption('force', 'f', InputOption::VALUE_NONE, 'Force processing');
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
$io = new SymfonyStyle($input, $output);
// Initialize backend for DataHandler operations
Bootstrap::initializeBackendAuthentication();
$type = $input->getArgument('type');
$force = $input->getOption('force');
$io->title('Processing: ' . $type);
// Your logic here...
$io->success('Processing completed successfully');
return Command::SUCCESS;
}
}
With autoconfigure: true in Services.yaml defaults, #[AsCommand] is enough — you do not need the console.command tag unless autoconfigure is disabled for that service.
# Optional — only when not using #[AsCommand] + autoconfigure
services:
Vendor\Extension\Command\ProcessCommand:
tags:
- name: console.command
<!-- phpunit.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="vendor/typo3/testing-framework/Resources/Core/Build/UnitTestsBootstrap.php"
colors="true">
<testsuites>
<testsuite name="Unit">
<directory>Tests/Unit</directory>
</testsuite>
<testsuite name="Functional">
<directory>Tests/Functional</directory>
</testsuite>
</testsuites>
</phpunit>
# .github/workflows/ci.yaml
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
typo3: ['^14.0']
php: ['8.2', '8.3', '8.4']
steps:
- uses: actions/checkout@v4
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php }}
extensions: intl, pdo_mysql
- name: Install dependencies
run: |
composer require typo3/cms-core:${{ matrix.typo3 }} --no-update
composer install --prefer-dist --no-progress
- name: Run tests
run: vendor/bin/phpunit
# 1. Create backup
ddev snapshot --name=before-upgrade
# 2. Update composer constraints
ddev composer require "typo3/cms-core:^14.0" --no-update
ddev composer update "typo3/*" --with-all-dependencies
# 3. Run upgrade wizards
ddev typo3 upgrade:list
ddev typo3 upgrade:run
# 4. Clear caches
ddev typo3 cache:flush
# 5. Register extensions and align database schema
ddev typo3 extension:setup
# Schema compare/apply (CLI entry point depends on your project: `typo3`, `vendor/bin/typo3`, typo3-console, etc.)
# `database:updateschema` is from **helhum/typo3-console**, not plain Core — omit if you only have `vendor/bin/typo3`.
ddev typo3 database:updateschema
# 6. Test thoroughly
The following changes apply exclusively to TYPO3 v14 and require manual migration. They are NOT fully covered by
ssch/typo3-rector(check your installed version; the TYPO3 14 rule set counts tens of rules and changes between releases). For automated migrations, runTypo3LevelSetList::UP_TO_TYPO3_14first, then address these manually.
Rector handles PHP-side ViewHelper declarations (UseStrictTypesInFluidViewHelpersRector), but Fluid template changes require manual review:
.html templates must match strict types (e.g., tabindex must be int, not string)._myVar) are disallowed — rename in all templates.{variable as type} casting for ambiguous ViewHelper arguments.Not covered by Rector — context-dependent migration requiring manual analysis:
$GLOBALS['TSFE'] and TypoScriptFrontendController are fully removed.// ❌ Removed in v14
$tsfe = $GLOBALS['TSFE'];
// ✅ TYPO3 v14 pattern
$pageInformation = $request->getAttribute('frontend.page.information');
$language = $request->getAttribute('language');
$typoscript = $request->getAttribute('frontend.typoscript');
Not a PHP migration — requires manual update to Configuration/Backend/Modules.php:
| Old Parent | New Parent |
|---|---|
web | content |
file | media |
tools | admin or system (Core split tools into multiple parents — map each module to its new parent in Configuration/Backend/Modules.php) |
$GLOBALS['TCA'] is read-only after boot in TYPO3 v14 — stricter than older majors. Static TCA under Configuration/TCA/ has been the supported approach since v12; extensions still mutating TCA from ext_tables.php, middleware, or event listeners must be refactored (architectural change, not a one-line replace).
switchableControllerActions: deprecated in TYPO3 v10.3 (#89463) and removed later — not a v14-only topic, but legacy FlexForm/plugins may still reference it until you split plugins.list_type subtypes / plugin list types: further tightened in v14 (#105538) — each variant needs its own configurePlugin() / registration and TypoScript/FlexForm split.Hook-to-event migration requires manual rewrite of hook implementations:
afterInitializeCurrentPage, #107518, #107528, #107568, #107569, #107343, #107380, #107382, #107388, #98239): beforeRendering, afterSubmit, initializeFormElement, beforeFormSave, beforeFormDelete, beforeFormDuplicate, beforeFormCreate, afterBuildingFinished, beforeRemoveFromParentRenderable, afterInitializeCurrentPage.BeforeFormIsSavedEvent, BeforeRenderableIsRenderedEvent).Rector removes PHP configuration (RemoveConcatenateAndCompressHandlerRector), but the infrastructure replacement is manual:
config.concatenateCss, config.compressCss, config.concatenateJs, config.compressJs must be removed (handled by Fractor, not Rector).New features to adopt (not migrations):
country (#99911) for country selection fields.itemsProcessors option (#107889) for dynamic item generation.title (and previewRenderer) in TCA types — Feature #108027 (not “arbitrary ctrl copies” per type — see changelog).<f:page.meta> — set page meta tags from Fluid templates.<f:page.title> — set page title from Fluid templates.<f:page.headerData> / <f:page.footerData> — inject raw HTML into head/footer (Feature #107056).Rector handles parser class replacement (ReplaceLocalizationParsersWithLoaders) and label syntax (MigrateLabelReferenceToDomainSyntaxRector), but these features are new:
discard command (#107519) — discard workspace changes programmatically.Verify each item in the official v14.1 changelog for your minor (entries change over time). Examples that have appeared in v14.1 discussions include default theme “Camino”, per-column content restrictions, Fluid Components tuning, and PHP 8.5 support — confirm before documenting them for a specific project.
xml:space attribute — whitespace handling respects the attribute.v14.0 (examples):
ExtensionManagementUtility::addPiFlexFormValue() (#107047) — use direct FlexForm TCA.v14.2+ examples:
ExtensionManagementUtility::addFieldsToUserSettings (#108843) — use TCA for user settings.PageRenderer->addInlineLanguageDomain() (#108963).FormEngine "additionalHiddenFields" key (#109102).