typo3-update

TYPO3 v14 開発

ソース：https://github.com/dirnbauer/webconsulting-skills

方針： このコレクションは TYPO3 v14.x のみを対象としています。ここで紹介するパターンは、v14 のコードベースを前提としています。 古いメジャーバージョンから移行する場合は、まず typo3-rector、typo3-extension-upgrade、Fractor、公式アップグレードガイドを使用してください。

TYPO3 API を優先： カスタム実装を作成する前に、必ず TYPO3 の組み込み API、コア機能、確立された規約を使用してください。TYPO3 がすでに提供しているものを再実装しないでください。使用する API やメソッドが TYPO3 v14 に存在し、非推奨になっていないことを、公式 TYPO3 ドキュメントで必ず確認してください。

1. バージョン方針

対象：TYPO3 v14.x のみ

バージョン	このコレクションでの位置づけ
v14.x	サポート対象 — 例と制約は TYPO3 v14 を前提としています
それ以前のメジャーバージョン	対象外 — コアのアップグレードを完了してから、これらのパターンを使用してください

ベストプラクティス： 新規開発では、composer.json と ext_emconf.php に TYPO3 v14 のみを対象とする制約を宣言してください。

バージョン制約

<?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-blocks では typo3/cms-core ^14.3 以上が必要になる場合があります（現行の 2.4.5 では ^14.3 が必要です）。^14.0 のみに固定する前に、Packagist の制約を確認してください。

2. PHP 要件

最低 PHP バージョン：8.2

TYPO3 v14 には PHP 8.2 以上が必要です。最新の PHP 機能を使用してください。

<?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';
}

3. コントローラーパターン（TYPO3 v14）

Extbase アクションコントローラー

<?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');
    }
}

4. ビューとテンプレート（TYPO3 v14）

ViewFactory（推奨パターン）

<?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');
    }
}

Fluid テンプレートのベストプラクティス

<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">
        
        <h1>{item.title}</h1>
        
        
        <f:format.html>{item.bodytext}</f:format.html>
        
        
        <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>
        
        
        <f:link.action action="show" arguments="{item: item.uid}">
            View Details
        </f:link.action>
    </div>
</f:section>

</html>

5. イベントシステム（TYPO3 v14）

PSR-14 イベントリスナー

PSR-14 イベントは TYPO3 v14 の標準です。フックよりも常にイベントを優先してください。

<?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
        }
    }
}

一般的なイベント（TYPO3 v14）

イベント	用途
ModifyPageLinkConfigurationEvent	リンク生成を変更します
ModifyCacheLifetimeForPageEvent	ページキャッシュを調整します
BeforeStdWrapFunctionsInitializedEvent	stdWrap を変更します
(DataHandler)	コアには汎用的な BeforeRecordOperationEvent／AfterRecordOperationEvent はありません。SC_OPTIONS の DataHandler フック、またはドキュメントに記載された TYPO3\CMS\Core\DataHandling\Event\* のみを使用してください（一覧）

Services.yaml の登録

# 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'

詳細リファレンス

詳細な例、長いテンプレート、トラブルシューティングの一覧表、付録、または上記に含まれていないセクションが必要な場合は、完全版ガイドをお読みください。限定的なタスクでは、このファイルを読み込まないようにして、スキルが段階的な情報開示に従うようにしてください。