From 5c850deac5a88cf69c9e0e32a1ccbdb6c72f98ef Mon Sep 17 00:00:00 2001
From: MYDev <mydev@my-dev.pro>
Date: Thu, 19 Mar 2026 17:36:48 +0200
Subject: [PATCH] update v1.1.0

---
 README.md | 662 ++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 413 insertions(+), 249 deletions(-)

diff --git a/README.md b/README.md
index 0cb40bf..1bcec15 100644
--- a/README.md
+++ b/README.md
@@ -1,316 +1,480 @@
 # FrankenPHP Docker Environment
 
-A modern, high-performance Docker environment for PHP applications using FrankenPHP, featuring built-in HTTP/2, HTTP/3, and automatic HTTPS support with Node.js integration.
+A modern, lightweight Docker environment for PHP applications using FrankenPHP, featuring HTTP/2, HTTP/3, automatic HTTPS, and built-in Node.js support for multiple PHP frameworks.
 
 ## Features
 
-- **FrankenPHP Server**: Modern PHP server with HTTP/2, HTTP/3, and automatic HTTPS
-- **MariaDB Database**: Reliable database server with persistent data storage
-- **Node.js Integration**: Full Node.js runtime for frontend tooling and build processes
-- **Framework Support**: Optimized for OpenCart, Laravel, and Symfony
-- **Multiple Modes**: Local development, proxy, and production configurations
-- **Rich PHP Extensions**: Comprehensive set of PHP extensions including Redis, APCu, and ImageMagick
-- **Composer & NPM**: PHP and JavaScript dependency management
-- **Volume Persistence**: Persistent data for database and Caddy certificates
-- **Hot Reload**: Automatic code reloading during development
+- 🚀 **FrankenPHP Server**: Modern PHP server with HTTP/2, HTTP/3, and automatic HTTPS via Caddy
+- 🗄️ **MariaDB Database**: Persistent relational database for your applications
+- 📦 **Node.js Integration**: Full Node.js runtime (v20.x) for frontend tooling and build processes
+- 🎯 **Multi-Framework Support**: Optimized build targets for Laravel, Symfony, Magento2, WordPress, and OpenCart
+- 📝 **PHP 8.0 - 8.5**: Support for multiple PHP versions with configurable extensions
+- 🔧 **Flexible Configuration**: Local, proxy, and production modes
+- 🔒 **Automatic HTTPS**: Let's Encrypt SSL certificates in production
+- 🎨 **Extension-Rich**: Pre-installed essential PHP extensions (PDO/MySQL, Redis, APCu, and more)
+- ⚡ **Alpine-Based**: Lightweight, fast, and efficient container images
+- 🔄 **Hot Reload**: Automatic code reloading during development
 
 ## Requirements
 
-- Docker
-- Docker Compose
-- Git (optional, for cloning)
+- Docker Desktop (or Docker Engine + Docker Compose)
+- 2GB+ RAM available
+- Terminal/Command-line access
 
 ## Quick Start
 
-1. **Clone or download the project**
-   ```bash
-   git clone <repository-url>
-   cd franken
-   ```
+### 1. Clone the Repository
 
-2. **Configure environment variables**
-   Edit the `.env` file with your preferred settings:
-   ```bash
-   # Example configuration
-   PHP_VERSION=8.2
-   FRAMEWORK=opencart  # or laravel, symfony
-   MODE=proxy          # or local, prod
-   PORT=80
-   ```
+```bash
+git clone <repository-url>
+cd franken
+```
 
-3. **Start the environment**
-   ```bash
-   docker-compose up -d
-   ```
+### 2. Configure Environment
 
-4. **Access your application**
-   - Local/Proxy mode: http://localhost:{PORT} (default: http://localhost:80)
-   - Production: https://yourdomain.com (configure DNS and SSL certificates)
+Edit the `.env` file with your preferred settings:
 
