name: typo3-ddev
description: Best practices for TYPO3 local development with DDEV, including configuration, database management, multi-version testing, and common workflows for v13/v14.
version: 2.1.0
typo3_compatibility: "13.0 - 14.x"
triggers:
- ddev
- local
- development
- docker
- environment
- multi-version

TYPO3 DDEV Local Development

Compatibility: TYPO3 v13.x and v14.x (v14 preferred)
All configurations in this skill support both TYPO3 v13 and v14.

Container Priority

Always check for existing containers first:

1. Check .ddev/ exists → use ddev exec
2. Check docker-compose.yml exists → use docker compose exec
3. Only use system tools if no container environment

Critical: Use the project's configured PHP version, not system PHP.

1. Project Initialization

New TYPO3 Project (v14 - Preferred)

# Create project directory
mkdir my-typo3-project && cd my-typo3-project

# Initialize DDEV with TYPO3 preset
ddev config --project-type=typo3 --docroot=public --php-version=8.3

# Start the environment
ddev start

# Install TYPO3 v14 (preferred)
ddev composer create "typo3/cms-base-distribution:^14"

# Run TYPO3 setup
ddev typo3 setup

New TYPO3 Project (v13 LTS)

# Create project directory
mkdir my-typo3-project && cd my-typo3-project

# Initialize DDEV with TYPO3 preset
ddev config --project-type=typo3 --docroot=public --php-version=8.2

# Start the environment
ddev start

# Install TYPO3 v13 LTS
ddev composer create "typo3/cms-base-distribution:^13"

# Run TYPO3 setup
ddev typo3 setup

Existing TYPO3 Project

# Clone repository
git clone [email protected]:org/project.git
cd project

# Configure DDEV (if not already)
ddev config --project-type=typo3 --docroot=public --php-version=8.3

# Start and install dependencies
ddev start
ddev composer install

# Import database (see Database Operations)

2. Recommended Configuration

.ddev/config.yaml (v13/v14 Compatible)

name: my-typo3-project
type: typo3
docroot: public
php_version: "8.3"    # 8.2 minimum for v13, 8.3 recommended for v14
webserver_type: nginx-fpm
database:
  type: mariadb
  version: "10.11"    # 10.11+ or 11.x recommended for both v13/v14

# Fixed port for external tools (MySQL MCP, etc.)
host_db_port: "33060"
host_webserver_port: "8080"
host_https_port: "8443"

# Enable Mailpit for email testing (replaced Mailhog in newer DDEV)
mailpit_http_port: "8025"

# PHP settings
web_environment:
  - TYPO3_CONTEXT=Development
  - PHP_IDE_CONFIG=serverName=my-typo3-project.ddev.site

# Additional services
hooks:
  post-start:
    - exec: composer install --no-interaction

.ddev/config.local.yaml (Personal Overrides)

# Personal machine-specific overrides (gitignored)
host_db_port: "33061"  # If 33060 conflicts

PHP Version Matrix

3. Database Operations

Import Database

# From SQL file
ddev import-db --file=dump.sql

# From gzipped file
ddev import-db --file=dump.sql.gz

# From remote (via SSH)
ssh user@server "mysqldump -u root dbname | gzip" | gunzip | ddev import-db

Export Database

# Standard export
ddev export-db --file=backup.sql.gz

# Without gzip
ddev export-db --gzip=false --file=backup.sql

Database Snapshots

# Create snapshot before risky operation
ddev snapshot --name=before-upgrade

# List snapshots
ddev snapshot --list

# Restore snapshot
ddev snapshot restore before-upgrade

# Delete snapshot
ddev snapshot delete before-upgrade

Direct MySQL Access

# MySQL CLI
ddev mysql

# Execute query
ddev mysql -e "SELECT uid, title FROM pages WHERE hidden = 0"

# Connect from external tool (e.g., TablePlus, DBeaver)
# Host: 127.0.0.1
# Port: 33060 (or your configured host_db_port)
# User: db
# Password: db
# Database: db

4. TYPO3 CLI Commands

Console Commands

# List all commands
ddev typo3 list

# Clear all caches
ddev typo3 cache:flush

# Clear specific cache
ddev typo3 cache:flush --group=pages

# Update database schema
ddev typo3 database:updateschema

# Reference index
ddev typo3 referenceindex:update

# Scheduled tasks
ddev typo3 scheduler:run

# Run upgrade wizards (after version update)
ddev typo3 upgrade:list
ddev typo3 upgrade:run

Extension Management

# Install extension from TER
ddev composer require typo3/cms-seo

# Install extension from Packagist
ddev composer require vendor/extension-name

# Setup extensions (generate PackageStates.php)
ddev typo3 extension:setup

# Activate extension
ddev typo3 extension:activate my_extension

# Deactivate extension
ddev typo3 extension:deactivate my_extension

5. Composer Operations

# Install dependencies
ddev composer install

# Update all dependencies
ddev composer update

# Update single package
ddev composer update typo3/cms-core --with-dependencies

# Require new package (with v13/v14 dual compatibility)
ddev composer require "vendor/package:^1.0"

# Remove package
ddev composer remove vendor/package

# Clear Composer cache
ddev composer clear-cache

Dual-Version Development

For extensions supporting both v13 and v14:

# Set version constraint in extension's composer.json
ddev composer require "typo3/cms-core:^13.0 || ^14.0" --no-update

6. File Operations

SSH into Container

# Web container (as www-data)
ddev ssh

# Web container (as root)
ddev ssh -s web -u root

