zhongwei/gh-netresearch-claude-code-marketplace-netresearch-skills-bundle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f6d4a68978a408e227d18a5ec3a0f7015c5e1c77
gh-netresearch-claude-code-…/skills/typo3-ddev/references/advanced-options.md
Zhongwei Li f6d4a68978 Initial commit
2025-11-30 08:43:13 +08:00

8.0 KiB
Raw Blame History

Advanced Options

Custom PHP Version

If extension requires different PHP version:

# In .ddev/config.yaml
php_version: "8.1"  # or "8.3"

Database Selection (Tiered Approach)

The skill uses intelligent database selection based on extension complexity.

🎯 Tier 1: SQLite (Simple Extensions - Development Optimized)

Recommended for:

  • ✅ Extensions using only TYPO3 Core APIs (Extbase, FAL, DataHandler)
  • ✅ No custom database tables (ext_tables.sql absent/empty)
  • ✅ No raw SQL queries
  • ✅ Category: plugin, fe, be, misc
  • ✅ Example: rte_ckeditor_image, simple content elements, frontend plugins

Benefits:

  • ⚡ Startup: 5-10 seconds faster per ddev start
  • 💾 RAM: 900 MB saved (no MariaDB container)
  • 💿 Disk: 744 MB saved (no container image)
  • 🔒 Isolation: Perfect v11/v12/v13 separation (separate .sqlite files)

Configuration:

# No .ddev/config.yaml database config needed
# TYPO3 installation uses SQLite automatically

Critical Warnings:

  • ⚠️ Development ONLY - Never use SQLite in production
  • ⚠️ Switch to MariaDB if you add custom SQL queries or tables
  • ⚠️ Final Testing - Run compatibility tests on MariaDB before release

🔧 Tier 2: MariaDB 10.11 (Complex Extensions - Production Parity)

Recommended for:

  • ❌ Extensions with custom database tables (ext_tables.sql present)
  • ❌ Extensions using raw SQL queries
  • ❌ Performance-critical operations
  • ❌ Category: services, module
  • ❌ Unknown complexity (safe default)

Benefits:

  • ✅ Production Standard: 95%+ TYPO3 hosting uses MariaDB
  • ✅ Extension Compatibility: 99%+ TYPO3 extensions tested on MariaDB
  • ✅ Performance: 13-36% faster than MySQL 8 for transactional workloads
  • ✅ TYPO3 Ecosystem: Documentation, tutorials, community standard

Configuration:

# In .ddev/config.yaml
database:
  type: mariadb
  version: "10.11"

🌐 Tier 3: PostgreSQL 16 (Specialized Requirements)

Recommended for:

  • 🎯 GIS/spatial data (PostGIS)
  • 🎯 Advanced analytics or complex queries
  • 🎯 Explicit PostgreSQL requirement

Configuration:

# In .ddev/config.yaml
database:
  type: postgres
  version: "16"

🏢 Tier 4: MySQL 8.0 (Corporate/Oracle Ecosystem)

Recommended for:

  • 🏢 Corporate environments requiring Oracle integration
  • 🏢 Production specifically uses MySQL 8

Configuration:

# In .ddev/config.yaml
database:
  type: mysql
  version: "8.0"

Auto-Detection Logic:

The skill will analyze your extension and suggest the appropriate tier:

SQLite Detection (Tier 1):
  ✓ ext_tables.sql: Absent or empty
  ✓ Raw SQL patterns: None found
  ✓ File size: < 1 MB
  ✓ Category: plugin, fe, be, misc
  → Suggests: SQLite (development-optimized)

MariaDB Detection (Tier 2):
  ✗ ext_tables.sql: Present with custom tables
  ✗ Raw SQL patterns: Found
  ✗ File size: > 1 MB
  ✗ Category: services, module
  → Suggests: MariaDB 10.11 (production-realistic)

PostgreSQL Detection (Tier 3):
  • Extension name: Contains "postgres", "pgsql", "postgis"
  • composer.json: Requires "typo3/cms-pgsql"
  • Keywords: "GIS", "spatial", "analytics"
  → Suggests: PostgreSQL 16 (specialized)

Alternative Options:

MariaDB 11 - Forward-looking performance:

database:
  type: mariadb
  version: "11.4"
  • Latest features (+40% performance vs 10.11)
  • Forward compatibility testing

For detailed rationale, see: docs/adr/0002-mariadb-default-with-database-alternatives.md

XDebug Setup

Enable XDebug for debugging:

ddev xdebug on

Customize TYPO3 Versions

Edit .ddev/docker-compose.web.yaml and installation scripts to add/remove versions.

Database Access

# Direct database access
ddev mysql

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

# Import database
ddev import-db --file=backup.sql.gz

Optional Services

The skill includes optional service templates for enhanced TYPO3 development:

Valkey / Redis (Caching)

Add high-performance caching to TYPO3 using Valkey (default) or Redis (alternative).

Default: Valkey 8 (Open Source, Future-Proof)

# Copy Valkey template (default)
cp .ddev/templates/docker-compose.services.yaml.optional .ddev/docker-compose.services.yaml
cp .ddev/templates/config.redis.php.example .ddev/config.redis.php.example

# Restart DDEV
ddev restart

# Test Valkey (wire-compatible with Redis)
ddev ssh
redis-cli -h valkey ping  # Should return: PONG

Alternative: Redis 7 (For Legacy Production Parity)

# Use Redis 7 alternative template
cp .ddev/templates/docker-compose.services-redis.yaml.optional .ddev/docker-compose.services.yaml

# Restart DDEV
ddev restart

# Test Redis
ddev ssh
redis-cli -h redis ping  # Should return: PONG

Why Valkey Default?

Valkey is wire-protocol compatible with Redis but offers:

  • ✅ True Open Source: BSD-3-Clause license (Redis 7.4+ is proprietary)
  • ✅ Industry Adoption: AWS, Google Cloud, Oracle backing (Linux Foundation project)
  • ✅ Smaller Image: 69.7 MB (vs 100 MB Redis 8, 60.6 MB Redis 7)
  • ✅ Cost-Effective: 20-33% cheaper on AWS ElastiCache
  • ✅ Future-Proof: Strategic direction for cloud/managed hosting

When to Use Redis 7 Instead:

  • Your production environment explicitly uses Redis 7.x
  • Corporate policy requires battle-tested technology only (Redis has 15 years vs Valkey 1 year)
  • Exact production-development parity needed with existing infrastructure

Technical Details:

Valkey: valkey/valkey:8-alpine (69.7 MB) Redis: redis:7-alpine (60.6 MB) Memory: 256MB with LRU eviction policy Port: 6379 (same for both)

Configuration: Both use identical TYPO3 configuration. Add cache backend to AdditionalConfiguration.php (see .ddev/config.redis.php.example)

For detailed rationale, see: docs/adr/0001-valkey-default-with-redis-alternative.md

MailPit (Email Testing)

Catch all emails sent by TYPO3 for testing:

# Already included in docker-compose.services.yaml.optional
# Access Web UI after ddev restart:
# http://{{DDEV_SITENAME}}.ddev.site:8025

Image: axllent/mailpit:latest SMTP: mailpit:1025 (automatically configured in docker-compose.web.yaml)

Ofelia (TYPO3 Scheduler Automation)

Automate TYPO3 scheduler tasks with ghcr.io/netresearch/ofelia:

# Copy Ofelia configuration
cp .ddev/templates/docker-compose.ofelia.yaml.optional .ddev/docker-compose.ofelia.yaml

# Restart DDEV
ddev restart

# View scheduler logs
docker logs -f ddev-{{DDEV_SITENAME}}-ofelia

Image: ghcr.io/netresearch/ofelia:latest (GitHub Container Registry - TYPO3-optimized fork) Default Schedule: TYPO3 scheduler runs every 1 minute for all versions Cache Warmup: Every 1 hour for v13

DDEV Naming: Uses docker-compose.*.yaml naming (DDEV v1.24.8 requirement, not Compose v2 standard) No Version Field: All service files omit version: declaration per Compose v2 spec

Shell Aliases

Add convenient shortcuts:

# Copy bash additions
cp .ddev/templates/homeadditions/.bashrc_additions.optional .ddev/homeadditions/.bashrc_additions

# Restart DDEV to load aliases
ddev restart

# Available aliases:
ddev ssh
t3-scheduler-v11    # Run TYPO3 11 scheduler
t3-scheduler-v12    # Run TYPO3 12 scheduler
t3-scheduler-v13    # Run TYPO3 13 scheduler
t3-scheduler-all    # Run scheduler on all versions
redis               # Access Redis CLI
t3-cache-flush-v13  # Flush TYPO3 13 cache

Complete Services Documentation

For detailed service configuration, troubleshooting, and performance tuning:

# Copy services README
cp .ddev/templates/README-SERVICES.md.optional .ddev/README-SERVICES.md

Important Notes:

  • DDEV v1.24.8 requires docker-compose.*.yaml naming (auto-loads from .ddev/)
  • Ofelia image: ghcr.io/netresearch/ofelia:latest (not Docker Hub)
  • Ofelia command: daemon --docker-events (not --docker)
  • Redis config must NOT be .yaml (DDEV tries to parse it as config)
Reference in New Issue View Git Blame Copy Permalink