-## Configuration
+```bash
+# Core Configuration
+PHP_VERSION=8.4              # PHP version (8.0-8.5)
+FRAMEWORK=opencart           # Framework: laravel, symfony, magento2, wordpress, opencart
+MODE=proxy                   # Mode: local, prod, proxy
+PORT=80                      # Local port
+PROJECT_NAME=opencart        # Project name
 
-### Environment Variables (.env)
+# Database Configuration
+MYSQL_ROOT_PASSWORD=root
+MYSQL_DATABASE=database
+MYSQL_USER_DATABASE=app
+MYSQL_PASSWORD_DATABASE=secret
+```
 
-| Variable | Description | Options/Default |
-|----------|-------------|----------------|
-| `PHP_VERSION` | PHP version to use | `8.0`, `8.1`, `8.2`, `8.3`, `8.4`, `8.5` (default: `8.2`) |
-| `FRAMEWORK` | Target PHP framework | `opencart`, `laravel`, `symfony` (default: `opencart`) |
-| `MODE` | Environment mode | `local`, `proxy`, `prod` (default: `proxy`) |
-| `PORT` | External port for HTTP | Any available port (default: `80`) |
-| `MYSQL_ROOT_PASSWORD` | MariaDB root password | `root` |
+### 3. Start Services
+
+```bash
+docker-compose up -d
+```
+
+### 4. Access Your Application
+
+- **Local/Proxy Mode**: http://localhost:{PORT}
+  - Default: http://localhost:80
+
+## Configuration Guide
+
+### Environment Variables
+
+| Variable | Description | Options |
+|----------|-------------|---------|
+| `PHP_VERSION` | PHP version | `8.0`, `8.1`, `8.2`, `8.3`, `8.4`, `8.5` |
+| `FRAMEWORK` | Target framework | `laravel`, `symfony`, `magento2`, `wordpress`, `opencart` |
+| `MODE` | Run mode | `local` (dev), `proxy` (behind reverse proxy), `prod` (production) |
+| `PORT` | HTTP port | Any available port (default: `80`) |
+| `PROJECT_NAME` | Project identifier | Any alphanumeric name |
+| `MYSQL_ROOT_PASSWORD` | Database root password | Your secure password |
 | `MYSQL_DATABASE` | Database name | `database` |
 | `MYSQL_USER_DATABASE` | Database user | `app` |
-| `MYSQL_PASSWORD_DATABASE` | Database user password | `secret` |
-| `SERVER_NAME` | Domain for production | Your domain (leave empty for local/proxy) |
+| `MYSQL_PASSWORD_DATABASE` | Database user password | Your secure password |
+| `SERVER_NAME` | Domain (prod mode) | Your domain (e.g., `example.com`) |
+
+### Framework-Specific Setup
+
+#### Laravel
+
+1. Update `.env`:
+   ```
+   FRAMEWORK=laravel
+   ```
+
+2. Uncomment Laravel volume in `docker-compose.yml`:
+   ```yaml
+   volumes:
+     - ./www:/app          # Instead of /app/public
+   ```
+
+3. Start services:
+   ```bash
+   docker-compose up -d --build
+   ```
+
+#### Symfony
+
+1. Update `.env`:
+   ```
+   FRAMEWORK=symfony
+   ```
+
+2. Uncomment Symfony volume in `docker-compose.yml`:
+   ```yaml
+   volumes:
+     - ./www:/app          # Instead of /app/public
+   ```
+
+3. Build and start:
+   ```bash
+   docker-compose up -d --build
+   ```
+
+#### WordPress
+
+1. Update `.env`:
+   ```
+   FRAMEWORK=wordpress
+   ```
+
+2. The default volume mount `/app/public` works for WordPress
+
+3. Start services:
+   ```bash
+   docker-compose up -d --build
+   ```
+
+#### OpenCart
+
+1. Update `.env`:
+   ```
+   FRAMEWORK=opencart
+   ```
+
+2. Default configuration uses `/app/public`
+
+3. Start services:
+   ```bash
+   docker-compose up -d --build
+   ```
+
+#### Magento 2
+
+1. Update `.env`:
+   ```
+   FRAMEWORK=magento2
+   ```
+
+2. Start services:
+   ```bash
+   docker-compose up -d --build
+   ```
 
 ### Modes Explained
 
-- **local**: Development mode with internal TLS disabled
-- **proxy**: Proxy mode for use behind a reverse proxy or load balancer
-- **prod**: Production mode with HTTPS and HTTP/2/3 enabled
+- **local**: Development mode with internal TLS disabled, suitable for local development
+- **proxy**: Designed for use behind a reverse proxy or load balancer
+- **prod**: Production mode with HTTPS enabled, automatic SSL certificates, and optimized PHP settings
+
+### Production Deployment
+
+1. Update `.env`:
+   ```
+   MODE=prod
+   SERVER_NAME=yourdomain.com
+   PHP_VERSION=8.4
+   ```
+
+2. Enable HTTPS in `docker-compose.yml`:
+   ```yaml
+   ports:
+     - "443:443"           # HTTPS
+     - "443:443/udp"       # HTTP/3
+   ```
+
+3. Start services:
+   ```bash
+   docker-compose up -d --build
+   ```
+
+4. FrankenPHP automatically obtains SSL certificates from Let's Encrypt
+
+## How to Run
+
+### Start Services
+
+```bash
+# Start in background
+docker-compose up -d
+
+# Start with output
+docker-compose up
+
+# Start and rebuild images
+docker-compose up -d --build
+```
+
+### Stop Services
+
+```bash
+docker-compose down
+```
+
+### View Logs
+
+```bash
+# View all logs
+docker-compose logs -f
+
+# View specific service logs
+docker-compose logs -f php
+docker-compose logs -f db
+```
+
+### Access Container Shell
+
+```bash
+# PHP container
+docker-compose exec php sh
+
+# Database container
+docker-compose exec db mysql -u app -p
+```
+
+## Development Workflow
+
+### Running Commands Inside Container
+
+```bash
+# Composer commands
+docker-compose exec php composer install
+docker-compose exec php composer require package/name
+
+# NPM/Node commands
+docker-compose exec php npm install
+docker-compose exec php npm run dev
+docker-compose exec php npm run build
+
+# PHP CLI
+docker-compose exec php php -v
+docker-compose exec php php artisan migrate          # Laravel
+docker-compose exec php bin/console doctrine:schema  # Symfony
+
+# Database management
+docker-compose exec db mysql -u app -p database
+```
+
+### File Structure
+
+```
+franken/
+├── docker-compose.yml    # Docker services configuration
+├── Dockerfile           # Multi-stage PHP container build
+├── .env                 # Environment configuration
+├── php.ini             # Custom PHP settings
+├── www/                # Web application root
+│   └── index.php       # Entry point
+└── README.md           # This file
+```
 
 ### PHP Configuration
 
-Custom PHP settings can be added to `php.ini`. The file is mounted as a read-only volume at `/usr/local/etc/php/php.ini`.
+Edit `php.ini` to customize PHP settings:
 
-### Framework Support
+```ini
+; Example configurations
+display_errors = On
+memory_limit = 512M
+upload_max_filesize = 100M
+post_max_size = 100M
+```
 
-The environment is optimized for different PHP frameworks:
+Changes take effect after container restart:
 
-#### OpenCart (Default)
-- Container name: `opencart{PHP_VERSION}` (e.g., `opencart8.2`)
-- Web root: `./www` → `/app/public`
-- Optimized for e-commerce applications
+```bash
+docker-compose restart php
+```
 
-#### Laravel
-- Container name: `laravel{PHP_VERSION}`
-- Web root: `./www` → `/app` (uncomment in docker-compose.yml)
-- Includes storage permission fixes
+## Docker Architecture
 
