hda/t3up

T3UP - Basic Installation

13.1.15 2025-09-25 12:39 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.

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