Updat TYPO3 13/14

1. 1Eight-phase migration procedure spanning backups, DDEV configuration (PHP 8.2+), extension relocation, and final testing.
2. 2Ready-to-use rector.php configuration targeting PHP 8.2 and TYPO3 v13 rule sets for automated refactoring.
3. 3Architectural shifts towards Content Blocks and complete removal of TCA definitions from ext_tables.php.
4. 4Modernisation of Doctrine DBAL queries using executeQuery() and executeStatement(), plus TypoScript file renaming.
5. 5Security header migration into TypoScript alongside cleanup of legacy configuration files.

# TYPO3 v13 Upgrade & v14 Preparation Plan

This document outlines the comprehensive procedure to upgrade the project directly to **TYPO3 v13 LTS**, restructure the architecture, and apply "deep dive" improvements to prepare for **TYPO3 v14**.

## Phase 1: Environment & Database Preparation

- [ ] **Backup Project:**
    - [ ] Create a full backup of the database: `ddev export-db --file=db-backup-pre-migration.sql.gz`.
    - [ ] Create a backup of `public/fileadmin`.
    - [ ] Create a backup of `composer.json` and `composer.lock`.
- [ ] **Update DDEV Configuration (v13 Requirements):**
    - [ ] Update `.ddev/config.yaml` to set **PHP 8.2** (or 8.3 recommended).
    - [ ] Run `ddev config --database=mariadb:10.4` (or higher, e.g., 10.11).
    - [ ] Run `ddev restart`.
- [ ] **Prepare Migration Tools:**
    - [ ] Clone the migration repository: `git clone https://github.com/toumoro/tm_migration tools/tm_migration`.
    - [ ] Ensure `typo3-rector` is updated to the latest version supporting v13 rules.

## Phase 2: Architecture & Extension Restructuring

- [ ] **Create Extension Directory:** Ensure `app/extensions` exists.
- [ ] **Migrate Local Extensions:**
    - [ ] Move local extensions (e.g., `theme`, `omb_form`) from `app/packages/` (or similar) to `app/extensions/`.
- [ ] **Theme Extension Configuration:**
    - [ ] Verify `app/extensions/theme/composer.json` has valid PSR-4 autoloading.
- [ ] **Main Composer Configuration:**
    - [ ] Edit root `composer.json`.
    - [ ] Update "repositories" to: `{"type": "path", "url": "app/extensions/*"}`.
    - [ ] **Remove** the `"scripts"` section entirely.
    - [ ] Update requirements:
        - [ ] `php`: `^8.2`
        - [ ] `typo3/cms-*`: `^13.4`
        - [ ] `b13/container`: `^3.0` (or compatible v13 version)
        - [ ] `apache-solr-for-typo3/solr`: `^13.0`
    - [ ] Run `ddev composer update --with-all-dependencies`.

## Phase 3: TYPO3 v13 Deep Dive Improvements

- [ ] **Strict TCA Migration:**
    - [ ] **Remove** all `ext_tables.php` usage for TCA definitions.
    - [ ] Move table definitions to `Configuration/TCA/<TableName>.php`.
    - [ ] Move table overrides to `Configuration/TCA/Overrides/<TableName>.php`.
- [ ] **Strict Types in Extbase:**
    - [ ] Add `declare(strict_types=1);` to all custom Controller and Model classes.
    - [ ] Ensure Controller actions have return type hints (e.g., `: ResponseInterface`).
- [ ] **Content Blocks Modernization:**
    - [ ] Evaluate replacing legacy "Plugins" or `mask` elements with the **Content Blocks** standard (native in v14).
    - [ ] Define blocks in `ContentBlocks/<Vendor>/<BlockName>/`.

## Phase 4: Automated Code Migration (Rector v13)

- [ ] **Configure Rector:** Create `rector.php` using the configuration provided below (Targeting TYPO3 13 & PHP 8.2).
- [ ] **Run Dry Run:** `ddev exec vendor/bin/rector process app/extensions --dry-run`.
- [ ] **Run Migration:** `ddev exec vendor/bin/rector process app/extensions`.
- [ ] **Manual Fixes:**
    - [ ] Replace `$_EXTKEY` in config files with string literals.
    - [ ] Replace `$GLOBALS['TSFE']` calls with Context API or Request Attributes.

## Phase 5: File Renaming & TypoScript Refactoring

- [ ] **Rename TSConfig:**
    - [ ] `*.ts` -> `*.tsconfig` in `Configuration/TsConfig/`.
    - [ ] Update references in `ext_localconf.php`.
- [ ] **Rename TypoScript:**
    - [ ] `*.ts` -> `*.typoscript` in `Configuration/TypoScript/`.
    - [ ] Update references in `@import` and `ext_localconf.php`.

## Phase 6: Security Headers & Server Config

- [ ] **TypoScript Security:**
    - [ ] Create `app/extensions/theme/Configuration/TypoScript/Static/Page/securityheaders.typoscript`.
    - [ ] Add `config.additionalHeaders` (CSP, HSTS, X-Frame-Options).
- [ ] **Update .htaccess:**
    - [ ] Replace `app/web/.htaccess` with the official TYPO3 v13 version.
    - [ ] Remove old security headers from `.htaccess` (now in TypoScript).

## Phase 7: Configuration Cleanup

- [ ] **Settings & Context:**
    - [ ] Update `app/web/typo3conf/settings.php` for Context handling.
    - [ ] Refactor/Clean `app/web/typo3conf/AdditionalConfiguration.php`.
    - [ ] **Remove** `app/web/typo3conf/ext/AdditionalConfiguration*`.

