gh-netresearch-claude-code-marketplace-netresearch-skills-bundle/skills/typo3-ddev/references/quickstart.md

Quick Start Guide

This guide walks you through setting up DDEV for your TYPO3 extension using this skill.

Prerequisites Check

Before starting, verify:

# Check DDEV
ddev version
# Expected: DDEV version v1.22+

# Check Docker
docker ps
# Expected: List of containers or empty (no error)

# Check you're in a TYPO3 extension directory
ls ext_emconf.php
# Expected: ext_emconf.php file exists

Step 1: Install the Skill

cd ~/.claude/skills/
git clone https://github.com/netresearch/typo3-ddev-skill.git

Step 2: Navigate to Your Extension

cd ~/projects/my-typo3-extension

Step 3: Invoke the Skill in Claude Code

Open Claude Code and type:

Set up DDEV for this TYPO3 extension

Or use the slash command (if configured):

/typo3-ddev

Step 4: Follow the Prompts

The skill will:

1. Detect your extension:

   ✅ Found TYPO3 extension: my_ext
   

2. Extract metadata:

   Extension Key:     my_ext
   Package Name:      vendor/my-ext
   DDEV Sitename:     my-ext
   Vendor Namespace:  Vendor\MyExt
   

3. Confirm with you:

   Is this correct? (y/n)
   

4. Generate .ddev configuration files

5. Start DDEV (if you approve)

Step 5: Install TYPO3

Once DDEV is running:

# Install all versions (recommended for first time)
ddev install-all

# Or install specific version
ddev install-v13

Wait 2-5 minutes per version for installation.

Step 6: Access Your Environment

Open in your browser:

• Overview: https://my-ext.ddev.site/
• TYPO3 13 Backend: https://v13.my-ext.ddev.site/typo3/
  • Username: admin
  • Password: Password:joh316

Step 7: Start Developing

Your extension source code is in the project root. Any changes you make will immediately reflect in all TYPO3 versions because the code is bind-mounted.

Typical Development Workflow

# 1. Make changes to your extension code
vim Classes/Controller/MyController.php

# 2. Clear TYPO3 cache
ddev exec -d /var/www/html/v13 vendor/bin/typo3 cache:flush

# 3. Test in browser
# Open https://v13.my-ext.ddev.site/

# 4. Check logs if needed
ddev logs

Next Steps

Enable XDebug

ddev xdebug on
# Configure your IDE to connect to localhost:9003

Add Database Fixtures

# Import database
ddev import-db --file=fixtures/database.sql

# Export database
ddev export-db > backup.sql.gz

Run Tests

# Unit tests
ddev exec vendor/bin/phpunit Tests/Unit/

# Functional tests
ddev exec vendor/bin/phpunit Tests/Functional/

Access Database

# MySQL CLI
ddev mysql

# Or use a GUI tool:
# Host: 127.0.0.1
# Port: (run `ddev describe` to get the port)
# User: root
# Password: root

Common Tasks

Restart DDEV

ddev restart

Stop DDEV

ddev stop

Remove Environment (keeps volumes)

ddev delete

Complete Cleanup (removes everything)

ddev delete --omit-snapshot --yes
docker volume rm my-ext-v11-data my-ext-v12-data my-ext-v13-data

SSH into Container

ddev ssh
# You're now inside the container
cd /var/www/html/v13
# Do stuff
exit

Troubleshooting

Port Already in Use

# Edit .ddev/config.yaml
router_http_port: "8080"
router_https_port: "8443"

ddev restart

Installation Hangs or Fails

# Check logs
ddev logs

# Retry installation
ddev ssh
rm -rf /var/www/html/v13/*
exit
ddev install-v13

Extension Not Found

# Verify environment variables
ddev ssh
echo $EXTENSION_KEY
echo $PACKAGE_NAME

# Check Composer setup
cd /var/www/html/v13
composer show $PACKAGE_NAME

Clear Everything and Start Over

ddev delete --omit-snapshot --yes
rm -rf .ddev/
# Then re-run the skill setup

Example Project Structure

After setup, your project should look like:

my-typo3-extension/
├── .ddev/                      # DDEV configuration (generated)
│   ├── config.yaml
│   ├── docker-compose.web.yaml
│   ├── apache/
│   ├── web-build/
│   └── commands/
├── Classes/                    # Your extension PHP classes
├── Configuration/              # Your extension configuration
├── Resources/                  # Your extension resources
├── Tests/                      # Your extension tests
├── composer.json               # Your extension composer config
├── ext_emconf.php             # TYPO3 extension declaration
└── README.md                   # Your extension documentation

Tips for Extension Development

1. Use Multiple Terminals:

   • Terminal 1: Code editing
   • Terminal 2: ddev logs -f (follow logs)
   • Terminal 3: ddev ssh (run commands)

2. Cache Management:

   • Development: Clear cache frequently
   • Use ddev exec -d /var/www/html/v13 vendor/bin/typo3 cache:flush

3. Version Testing:

   • Test critical changes across all versions
   • Use ddev install-all to have all versions ready

4. Backup Important Data:

   • Export databases before major changes
   • Use ddev export-db --gzip=false > backup.sql

5. Keep DDEV Updated:

   ddev version  # Check current version
   # Update via your package manager (brew, apt, etc.)
   

---

Happy TYPO3 Extension Development! 🚀