Initial commit

2025-11-30 08:45:19 +08:00
commit f6bb21b404
6 changed files with 1479 additions and 0 deletions
--- a/references/ddev.md
+++ b/references/ddev.md
@@ -0,0 +1,450 @@
+# DDEV Commands Reference
+
+Comprehensive DDEV command reference for Drupal development. DDEV is a Docker-based local development environment.
+
+## Project Initialization
+
+```bash
+# Initialize DDEV in current directory
+ddev config
+
+# Initialize with Drupal specific settings
+ddev config --project-type=drupal10 --docroot=web --create-docroot
+
+# Initialize Drupal 9
+ddev config --project-type=drupal9 --docroot=web
+
+# Initialize Drupal 11
+ddev config --project-type=drupal --docroot=web
+
+# Configure project name and PHP version
+ddev config --project-name=myproject --php-version=8.2
+```
+
+## Project Management
+
+```bash
+# Start project
+ddev start
+
+# Stop project
+ddev stop
+
+# Restart project
+ddev restart
+
+# Delete project (keeps files, removes containers)
+ddev delete
+
+# Delete project and remove images
+ddev delete --omit-snapshot
+
+# Power off all DDEV projects
+ddev poweroff
+
+# Show project description
+ddev describe
+
+# List all DDEV projects
+ddev list
+```
+
+## Accessing Services
+
+```bash
+# SSH into web container
+ddev ssh
+
+# SSH into database container
+ddev ssh -s db
+
+# Open project in browser
+ddev launch
+
+# Open specific path
+ddev launch /admin
+
+# Open phpMyAdmin
+ddev launch -p
+
+# Open MailHog (email catcher)
+ddev launch -m
+```
+
+## Database Operations
+
+```bash
+# Import database from file
+ddev import-db --src=dump.sql
+ddev import-db --src=dump.sql.gz
+ddev import-db --file=dump.sql
+
+# Export database to file
+ddev export-db --file=backup.sql
+ddev export-db --file=backup.sql.gz --gzip
+
+# Execute MySQL query
+ddev mysql -e "SELECT * FROM users WHERE uid=1;"
+
+# Connect to MySQL CLI
+ddev mysql
+
+# Import database and files from @drush-alias
+ddev pull @production
+
+# Snapshot database (backup)
+ddev snapshot
+
+# Restore from snapshot
+ddev snapshot restore
+
+# List snapshots
+ddev snapshot list
+
+# Delete snapshot
+ddev snapshot delete --name=backup-name
+```
+
+## File Management
+
+```bash
+# Import files directory
+ddev import-files --src=/path/to/files
+
+# Pull files from remote using Drush alias
+ddev pull @production --skip-db
+
+# SCP files into container
+ddev scp local-file.txt :/var/www/html/web/
+
+# SCP files from container
+ddev scp :/var/www/html/web/file.txt ./local-file.txt
+```
+
+## Composer
+
+```bash
+# Run composer install
+ddev composer install
+
+# Require package
+ddev composer require drupal/webform
+
+# Require dev package
+ddev composer require --dev drupal/devel
+
+# Update packages
+ddev composer update
+
+# Remove package
+ddev composer remove drupal/old_module
+
+# Show installed packages
+ddev composer show
+```
+
+## Drush Integration
+
+```bash
+# Run Drush commands
+ddev drush status
+ddev drush cr
+ddev drush uli
+
+# Config import
+ddev drush cim -y
+
+# Config export
+ddev drush cex -y
+
+# Update database
+ddev drush updb -y
+
+# Enable module
+ddev drush en mymodule -y
+
+# Install Drupal
+ddev drush site:install standard --account-name=admin --account-pass=admin
+```
+
+## Logs & Debugging
+
+```bash
+# View container logs
+ddev logs
+
+# Follow logs in real-time
+ddev logs -f
+
+# View web server logs
+ddev logs -s web
+
+# View database logs
+ddev logs -s db
+
+# Enable Xdebug
+ddev xdebug on
+
+# Disable Xdebug
+ddev xdebug off
+
+# Toggle Xdebug
+ddev xdebug toggle
+
+# Check Xdebug status
+ddev xdebug status
+```
+
+## Mailhog (Email Testing)
+
+```bash
+# Launch MailHog UI
+ddev launch -m
+
+# All emails sent by Drupal are caught in MailHog
+# Access at: http://<project>.ddev.site:8025
+```
+
+## Custom Commands
+
+```bash
+# Execute arbitrary command in web container
+ddev exec ls -la
+
+# Run PHP command
+ddev exec php -v
+
+# Run npm
+ddev exec npm install
+ddev exec npm run build
+
+# Execute command in specific service
+ddev exec -s db mysql --version
+```
+
+## Add-ons & Services
+
+```bash
+# Get additional services (Redis, Elasticsearch, etc.)
+ddev get ddev/ddev-redis
+ddev get ddev/ddev-elasticsearch
+ddev get ddev/ddev-solr
+
+# List available add-ons
+ddev get --list
+
+# Remove add-on
+ddev get --remove ddev/ddev-redis
+```
+
+## Environment & Configuration
+
+```bash
+# Show DDEV version
+ddev version
+
+# Show project info
+ddev describe
+
+# Edit project configuration
+# Edit .ddev/config.yaml manually
+
+# Common config.yaml settings:
+# - php_version: "8.2"
+# - nodejs_version: "18"
+# - webserver_type: nginx-fpm
+# - database: mariadb:10.11
+# - router_http_port: "80"
+# - router_https_port: "443"
+```
+
+## Multiple PHP Versions
+
+```bash
+# Set PHP version
+ddev config --php-version=8.1
+ddev config --php-version=8.2
+ddev config --php-version=8.3
+
+# Apply changes
+ddev restart
+```
+
+## Database Types & Versions
+
+```bash
+# Use MySQL
+ddev config --database=mysql:8.0
+
+# Use MariaDB (default)
+ddev config --database=mariadb:10.11
+
+# Use PostgreSQL
+ddev config --database=postgres:14
+```
+
+## Performance Optimization
+
+```bash
+# Use Mutagen for better file sync performance (Mac)
+ddev config --mutagen-enabled
+
+# Use NFS for better performance (Mac/Linux)
+ddev config --nfs-mount-enabled
+
+# Disable NFS
+ddev config --nfs-mount-enabled=false
+```
+
+## Sharing Your Project
+
+```bash
+# Share project via ngrok (requires ngrok account)
+ddev share
+
+# This creates a public URL for your local site
+```
+
+## Drupal-Specific Workflows
+
+### Fresh Drupal Installation
+```bash
+# Initialize DDEV
+ddev config --project-type=drupal10 --docroot=web
+
+# Start DDEV
+ddev start
+
+# Install Drupal via Composer
+ddev composer create drupal/recommended-project
+
+# Install Drupal
+ddev drush site:install standard --account-name=admin --account-pass=admin
+
+# Launch site
+ddev launch
+```
+
+### Clone Existing Project
+```bash
+# Clone repository
+git clone <repo-url> myproject
+cd myproject
+
+# Start DDEV (uses existing .ddev/config.yaml)
+ddev start
+
+# Install dependencies
+ddev composer install
+
+# Import database
+ddev import-db --src=database.sql.gz
+
+# Import files
+ddev import-files --src=files.tar.gz
+
+# Clear cache
+ddev drush cr
+
+# Launch site
+ddev launch
+```
+
+### Development Workflow
+```bash
+# Start work
+ddev start
+
+# Enable development modules
+ddev drush en devel devel_generate -y
+
+# Watch theme files (if using compile tools)
+ddev exec npm run watch
+
+# Clear cache frequently
+ddev drush cr
+
+# Stop work
+ddev stop
+```
+
+## Troubleshooting
+
+```bash
+# Restart if containers are unresponsive
+ddev restart
+
+# Clean restart (rebuild containers)
+ddev restart --clean
+
+# Remove all Docker volumes and restart
+ddev stop --remove-data
+ddev start
+
+# Check for port conflicts
+ddev describe
+
+# View detailed debug info
+ddev debug test
+
+# Check Docker is running
+docker ps
+
+# Rebuild DDEV containers from scratch
+ddev delete --omit-snapshot
+ddev start
+```
+
+## Common Issues
+
+### Port Conflicts
+If ports 80/443 are in use:
+```bash
+# Change router ports in .ddev/config.yaml
+router_http_port: "8080"
+router_https_port: "8443"
+
+# Then restart
+ddev restart
+```
+
+### Permission Issues
+```bash
+# Fix file permissions
+ddev exec chmod -R 755 web/sites/default/files
+
+# Fix ownership
+ddev exec chown -R www-data:www-data web/sites/default/files
+```
+
+### Database Connection Issues
+Check database credentials in settings.php or settings.ddev.php:
+```php
+$databases['default']['default'] = [
+  'database' => 'db',
+  'username' => 'db',
+  'password' => 'db',
+  'host' => 'db',
+  'port' => '3306',
+  'driver' => 'mysql',
+];
+```
+
+## Best Practices
+
+1. **Always use `ddev` prefix**: Run Composer, Drush, and other tools through DDEV (`ddev composer`, `ddev drush`)
+2. **Commit .ddev/config.yaml**: Share project configuration with team
+3. **Use .gitignore**: Exclude `.ddev/.importdb`, `.ddev/.ddev-docker-compose*`
+4. **Performance**: Enable Mutagen or NFS on Mac for better performance
+5. **Xdebug**: Only enable when needed (slows performance)
+6. **Regular updates**: Keep DDEV updated with `brew upgrade ddev` (Mac) or equivalent
+7. **Clean shutdown**: Use `ddev stop` before system shutdown
+8. **Database snapshots**: Create snapshots before major changes
+9. **Environment variables**: Use `.ddev/config.yaml` for environment-specific settings
+10. **Multiple projects**: Use unique project names to avoid conflicts
+
+## Additional Resources
+
+- Official docs: https://ddev.readthedocs.io/
+- DDEV Discord: https://discord.gg/hCZFfAMc5k
+- DDEV GitHub: https://github.com/ddev/ddev