hda/t3up

T3UP - Basic Installation

13.1.21 2025-10-08 07:49 UTC

Requires

• scssphp/scssphp: ^1
• typo3/cms-core: ^13.4-
• wapplersystems/ws-scss: ^13.0.2

GPL-2.0-or-later

• Michael Lang

• extension
• t3up

README

Changelog

• 2025-08-01

  • t3up-table, t3up-onepager und t3up-image sind integriert.
  • Google Icons — Material Symbols ersetzt Font Awesome. Varianten: filled / outline. Klassenbeispiele: .symbol, .symbol-outline.
  • Social-Media-Elemente nutzen .brands und verwenden FFFontawesome Brands.

• 2025-08-21

  • Material im RTE integriert.
  • Symbolic link for fonts added (see Commands).

• 2025-08-25

  • In the public/ folder there should be a symlink to ../vendor/hda/t3up/Resources/Public/Fonts.

• 2025-10-01

  • New fonts inside Merriweather Sans and Merriweather.

Commands

This extension provides two console commands to help with local setup and debugging.

1) Create Fonts Symlink

Creates a symlink public/Fonts → vendor/hda/t3up/Resources/Public/Fonts.

• Command name: t3up:symlink:fonts
• Alias: t:s:f
• Description: Create a symlink in public/ that points to vendor/hda/t3up/Resources/Public/Fonts.
• Behavior:
  • Verifies that the target folder exists.
  • If public/Fonts is an existing symlink it will be removed and recreated.
  • If public/Fonts is a real file/directory the command refuses to overwrite and asks for manual removal (to avoid accidental data loss).
• Usage (from project root):

  vendor/bin/typo3 t3up:symlink:fonts
  

  or alias

  vendor/bin/typo3 t3up:s:f
  

2) Debug Container Command

Lists services from the DI container, optionally filtered by a string.

• Command name: t3up:debug:container
• Alias: t3up:d:c
• Argument: optional filter (string) — filters service ids (case insensitive).

Usage

  # list all services
  vendor/bin/typo3 t3up:debug:container

  # filtered (e.g. match "Repository")
  vendor/bin/typo3 t3up:debug:container Repository

  # using alias
  vendor/bin/typo3 t3up:d:c Repository

3) Update TypoScript Constants (main command)

Command name: t3up:update:constants

Description: Apply predefined TypoScript constant presets to sys_template (modes: default | up | imp).

This command (Hda\T3up\Command\UpdateTypoScriptConstantsCommand) is designed to automatically apply or update TypoScript constant presets in sys_template.constants.

Purpose

• Programmatically apply groups of TypoScript constant key/value pairs (presets) to TYPO3 sys_template.constants.
• A quick way to switch site presets (colors, header/footer wrappers, top bar config, social links, components, site config flags, and more).

High-level behavior

• Presets are grouped by category (e.g., color, fonts, footer, header, socialmedia, etc.).
• Each category can provide up to three arrays:
  • PRESET_<CAT>_DEFAULT
  • PRESET_<CAT>_UP
  • PRESET_<CAT>_IMP
• Final key/value pairs are built according to the selected mode:
  • default: PRESET_*_DEFAULT only.
  • up: PRESET_*_DEFAULT + PRESET_*_UP (keys in UP override DEFAULT).
  • imp: PRESET_*_DEFAULT + PRESET_*_IMP (keys in IMP override DEFAULT).
• For each selected sys_template record:
  • Existing keys in constants are replaced (line-based regex).
  • Keys absent in the template are inserted only if --force is used; otherwise, they are reported as skipped.
  • A line-level diff preview (old → new) is printed before any DB write.
  • --dry-run shows the preview but does not write to the database.

Merge precedence (important)

• Implementation uses array_merge($pairs, $defaultConst, $upConst), etc.
• In PHP, array_merge with associative keys means later arrays override earlier ones: array_merge($a, $b, $c) means keys in $c override $b and $a when identical.
• Therefore, in --mode up, the UP values win for colliding keys; in --mode imp, the IMP values win.

