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

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

## Requirements

- Docker
- Docker Compose
- Git (optional, for cloning)

## Quick Start

1. **Clone or download the project**
   ```bash
   git clone <repository-url>
   cd franken
   ```

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

3. **Start the environment**
   ```bash
   docker-compose up -d
   ```

4. **Access your application**
   - Local/Proxy mode: http://localhost:{PORT} (default: http://localhost:80)
   - Production: https://yourdomain.com (configure DNS and SSL certificates)

## Configuration

### Environment Variables (.env)

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

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

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

### Framework Support

The environment is optimized for different PHP frameworks:

#### OpenCart (Default)
- Container name: `opencart{PHP_VERSION}` (e.g., `opencart8.2`)
- Web root: `./www` → `/app/public`
- Optimized for e-commerce applications

#### Laravel
- Container name: `laravel{PHP_VERSION}`
- Web root: `./www` → `/app` (uncomment in docker-compose.yml)
- Includes storage permission fixes

#### Symfony
- Container name: `symfony{PHP_VERSION}`
- Web root: `./www` → `/app` (uncomment in docker-compose.yml)
- Includes storage permission fixes

### Production Mode

For production deployment:

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

## Docker Services

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

### Database Service (MariaDB)
- **Image**: `mariadb:latest`
- **Features**:
  - Persistent data storage
  - User and database creation
  - Optimized for web applications

## PHP Extensions Included

The environment includes a comprehensive set of PHP 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`

## Development Workflow

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:
   ```bash
   docker-compose exec php npm install
   docker-compose exec php npm run build
   ```
4. **Logs**: View container logs with `docker-compose logs -f`
5. **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 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
```

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

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

### Database Service (MariaDB)
- **Image**: `mariadb:latest`
- **Features**:
  - Persistent data storage
  - User and database creation
  - Optimized for web applications

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