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:
Check .ddev/ exists → use ddev exec Check docker-compose.yml exists → use docker compose exec Only use system tools if no container environment
Critical: Use the project's configured PHP version, not system PHP.
- 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 git@github.com: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)
- 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 TYPO3 Version Minimum PHP Recommended PHP MariaDB v13.4 LTS 8.2 8.3 10.11+ v14.x 8.2 8.3 / 8.4 10.11+ 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
- 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
- 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
- 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
- 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) Set breakpoint in PHP file Start listening for connections (PhpStorm: "Start Listening") Enable Xdebug: ddev xdebug on Trigger request in browser Debugger should connect Xdebug Environment
.ddev/config.yaml
web_environment: - XDEBUG_MODE=debug,develop - XDEBUG_CONFIG=client_host=host.docker.internal
- 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
- 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)
'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: