525 lines
13 KiB
Markdown
525 lines
13 KiB
Markdown
# Development Environment Standards
|
||
|
||
**Purpose:** Validate development environment setup for consistent, reproducible TYPO3 extension development
|
||
|
||
## Why Development Environment Matters
|
||
|
||
A properly configured development environment ensures:
|
||
|
||
- ✅ **Consistency** - All developers work with identical PHP/TYPO3/database versions
|
||
- ✅ **Onboarding** - New contributors can start immediately without complex setup
|
||
- ✅ **CI/CD Parity** - Local environment matches production/staging
|
||
- ✅ **Reproducibility** - Bugs are reproducible across all environments
|
||
- ✅ **Cross-Platform** - Works on macOS, Linux, Windows (WSL)
|
||
|
||
Without standardized dev environment:
|
||
- ❌ "Works on my machine" syndrome
|
||
- ❌ Inconsistent PHP/database versions causing bugs
|
||
- ❌ Complex setup discourages contributions
|
||
- ❌ CI failures that don't reproduce locally
|
||
|
||
## TYPO3 Community Standards
|
||
|
||
### DDEV - Primary Recommendation
|
||
|
||
**DDEV** is the **de facto standard** for TYPO3 development:
|
||
|
||
- ✅ Official TYPO3 core development uses DDEV
|
||
- ✅ TYPO3 Best Practices (Tea extension) uses DDEV
|
||
- ✅ TYPO3 documentation recommends DDEV
|
||
- ✅ Cross-platform support (Docker-based)
|
||
- ✅ Preconfigured for TYPO3 (`ddev config --project-type=typo3`)
|
||
|
||
**Alternative:** Docker Compose (acceptable, more manual configuration)
|
||
|
||
## Validation Checklist
|
||
|
||
### 1. DDEV Configuration
|
||
|
||
**Check for `.ddev/` directory:**
|
||
|
||
```bash
|
||
ls -la .ddev/
|
||
```
|
||
|
||
**Required files:**
|
||
- `.ddev/config.yaml` - Core DDEV configuration
|
||
- `.ddev/.gitignore` - Excludes dynamic files (import-db, .ddev-docker-compose-*.yaml)
|
||
|
||
**Optional but recommended:**
|
||
- `.ddev/config.typo3.yaml` - TYPO3-specific settings
|
||
- `.ddev/commands/` - Custom DDEV commands
|
||
- `.ddev/docker-compose.*.yaml` - Additional services
|
||
|
||
**Severity if missing:** 🟡 **Medium** - Indicates no standardized dev environment
|
||
|
||
### 2. DDEV config.yaml Structure
|
||
|
||
**Minimum DDEV Configuration:**
|
||
|
||
```yaml
|
||
name: extension-name
|
||
type: typo3
|
||
docroot: .Build/public
|
||
php_version: "8.2" # Match composer.json minimum
|
||
webserver_type: nginx-fpm
|
||
router_http_port: "80"
|
||
router_https_port: "443"
|
||
xdebug_enabled: false
|
||
additional_hostnames: []
|
||
additional_fqdns: []
|
||
database:
|
||
type: mariadb
|
||
version: "10.11"
|
||
omit_containers: [ddev-ssh-agent]
|
||
```
|
||
|
||
**Validation Rules:**
|
||
|
||
| Field | Validation | Example | Severity |
|
||
|-------|-----------|---------|----------|
|
||
| `name` | Should match extension key or composer name | `rte-ckeditor-image` | Low |
|
||
| `type` | Must be `typo3` | `typo3` | High |
|
||
| `docroot` | Should match composer.json web-dir | `.Build/public` | High |
|
||
| `php_version` | Should match composer.json minimum PHP | `"8.2"` | High |
|
||
| `database.type` | Should be `mariadb` (TYPO3 standard) | `mariadb` | Medium |
|
||
| `database.version` | Should be LTS version (10.11 or 11.x) | `"10.11"` | Medium |
|
||
|
||
**Example Check:**
|
||
|
||
```bash
|
||
# Extension composer.json
|
||
"require": {
|
||
"php": "^8.2 || ^8.3 || ^8.4",
|
||
"typo3/cms-core": "^13.4"
|
||
}
|
||
"extra": {
|
||
"typo3/cms": {
|
||
"web-dir": ".Build/public"
|
||
}
|
||
}
|
||
|
||
# DDEV config.yaml SHOULD have:
|
||
php_version: "8.2" # ✅ Matches minimum
|
||
docroot: .Build/public # ✅ Matches web-dir
|
||
type: typo3 # ✅ Correct type
|
||
|
||
# DDEV config.yaml SHOULD NOT have:
|
||
php_version: "7.4" # ❌ Below minimum
|
||
docroot: public # ❌ Doesn't match web-dir
|
||
type: php # ❌ Wrong type
|
||
```
|
||
|
||
### 3. Docker Compose (Alternative)
|
||
|
||
If DDEV not present, check for `docker-compose.yml`:
|
||
|
||
**Minimum Docker Compose Configuration:**
|
||
|
||
```yaml
|
||
version: '3.8'
|
||
|
||
services:
|
||
web:
|
||
image: ghcr.io/typo3/core-testing-php82:latest
|
||
volumes:
|
||
- .:/var/www/html
|
||
working_dir: /var/www/html
|
||
ports:
|
||
- "8000:80"
|
||
environment:
|
||
TYPO3_CONTEXT: Development
|
||
|
||
db:
|
||
image: mariadb:10.11
|
||
environment:
|
||
MYSQL_ROOT_PASSWORD: root
|
||
MYSQL_DATABASE: typo3
|
||
volumes:
|
||
- db_data:/var/lib/mysql
|
||
|
||
volumes:
|
||
db_data:
|
||
```
|
||
|
||
**Validation Rules:**
|
||
|
||
| Service | Validation | Severity |
|
||
|---------|-----------|----------|
|
||
| `web` service exists | Required | High |
|
||
| PHP version matches composer.json | Required | High |
|
||
| `db` service exists | Required | Medium |
|
||
| Database type is MariaDB/MySQL | Recommended | Low |
|
||
| Volumes preserve database data | Required | High |
|
||
|
||
**Severity if missing:** 🟡 **Medium** - Harder to onboard, but not critical
|
||
|
||
### 4. DevContainer (VS Code Remote Containers)
|
||
|
||
Check for `.devcontainer/devcontainer.json`:
|
||
|
||
**Example DevContainer Configuration:**
|
||
|
||
```json
|
||
{
|
||
"name": "TYPO3 Extension Development",
|
||
"dockerComposeFile": ["../docker-compose.yml"],
|
||
"service": "web",
|
||
"workspaceFolder": "/var/www/html",
|
||
"customizations": {
|
||
"vscode": {
|
||
"extensions": [
|
||
"bmewburn.vscode-intelephense-client",
|
||
"xdebug.php-debug",
|
||
"EditorConfig.EditorConfig"
|
||
],
|
||
"settings": {
|
||
"php.validate.executablePath": "/usr/local/bin/php"
|
||
}
|
||
}
|
||
},
|
||
"features": {
|
||
"ghcr.io/devcontainers/features/common-utils:2": {},
|
||
"ghcr.io/devcontainers/features/node:1": {}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Validation:**
|
||
- File exists: ✅ Good (VS Code support)
|
||
- References docker-compose.yml or DDEV: ✅ Integrated approach
|
||
- Empty directory: ⚠️ Incomplete setup
|
||
|
||
**Severity if missing:** 🟢 **Low** - Nice to have, not required
|
||
|
||
## DDEV-Specific Best Practices
|
||
|
||
### TYPO3-Optimized Settings
|
||
|
||
**`.ddev/config.typo3.yaml`:**
|
||
|
||
```yaml
|
||
# TYPO3-specific DDEV configuration
|
||
override_config: false
|
||
web_extra_daemons:
|
||
- name: "typo3-backend-lock-handler"
|
||
command: "/var/www/html/.Build/bin/typo3 scheduler:run"
|
||
directory: /var/www/html
|
||
|
||
hooks:
|
||
post-start:
|
||
- exec: composer install
|
||
- exec: .Build/bin/typo3 cache:flush
|
||
|
||
# Additional PHP settings for TYPO3
|
||
php_ini:
|
||
memory_limit: 512M
|
||
max_execution_time: 240
|
||
upload_max_filesize: 32M
|
||
post_max_size: 32M
|
||
```
|
||
|
||
### Custom DDEV Commands
|
||
|
||
**`.ddev/commands/web/typo3`:**
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
## Description: Run TYPO3 CLI commands
|
||
## Usage: typo3 [args]
|
||
## Example: "ddev typo3 cache:flush"
|
||
|
||
.Build/bin/typo3 "$@"
|
||
```
|
||
|
||
**`.ddev/commands/web/test-unit`:**
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
## Description: Run unit tests
|
||
## Usage: test-unit [args]
|
||
|
||
.Build/bin/phpunit -c Build/phpunit/UnitTests.xml "$@"
|
||
```
|
||
|
||
**`.ddev/commands/web/test-functional`:**
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
## Description: Run functional tests
|
||
## Usage: test-functional [args]
|
||
|
||
.Build/bin/phpunit -c Build/phpunit/FunctionalTests.xml "$@"
|
||
```
|
||
|
||
## Conformance Evaluation Workflow
|
||
|
||
### Step 1: Detect Development Environment Type
|
||
|
||
```bash
|
||
# Check for DDEV
|
||
if [ -f ".ddev/config.yaml" ]; then
|
||
DEV_ENV="ddev"
|
||
SCORE=20 # Full points for DDEV
|
||
|
||
# Check for Docker Compose
|
||
elif [ -f "docker-compose.yml" ]; then
|
||
DEV_ENV="docker-compose"
|
||
SCORE=15 # Good, but manual
|
||
|
||
# Check for DevContainer only
|
||
elif [ -f ".devcontainer/devcontainer.json" ]; then
|
||
DEV_ENV="devcontainer"
|
||
SCORE=10 # VS Code specific
|
||
|
||
# No dev environment
|
||
else
|
||
DEV_ENV="none"
|
||
SCORE=0
|
||
fi
|
||
```
|
||
|
||
### Step 2: Validate Configuration Against Extension
|
||
|
||
**For DDEV:**
|
||
|
||
```bash
|
||
# Extract extension requirements
|
||
MIN_PHP=$(jq -r '.require.php' composer.json | grep -oE '[0-9]+\.[0-9]+' | head -1)
|
||
WEB_DIR=$(jq -r '.extra.typo3.cms."web-dir"' composer.json)
|
||
|
||
# Validate DDEV config
|
||
DDEV_PHP=$(grep 'php_version:' .ddev/config.yaml | awk '{print $2}' | tr -d '"')
|
||
DDEV_DOCROOT=$(grep 'docroot:' .ddev/config.yaml | awk '{print $2}')
|
||
DDEV_TYPE=$(grep 'type:' .ddev/config.yaml | awk '{print $2}')
|
||
|
||
# Compare
|
||
if [ "${DDEV_PHP}" != "${MIN_PHP}" ]; then
|
||
echo "⚠️ PHP version mismatch: DDEV ${DDEV_PHP} vs required ${MIN_PHP}"
|
||
fi
|
||
|
||
if [ "${DDEV_DOCROOT}" != "${WEB_DIR}" ]; then
|
||
echo "⚠️ Docroot mismatch: DDEV ${DDEV_DOCROOT} vs composer ${WEB_DIR}"
|
||
fi
|
||
|
||
if [ "${DDEV_TYPE}" != "typo3" ]; then
|
||
echo "❌ DDEV type should be 'typo3', found '${DDEV_TYPE}'"
|
||
fi
|
||
```
|
||
|
||
### Step 3: Check for Recommended Enhancements
|
||
|
||
```bash
|
||
# DDEV commands
|
||
if [ -d ".ddev/commands/web" ]; then
|
||
COMMANDS=$(ls .ddev/commands/web/ 2>/dev/null | wc -l)
|
||
echo "✅ DDEV has ${COMMANDS} custom commands"
|
||
else
|
||
echo "ℹ️ No custom DDEV commands (consider adding typo3, test-unit, test-functional)"
|
||
fi
|
||
|
||
# TYPO3-specific config
|
||
if [ -f ".ddev/config.typo3.yaml" ]; then
|
||
echo "✅ TYPO3-specific DDEV configuration present"
|
||
else
|
||
echo "ℹ️ No TYPO3-specific config (optional)"
|
||
fi
|
||
```
|
||
|
||
## Conformance Report Integration
|
||
|
||
### When Evaluating Development Environment:
|
||
|
||
**In "Best Practices" Section:**
|
||
|
||
```markdown
|
||
### Development Environment
|
||
|
||
**Configuration:**
|
||
|
||
- ✅ DDEV configured (.ddev/config.yaml present)
|
||
- ✅ PHP version matches composer.json minimum (8.2)
|
||
- ✅ Docroot matches composer.json web-dir (.Build/public)
|
||
- ✅ Type set to 'typo3' for TYPO3-optimized setup
|
||
- ✅ MariaDB 10.11 (LTS) configured
|
||
- ✅ Custom DDEV commands for testing (test-unit, test-functional)
|
||
- ℹ️ Optional: TYPO3-specific config (.ddev/config.typo3.yaml) could enhance setup
|
||
|
||
**Or with issues:**
|
||
|
||
- ❌ No development environment configuration
|
||
- Missing: .ddev/config.yaml, docker-compose.yml
|
||
- Impact: Inconsistent development environments, difficult onboarding
|
||
- Severity: Medium
|
||
- Recommendation: Add DDEV configuration from Tea extension pattern
|
||
- Reference: https://github.com/TYPO3BestPractices/tea/tree/main/.ddev
|
||
|
||
- ⚠️ DDEV PHP version mismatch
|
||
- File: .ddev/config.yaml
|
||
- Current: php_version: "7.4"
|
||
- Expected: php_version: "8.2" (from composer.json)
|
||
- Severity: High
|
||
- Fix: Update php_version to match minimum requirement
|
||
|
||
- ⚠️ DDEV docroot mismatch
|
||
- File: .ddev/config.yaml
|
||
- Current: docroot: public
|
||
- Expected: docroot: .Build/public (from composer.json extra.typo3.cms.web-dir)
|
||
- Severity: High
|
||
- Fix: Update docroot to match web-dir
|
||
```
|
||
|
||
## Scoring Impact
|
||
|
||
**Best Practices Score Components (out of 20):**
|
||
|
||
| Component | Max Points | DDEV | Docker Compose | None |
|
||
|-----------|-----------|------|----------------|------|
|
||
| **Dev Environment Exists** | 6 | 6 | 4 | 0 |
|
||
| **Configuration Correct** | 4 | 4 | 3 | 0 |
|
||
| **Version Matching** | 3 | 3 | 2 | 0 |
|
||
| **Documentation** | 2 | 2 | 1 | 0 |
|
||
| **Custom Commands/Enhancements** | 2 | 2 | 0 | 0 |
|
||
| **Other Best Practices** | 3 | 3 | 3 | 3 |
|
||
| **Total** | 20 | 20 | 13 | 3 |
|
||
|
||
**Deductions:**
|
||
|
||
| Issue | Severity | Score Impact |
|
||
|-------|----------|--------------|
|
||
| No dev environment at all | High | -6 points |
|
||
| PHP version mismatch | High | -3 points |
|
||
| Docroot mismatch | High | -3 points |
|
||
| Wrong type (not 'typo3') | Medium | -2 points |
|
||
| Missing custom commands | Low | -1 point |
|
||
| No documentation | Low | -1 point |
|
||
|
||
## Tea Extension Reference
|
||
|
||
**Source:** https://github.com/TYPO3BestPractices/tea/tree/main/.ddev
|
||
|
||
**Tea DDEV Structure:**
|
||
|
||
```
|
||
.ddev/
|
||
├── .gitignore
|
||
├── config.yaml # Main configuration
|
||
├── config.typo3.yaml # TYPO3-specific settings
|
||
└── commands/
|
||
└── web/
|
||
├── typo3 # TYPO3 CLI wrapper
|
||
├── test-unit # Run unit tests
|
||
└── test-functional # Run functional tests
|
||
```
|
||
|
||
**Tea config.yaml (simplified):**
|
||
|
||
```yaml
|
||
name: tea
|
||
type: typo3
|
||
docroot: .Build/public
|
||
php_version: "8.2"
|
||
webserver_type: nginx-fpm
|
||
database:
|
||
type: mariadb
|
||
version: "10.11"
|
||
xdebug_enabled: false
|
||
```
|
||
|
||
**Usage Examples:**
|
||
|
||
```bash
|
||
# Start DDEV
|
||
ddev start
|
||
|
||
# Install dependencies
|
||
ddev composer install
|
||
|
||
# Run TYPO3 CLI
|
||
ddev typo3 cache:flush
|
||
|
||
# Run unit tests
|
||
ddev test-unit
|
||
|
||
# Run functional tests
|
||
ddev test-functional
|
||
|
||
# Access database
|
||
ddev mysql
|
||
|
||
# SSH into container
|
||
ddev ssh
|
||
```
|
||
|
||
## Quick Reference Checklist
|
||
|
||
**When evaluating development environment:**
|
||
|
||
```
|
||
□ .ddev/config.yaml exists (preferred)
|
||
□ OR docker-compose.yml exists (acceptable)
|
||
□ OR .devcontainer/devcontainer.json exists (VS Code only)
|
||
□ Configuration type is 'typo3' (DDEV) or uses TYPO3 image (Docker Compose)
|
||
□ PHP version matches composer.json minimum
|
||
□ Docroot matches composer.json web-dir
|
||
□ Database is MariaDB 10.11+ or MySQL 8.0+
|
||
□ Custom commands for common tasks (DDEV)
|
||
□ Documentation exists (README.md mentions DDEV/Docker setup)
|
||
□ .ddev/.gitignore present (excludes dynamic files)
|
||
□ Post-start hooks run composer install (optional but nice)
|
||
```
|
||
|
||
## Common Issues
|
||
|
||
### Issue: Empty .devcontainer/
|
||
|
||
**Diagnosis:**
|
||
```bash
|
||
ls -la .devcontainer/
|
||
# total 8
|
||
# drwxr-sr-x 2 user user 4096 Oct 20 20:05 .
|
||
```
|
||
|
||
**Severity:** 🟢 Low (incomplete setup, doesn't help or hurt)
|
||
|
||
**Fix:** Either populate with devcontainer.json or remove directory
|
||
|
||
### Issue: DDEV but no .gitignore
|
||
|
||
**Diagnosis:**
|
||
```bash
|
||
ls -la .ddev/.gitignore
|
||
# No such file or directory
|
||
```
|
||
|
||
**Problem:** DDEV generates dynamic files that shouldn't be committed
|
||
|
||
**Fix:** Create `.ddev/.gitignore`:
|
||
```
|
||
/*.yaml
|
||
.ddev-docker-compose-*.yaml
|
||
.homeadditions
|
||
.sshimagename
|
||
commands/web/.ddev-docker-compose-*.yaml
|
||
import-db/
|
||
```
|
||
|
||
### Issue: Wrong DDEV project type
|
||
|
||
**Diagnosis:**
|
||
```yaml
|
||
# .ddev/config.yaml
|
||
type: php # ❌ Wrong
|
||
```
|
||
|
||
**Problem:** Misses TYPO3-specific optimizations (URL structure, etc.)
|
||
|
||
**Fix:** Change to `type: typo3`
|
||
|
||
## Resources
|
||
|
||
- **DDEV Documentation:** https://ddev.readthedocs.io/
|
||
- **DDEV TYPO3 Quickstart:** https://ddev.readthedocs.io/en/stable/users/quickstart/#typo3
|
||
- **Tea Extension DDEV Setup:** https://github.com/TYPO3BestPractices/tea/tree/main/.ddev
|
||
- **TYPO3 Docker Documentation:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/LocalDevelopment/
|