Alias

    vendor/bin/typo3 t3up:u:c

Options & usage (copyable)

    vendor/bin/typo3 t3up:update:constants [--uid=<UID>...] [--category=<cat>...] [--mode=<default|up|imp>] [--dry-run] [--force]

• --uid (optional, repeatable) — UID(s) of sys_template records to update. If omitted, templates with root = 1 are targeted.
  • Update a single template by UID:

      vendor/bin/typo3 t3up:update:constants --uid 2 --mode up
    

  • Update multiple templates:

      vendor/bin/typo3 t3up:update:constants --uid 2 --uid 3 --mode up
    

• --category, -c (optional, repeatable) — Which preset categories to apply. If omitted, all categories are applied.
  • Only apply color and header presets:

      vendor/bin/typo3 t3up:update:constants -c color -c header --mode imp
    

• --mode, -m (optional) — default | up | imp. Default is default.

    vendor/bin/typo3 t3up:update:constants --mode up
  

• --dry-run, -dr — Show preview only; do not write to the DB.

    vendor/bin/typo3 t3up:update:constants --mode up --dry-run
  

• --force, -f — Insert keys that do not exist in the template (otherwise, missing keys are skipped and reported).

    vendor/bin/typo3 t3up:update:constants --mode imp --force
  

Full multi-example (copyable)

1. Preview all categories in UP mode for root template(s):

   vendor/bin/typo3 t3up:update:constants --mode up --dry-run
   

2. Apply color + fonts for template UID 10, insert missing keys:

   vendor/bin/typo3 t3up:update:constants --uid 10 --category color --category fonts --mode up --force
   

3. Apply IMP presets for multiple templates:

   vendor/bin/typo3 t3up:update:constants --uid 2 --uid 3 --mode imp
   

Categories (valid values for --category)

color, typography, fonts, footer, header, navigation, top, totop, socialmedia, breadcrumb, components, design, config, plugins, styles

Implementation details (what gets changed)

• Reads the constants field from selected sys_template rows.
• For each preset key, it looks for a line matching ^(\s*KEY\s*=\s*)(.*)$ and replaces that whole line with KEY = value.
• If the key is missing:
  • With --force, the key/value is appended to the end of the constants string.
  • Without --force, the key is added to skipped and reported.
• A diff preview is shown; the new constants string is written back only when not in --dry-run.

Safety & best-practices

• Always run a dry-run first:

    vendor/bin/typo3 t3up:update:constants --mode up --dry-run
  

• Backup sys_template (or the whole DB) before writing:
  • Example: Dump sys_template table (adjust for your DB)

    mysqldump -u dbuser -p dbname sys_template > /tmp/sys_template.sql
    

• Inspect the printed diff before confirming.
• Use --force only if you are certain the inserted keys are intended.
• To revert, restore from your DB backup.

4) Content Spacing Update

• Command name: t3up:update:spacing

• Description:

Ersetzt alte px-Abstände (wie 16px, 8px usw.) in den Feldern space_before_class, space_after_class, padding_before_class und padding_after_class durch numerische Klassen, basierend auf einem festgelegten Mapping.

• Usage:

    vendor/bin/typo3 t3up:update:spacing

• Alias:

    vendor/bin/typo3 t3up:u:s

• Mapping:

• 16px / 20px → 6

• 12px → 5

• 8px → 3

• (Das vollständige Mapping ist in der Extension definiert.)

5) Set Owner & Permissions (rekursiv)

• Command name: t3up:set:owner-perms

• Description:

Setzt owner/group www-data und sinnvolle Rechte rekursiv. Standard: Dry‑run — zeigt an, was passieren würde. Mit --force werden Änderungen ausgeführt.

• Options:

• --path: Zielpfad (default: Projektroot)

• --force, -f: Änderungen anwenden

• --skip-errors: Fehler sammeln und weitermachen (nicht abbrechen)

