php-container/README.md

# FrankenPHP Docker Environment

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 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 Desktop (or Docker Engine + Docker Compose)
- 2GB+ RAM available
- Terminal/Command-line access

## Quick Start

### 1. Clone the Repository

```bash
git clone <repository-url>
cd franken
```

### 2. Configure Environment

```bash
cp .env.example .env
```

Edit the `.env` file with your preferred settings:

```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

# Database Configuration
MYSQL_ROOT_PASSWORD=root
MYSQL_DATABASE=database
MYSQL_USER_DATABASE=app
MYSQL_PASSWORD_DATABASE=secret
```

### 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 | 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, 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

Edit `php.ini` to customize PHP settings:

```ini
; Example configurations
display_errors = On
memory_limit = 512M
upload_max_filesize = 100M
post_max_size = 100M
```

Changes take effect after container restart:

```bash
docker-compose restart php
```

## Docker Architecture

### Multi-Stage Build

The Dockerfile uses multi-stage builds to optimize for different frameworks:

- **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

### Services

#### PHP Service (FrankenPHP)

- **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)

- **Image**: `mariadb:latest`
- **Volume**: `db_data` (persistent)
- **Port**: `3306` (internal)

### Network & Volumes

```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`
- **String**: `mbstring`, `ctype`, `iconv`
- **Data**: `xml`, `dom`, `simplexml`, `fileinfo`
- **Security**: `openssl`, `tokenizer`
- **Utilities**: `curl`, `zip`, `intl`, `opcache`

### Framework-Specific Extensions

**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 redis-cli
   ```

### Database Optimization

1. Set appropriate `MYSQL_ROOT_PASSWORD`
2. Monitor with:
   ```bash
   docker-compose exec db mysql -u root -p -e "SHOW PROCESSLIST;"
   ```

## Security Best Practices

- ✅ 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 (`git checkout -b feature/improvement`)
3. Make your changes
4. Test thoroughly
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 & Resources

- **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

### 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

### v1.0.0
- Initial release with FrankenPHP and MariaDB
- Basic framework support
- Development and production modes

---

**Last Updated**: March 2026  
**Maintainer**: Development Team