-#### Symfony
-- Container name: `symfony{PHP_VERSION}`
-- Web root: `./www` → `/app` (uncomment in docker-compose.yml)
-- Includes storage permission fixes
+### Multi-Stage Build
 
-### Production Mode
+The Dockerfile uses multi-stage builds to optimize for different frameworks:
 
-For production deployment:
+- **base**: Foundation with core PHP extensions
+- **node**: Adds Node.js runtime
+- **laravel**: Laravel-specific extensions (Redis, APCu)
+- **symfony**: Symfony-specific extensions (APCu, Sodium)
+- **wordpress**: WordPress-specific configuration
+- **opencart**: OpenCart-specific configuration
+- **magento2**: Magento 2-specific configuration
 
-1. Set `MODE=prod` in `.env`
-2. Configure `SERVER_NAME` with your domain
-3. Uncomment HTTPS ports in `docker-compose.yml`:
-   ```yaml
-   ports:
-     - "443:443"     # HTTPS
-     - "443:443/udp" # HTTP/3
-   ```
-4. Set up DNS to point to your server
-5. FrankenPHP will automatically obtain SSL certificates
+### Services
 
-## Docker Services
+#### PHP Service (FrankenPHP)
 
-### PHP Service (FrankenPHP)
-- **Base Image**: `dunglas/frankenphp:php${PHP_VERSION}-alpine`
-- **Container Name**: `{FRAMEWORK}{PHP_VERSION}` (e.g., `opencart8.2`)
-- **Features**:
-  - HTTP/2 and HTTP/3 support
-  - Automatic HTTPS with Let's Encrypt
-  - Built-in Caddy web server
-  - PHP-FPM compatibility
-  - Node.js runtime included
+- **Image**: `dunglas/frankenphp:php{PHP_VERSION}-alpine`
+- **Includes**: 
+  - PHP 8.0-8.5
+  - Node.js v20.x
+  - Caddy web server
+  - Framework-specific extensions
+
+#### Database Service (MariaDB)
 
-### Database Service (MariaDB)
 - **Image**: `mariadb:latest`
-- **Features**:
-  - Persistent data storage
-  - User and database creation
-  - Optimized for web applications
+- **Volume**: `db_data` (persistent)
+- **Port**: `3306` (internal)
 
-## PHP Extensions Included
+### Network & Volumes
 
-The environment includes a comprehensive set of PHP extensions:
+```yaml
+networks:
+  app-network:           # Internal communication
+    driver: bridge
+
+volumes:
+  caddy_data:           # Caddy cache and data
+  caddy_config:         # Caddy configuration
+  db_data:              # Database persistence
+```
+
+## PHP Extensions
+
+### Core Extensions
 
 - **Database**: `pdo_mysql`, `mysqli`
-- **Image Processing**: `gd`, `imagick`, `exif`
-- **Internationalization**: `intl`, `mbstring`, `iconv`
-- **Data Formats**: `xml`, `dom`, `simplexml`, `zip`, `json`
-- **Security**: `openssl`, `sodium`
-- **Performance**: `opcache`, `apcu`, `redis`
-- **Utilities**: `curl`, `fileinfo`, `ctype`, `tokenizer`, `bcmath`, `soap`, `sqlite3`, `xsl`
+- **String**: `mbstring`, `ctype`, `iconv`
+- **Data**: `xml`, `dom`, `simplexml`, `fileinfo`
+- **Security**: `openssl`, `tokenizer`
+- **Utilities**: `curl`, `zip`, `intl`, `opcache`
 
-## Development Workflow
+### Framework-Specific Extensions
 