## Phase 8: Final Verification

- [ ] **Database Upgrades:** `ddev typo3 database:updateschema` and `ddev typo3 upgrade:run`.
- [ ] **Functional Testing:** Verify Frontend, Backend, Solr search, and SUPI extension.

---

## Rector Configuration for TYPO3 13

Save this content as `rector.php` in your project root.

```php
<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\TypeDeclaration\Rector\ClassMethod\AddVoidReturnTypeWhereNoReturnRector;
use Rector\ValueObject\PhpVersion;
use Ssch\TYPO3Rector\Set\Typo3SetList;
use Ssch\TYPO3Rector\Set\Typo3LevelSetList;

return static function (RectorConfig $rectorConfig): void {
    // 1. Target PHP 8.2 (Required for TYPO3 v13)
    $rectorConfig->phpVersion(PhpVersion::PHP_82);

    // 2. Paths to scan
    $rectorConfig->paths([
        __DIR__ . '/app/extensions',
    ]);

    // 3. Skip folders that shouldn't be touched
    $rectorConfig->skip([
        __DIR__ . '/app/extensions/**/Resources/*',
        __DIR__ . '/app/extensions/**/Documentation/*',
        __DIR__ . '/vendor/*',
        __DIR__ . '/var/*',
    ]);

    // 4. Define Sets
    $rectorConfig->sets([
        // TYPO3 v13 Specifics
        Typo3SetList::TYPO3_13,
        Typo3LevelSetList::UP_TO_TYPO3_13,
        
        // Content Blocks / TCA Migrations (Crucial for v13/v14)
        Typo3SetList::TCA_130, 
        
        // PHP Upgrades (Auto-upgrade code to 8.2 syntax like Readonly classes, Enums, etc.)
        \Rector\Set\ValueObject\LevelSetList::UP_TO_PHP_82,
        
        // Code Quality & Dead Code
        \Rector\Set\ValueObject\SetList::CODE_QUALITY,
        \Rector\Set\ValueObject\SetList::DEAD_CODE,
        \Rector\Set\ValueObject\SetList::TYPE_DECLARATION,
    ]);

    // 5. Future Proofing (v14 Preparation)
    // TYPO3 v14 will enforce strict types heavily.
    $rectorConfig->rule(AddVoidReturnTypeWhereNoReturnRector::class);
};

```
# TYPO3 v13 Deep Dive & v14 Readiness Guide

This section details the architectural shifts required for v13 and the strategic moves to prepare for **TYPO3 v14** (scheduled for 2025/2026).

## 1. Architectural Shift: Content Blocks

TYPO3 v13 and v14 are moving away from the traditional "Plugin" (`registerPlugin`) concept for simple content elements. The new standard is **Content Blocks**.

* **The Shift:** Instead of using `mask` or manual Fluid Styled Content (FSC) configurations, use the **Content Blocks** standard (native in v14, available as an extension in v13).
* **Actionable Task:**
    * Do not create new "Plugins" for simple text/image elements.
    * Convert existing simple plugins into Content Blocks defined via YAML/JSON manifests.
    * **Location:** `app/extensions/theme/ContentBlocks/` (structure may vary based on exact Content Blocks version used).

## 2. Strict TCA Enforcement

TYPO3 v13 removes the fallback logic that allowed TCA definitions in `ext_tables.php`.

* **The Rule:** `ext_tables.php` is **strictly** for module registration and table access permission setup. It must **never** contain `$GLOBALS['TCA']` arrays.
* **Actionable Task:**
    * **Move** all table definitions to `Configuration/TCA/<TableName>.php`.
    * **Move** all field overrides (e.g., adding fields to `pages` or `tt_content`) to `Configuration/TCA/Overrides/<TableName>.php`.
    * Ensure strict types are used in these PHP files.

## 3. Doctrine DBAL Strictness

TYPO3 v13 adopts a newer version of Doctrine DBAL, removing deprecated shortcuts.

* **The Change:** Methods like `$queryBuilder->execute()` are removed.
* **Actionable Task:**
    * Refactor all `SELECT` queries to use `$queryBuilder->executeQuery()`.
    * Refactor all `INSERT/UPDATE/DELETE` queries to use `$queryBuilder->executeStatement()`.
    * Review all custom repositories for raw SQL usage and convert to QueryBuilder methods where possible.

## 4. Outlook: Preparing for TYPO3 v14

To ensure the project is "future-proof" immediately, implement these v14-ready practices now:

### A. Fluid 5 & Strict Typing
* **Context:** v14 will introduce Fluid 5, which handles types much more strictly.
* **Preparation:**
    * Add type hints to all arguments in custom ViewHelpers.
    * Rename all template files to standard extensions (e.g., `.html`), avoiding legacy naming like `.txt`.

### B. Modern Image Handling
* **Context:** v14 moves towards "Configurable Image Conversion," dropping hardcoded dependence on ImageMagick's legacy handling.
* **Preparation:**
    * Configure the global site settings to prefer modern formats: `webp` and `avif`.
    * Verify that `localconf` settings do not force specific legacy image processors.

### C. Backend Module Structure
* **Context:** Module names and structures are being standardized.
* **Preparation:**
    * Update internal editor documentation to reflect upcoming terminology changes:
        * "Web" module -> **"Content"**
        * "Filelist" module -> **"Media"**
    * Centralize any custom "webhook" logic into the new System **Integrations** module logic if applicable.

• GitHub: tm_migrationgithub.com/toumoro/tm_migration