• Usage:

  # Dry-run
  vendor/bin/typo3 t3up:set:owner-perms
  

  # Apply on project root
  vendor/bin/typo3 t3up:set:owner-perms --force
  

  # Apply on custom path and continue on errors
  vendor/bin/typo3 t3up:set:owner-perms --force --path=/var/www/html/site --skip-errors
  

• Verhaltensdetails:

• Directories: 0755

• Files: 0644 (ausführbare Dateien behalten 0755)

• Owner/Group: www-data (chown/chgrp)

• Warnung: chown/chgrp funktionieren nur mit entsprechenden Rechten — auf Shared-Hosting oft nicht verfügbar.

6) Convert List Type

# Trockenlauf (zeigt nur, was passieren würde)
vendor/bin/typo3 t3up:convert:listtypes --dry-run

# Tatsächliches Ausführen (wendet Änderungen an)
vendor/bin/typo3 t3up:convert:listtypes

Option

--dry-run

Zeigt die Anzahl gefundener Einträge und die geplanten Änderungen, führt aber keine Updates aus.

Wo die Mappings stehen

Die Mappings werden in der Klasse selbst definiert in der Konstante C_TYPE_AND_LIST_TYPE_MAPPINGS. Struktur (vereinfachtes Beispiel):

private const C_TYPE_AND_LIST_TYPE_MAPPINGS = [
    [
        'CType' => ['buttons' => 'hda_buttonbox'],
        'list_type' => [],                // nur CType
    ],
    [
        'CType' => ['list' => 'news_newsliststicky'],
        'list_type' => ['news_pi1' => 'news_pi1'], // CType × list_type kombiniert
    ],
];

7) Run helper commands to update project to TYPO3 v13.

• Command name: t3up:update:to13

• Alias: t3up:u:13

• Description:

Führt alle oben gelisteten Commands sequenziell aus. Runs: symlink:fonts, update:constants, adjust-colpos, update-spacing, set:owner-perms in dieser Reihenfolge.

• Options:

• --force, -s

• --dry-run, -d

• --path, -p: weitergeleitet zu t3up:set:owner-perms

• --continue-on-error, -c: continue even if a step fails

• Usage:

  Dry-run owner perms

  vendor/bin/typo3 t3up:update:to13 --dry-run
  

  use force

  vendor/bin/typo3 t3up:update:to13 --force
  

  force and pass path

  vendor/bin/typo3 t3up:update:to13 --force --path=/var/www/html/site
  

t3up:convert:layouts

Was es macht Dieser Symfony/TYPO3-Console-Command durchsucht die Tabelle pages in den Spalten backend_layout und backend_layout_next_level nach Einträgen der Form pagets und ersetzt sie gemäß vordefinierter Mappings durch pagets. Der Command zählt zuerst die betroffenen Zeilen, schreibt die geplanten Änderungen in die Konsole und führt anschließend (oder im Dry-Run nur simuliert) die Updates aus.

Features

Prüft beide Spalten: backend_layout und backend_layout_next_level.

Zeigt Anzahl gefundener und aktualisierter Zeilen an.

Unterstützt --dry-run (zeigt, was geändert würde, ohne die DB zu verändern).

Fängt Fehler beim Update ab und gibt Fehlermeldungen in die Konsole.

Mappings

Quelle (alt) Ziel (neu)

pagets__RightMarginalLayout     ->	pagets__RightMarginal
pagets__OneColumnLayout         ->	pagets__OneColumn
pagets__StandardLayout          ->	pagets__Standard
pagets__RightNavigationLayout   ->	pagets__RightNavigation
pagets__LeftNavigationLayout    ->	pagets__LeftNavigation
pagets__OnePagerLayout          ->	pagets__OnePager
pagets__DefaultLayout           ->	pagets__Default

Dry-Run (Nur Anzeige, keine Änderungen):

vendor/bin/typo3 t3up:convert:layouts --dry-run

Tatsächliches Ausführen (Änderungen werden geschrieben):

vendor/bin/typo3 t3up:convert:layouts