-1. **Code Changes**: Edit files in the `www/` directory
-2. **Database Access**: Connect to `localhost:3306` with configured credentials
-3. **Node.js Usage**: Run npm/yarn commands in the container:
+**Laravel/Magento2**:
+- `redis`: Redis cache support
+
+**Symfony**:
+- `apcu`: APCu caching
+- `sodium`: Modern cryptography
+
+## Troubleshooting
+
+### Port Already in Use
+
+```bash
+# Change PORT in .env and restart
+PORT=8080 docker-compose up -d
+```
+
+### Database Connection Issues
+
+Verify credentials in `.env`:
+
+```bash
+docker-compose exec php php -r "
+\$db = new mysqli('db', 'app', 'secret', 'database');
+if (\$db->connect_error) exit('Connection failed: ' . \$db->connect_error);
+echo 'Connected successfully!';
+"
+```
+
+### Permission Issues
+
+```bash
+# Fix permissions in www directory
+chmod -R 755 www/
+```
+
+### Rebuild Everything
+
+```bash
+docker-compose down -v
+docker-compose up --build -d
+```
+
+### Check Container Status
+
+```bash
+docker-compose ps
+docker-compose logs -f
+```
+
+## Useful Commands
+
+```bash
+# List running containers
+docker-compose ps
+
+# Restart a service
+docker-compose restart php
+
+# Rebuild images
+docker-compose build --no-cache
+
+# Execute command in container
+docker-compose exec php <command>
+
+# Copy files from container
+docker cp <container>:/path/to/file ./local/path
+
+# View resource usage
+docker stats
+```
+
+## Performance Optimization
+
+### For Production
+
+1. Set `MODE=prod` in `.env`
+2. Enable opcache in `php.ini`:
+   ```ini
+   opcache.enable=1
+   opcache.memory_consumption=256
+   ```
+3. Configure Redis for caching:
    ```bash
-   docker-compose exec php npm install
-   docker-compose exec php npm run build
+   docker-compose exec php redis-cli
    ```
-4. **Logs**: View container logs with `docker-compose logs -f`
-5. **Rebuild**: After Dockerfile changes: `docker-compose up --build`
 
-## File Structure
+### Database Optimization
 
-```
-franken/
-├── docker-compose.yml    # Docker services configuration
-├── Dockerfile           # PHP container build instructions
-├── .env                 # Environment variables
-├── php.ini             # Custom PHP configuration
-├── www/                # Web application files
-│   └── index.php       # Sample PHP file
-└── README.md           # This file
-```
+1. Set appropriate `MYSQL_ROOT_PASSWORD`
+2. Monitor with:
+   ```bash
+   docker-compose exec db mysql -u root -p -e "SHOW PROCESSLIST;"
+   ```
 
-## Troubleshooting
+## Security Best Practices
 
-### Common Issues
-
-1. **Port conflicts**: Change the `PORT` variable in `.env`
-2. **Permission issues**: Ensure proper file permissions in `www/` directory
-3. **Database connection**: Verify credentials in `.env` match application config
-4. **SSL issues**: Check domain configuration and DNS propagation
-5. **Framework switching**: Update `FRAMEWORK` in `.env` and rebuild containers
-
-### Useful Commands
-
-```bash
-# View logs
-docker-compose logs -f
-
-# Access container shell
-docker-compose exec php sh
-
-# Run Node.js commands
-docker-compose exec php npm install
-docker-compose exec php npm run dev
-
-# Restart services
-docker-compose restart
-
-# Rebuild and restart
-docker-compose up --build -d
-
-# Stop and remove containers
-docker-compose down
-
-# Clean up volumes (WARNING: deletes data)
-docker-compose down -v
-```
+- ✅ Change default database credentials in `.env`
+- ✅ Use strong passwords for `MYSQL_ROOT_PASSWORD` and `MYSQL_PASSWORD_DATABASE`
+- ✅ Set `MODE=prod` for production deployments
+- ✅ Keep `php.ini` locked to read-only (default)
+- ✅ Use environment variables for sensitive data
+- ✅ Keep Docker images updated
 
 ## Contributing
 
 1. Fork the repository