# Database container
ddev ssh -s db

File Sync

# Copy file into container
ddev exec cp /path/in/container /other/path

# Copy from host to container
docker cp localfile.txt ddev-myproject-web:/var/www/html/

# Download file from container
ddev exec cat /var/www/html/somefile > localfile

7. Debugging with Xdebug

Enable/Disable

# Enable Xdebug
ddev xdebug on

# Disable Xdebug (faster performance)
ddev xdebug off

# Check status
ddev xdebug status

IDE Configuration (PhpStorm/Cursor)

1. Set breakpoint in PHP file
2. Start listening for connections (PhpStorm: "Start Listening")
3. Enable Xdebug: ddev xdebug on
4. Trigger request in browser
5. Debugger should connect

Xdebug Environment

# .ddev/config.yaml
web_environment:
  - XDEBUG_MODE=debug,develop
  - XDEBUG_CONFIG=client_host=host.docker.internal

8. Multi-Site Configuration

Additional Hostnames

# .ddev/config.yaml
additional_hostnames:
  - site1
  - site2
additional_fqdns:
  - site1.myproject.ddev.site
  - site2.myproject.ddev.site

Site Configuration

# Create site configuration
mkdir -p config/sites/site1

# config/sites/site1/config.yaml
base: 'https://site1.myproject.ddev.site/'
rootPageId: 1
languages:
  - title: English
    languageId: 0
    locale: en_US.UTF-8

9. Services and Add-ons

Common Add-ons

# Redis (for caching)
ddev get ddev/ddev-redis

# Elasticsearch
ddev get ddev/ddev-elasticsearch

# Solr
ddev get ddev/ddev-solr

Custom Services

# .ddev/docker-compose.redis.yaml
services:
  redis:
    image: redis:7-alpine
    container_name: ddev-${DDEV_SITENAME}-redis
    command: redis-server --appendonly yes
    volumes:
      - redis-data:/data
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT

volumes:
  redis-data:

Redis Caching Configuration (v13/v14)

<?php
// config/system/additional.php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['hash']['backend'] 
    = \TYPO3\CMS\Core\Cache\Backend\RedisBackend::class;
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['hash']['options'] = [
    'hostname' => 'redis',
    'port' => 6379,
    'database' => 0,
];

10. Troubleshooting

Common Issues

# Restart everything
ddev restart

# Full reset (keeps database)
ddev stop && ddev start

# Nuclear option (removes containers **and database volume**)
ddev delete -O && ddev start

# View logs
ddev logs

# View specific service logs
ddev logs -s web
ddev logs -s db

Port Conflicts

# Check what's using a port
lsof -i :80

# Use different ports in config.yaml
router_http_port: "8080"
router_https_port: "8443"

Permission Issues

# Fix file permissions
ddev exec chmod -R g+w var/
ddev exec chmod -R g+w public/fileadmin/
ddev exec chmod -R g+w public/typo3temp/

11. Environment Variables

TYPO3 Context

# Development (default in DDEV)
TYPO3_CONTEXT=Development

# Production testing
TYPO3_CONTEXT=Production

# Sub-contexts
TYPO3_CONTEXT=Development/Docker

Custom Variables

# .ddev/config.yaml
web_environment:
  - MY_API_KEY=secret123
  - FEATURE_FLAG=enabled

Access in TYPO3:

<?php
$apiKey = getenv('MY_API_KEY');
// or
$apiKey = $_ENV['MY_API_KEY'];

12. Best Practices

Performance

1. Disable Xdebug when not debugging (ddev xdebug off)
2. Use snapshots instead of full imports for quick state changes
3. Mount with Mutagen on macOS for better file sync performance
4. Use PHP 8.3 for best performance on v13/v14

Team Workflow

1. Commit .ddev/config.yaml to repository
2. Gitignore .ddev/config.local.yaml for personal overrides
3. Document additional setup steps in README.md
4. Share database snapshots for consistent development data

Security

1. Never expose DDEV ports publicly
2. Don't use DDEV in production
3. Rotate any sensitive data in development databases

13. Multi-Version Testing (Extension Development)

When developing extensions that need to work across multiple TYPO3 versions:

Setup for Multi-Version Testing

# .ddev/config.yaml
name: my-extension
type: php
docroot: ""
php_version: "8.3"

additional_hostnames:
  - v13
  - v14

Install Multiple TYPO3 Versions

# Create version-specific directories
mkdir -p v13 v14

# Install TYPO3 v13
cd v13
ddev composer create "typo3/cms-base-distribution:^13"
cd ..

# Install TYPO3 v14
cd v14
ddev composer create "typo3/cms-base-distribution:^14"
cd ..

# Symlink extension
ln -s ../../../ v13/packages/my_extension
ln -s ../../../ v14/packages/my_extension

Access URLs

Default Credentials: admin / Joh316!

Version-Specific Commands

# Run tests on v13
ddev exec -d /var/www/html/v13 vendor/bin/phpunit

# Run tests on v14
ddev exec -d /var/www/html/v14 vendor/bin/phpunit

# Clear cache for specific version
ddev exec -d /var/www/html/v13 vendor/bin/typo3 cache:flush

Credits & Attribution

This skill is based on the excellent TYPO3 best practices and methodology developed by
Netresearch DTT GmbH.

Original repository: https://github.com/netresearch/typo3-ddev-skill

Copyright (c) Netresearch DTT GmbH - Methodology and best practices
Adapted by webconsulting.at for this skill collection