-2. Create a feature branch
+2. Create a feature branch (`git checkout -b feature/improvement`)
 3. Make your changes
 4. Test thoroughly
-5. Submit a pull request
+5. Commit with clear messages (`git commit -am 'Add improvement'`)
+6. Push to your fork (`git push origin feature/improvement`)
+7. Open a Pull Request
 
 ## License
 
 [Specify your license here]
 
-## Support
+## Support & Resources
 
-For issues and questions:
-- Check the troubleshooting section
-- Review FrankenPHP documentation: https://frankenphp.dev/
-- Open an issue in the repository
+- **FrankenPHP Docs**: https://frankenphp.dev/
+- **Caddy Docs**: https://caddyserver.com/docs/
+- **Docker Docs**: https://docs.docker.com/
+- **Compose Docs**: https://docs.docker.com/compose/
 
 ## Changelog
 
-### [Latest Version]
-- Added Node.js integration for frontend tooling
-- Enhanced PHP extensions (Redis, APCu, ImageMagick, etc.)
-- Framework-specific container naming
-- Added proxy mode for reverse proxy setups
-- Improved volume management and networking
-- Updated configuration options and documentation
-- **Image**: `dunglas/frankenphp:php${PHP_VERSION}-alpine`
-- **Features**:
-  - HTTP/2 and HTTP/3 support
-  - Automatic HTTPS with Let's Encrypt
-  - Built-in Caddy web server
-  - PHP-FPM compatibility
+### v1.1.0 (Current)
+- Multi-stage Docker build for framework-specific optimization
+- Node.js v20.x integration
+- Support for 5+ PHP frameworks with dedicated configurations
+- Improved documentation and examples
+- Production mode with automatic HTTPS
 
-### Database Service (MariaDB)
-- **Image**: `mariadb:latest`
-- **Features**:
-  - Persistent data storage
-  - User and database creation
-  - Optimized for web applications
+### v1.0.0
+- Initial release with FrankenPHP and MariaDB
+- Basic framework support
+- Development and production modes
 
-## Development Workflow
+---
 
-1. **Code Changes**: Edit files in the `www/` directory
-2. **Database Access**: Connect to `localhost:3306` with configured credentials
-3. **Logs**: View container logs with `docker-compose logs -f`
-4. **Rebuild**: After Dockerfile changes: `docker-compose up --build`
-
-## File Structure
-
-```
-franken/
-├── docker-compose.yml    # Docker services configuration
-├── Dockerfile           # PHP container build instructions
-├── .env                 # Environment variables
-├── php.ini             # Custom PHP configuration
-├── www/                # Web application files
-│   └── index.php       # Sample PHP file
-└── README.md           # This file
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Port conflicts**: Change port mappings in `docker-compose.yml`
-2. **Permission issues**: Ensure proper file permissions in `www/` directory
-3. **Database connection**: Verify credentials in `.env` match application config
-4. **SSL issues**: Check domain configuration and DNS propagation
-
-### Useful Commands
-
-```bash
-# View logs
-docker-compose logs -f
-
-# Restart services
-docker-compose restart
-
-# Rebuild and restart
-docker-compose up --build -d
-
-# Stop and remove containers
-docker-compose down
-
-# Clean up volumes (WARNING: deletes data)
-docker-compose down -v
-```
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Test thoroughly
-5. Submit a pull request
-
-## License
-
-[Specify your license here]
-
-## Support
-
-For issues and questions:
-- Check the troubleshooting section
-- Review FrankenPHP documentation: https://frankenphp.dev/
-- Open an issue in the repository
-
-## Changelog
-
-### [Version]
-- Initial release with FrankenPHP and MariaDB support
-- Support for multiple PHP frameworks
-- Development and production mode configurations
\ No newline at end of file
+**Last Updated**: March 2026  
+**Maintainer**: Development Team