Laravel FrankenPHP Test Bench

A Docker-based Laravel development environment with FrankenPHP.

Description

This project provides a complete Docker environment for running Laravel applications with FrankenPHP, which combines the Caddy web server and PHP runtime in a single process. It includes:

• Laravel application container (FrankenPHP)
• Properly configured Docker setup for local development
• Performance testing capabilities with autocannon
• Automated testing script for verification
• Redis caching layer for improved performance

FrankenPHP is a modern PHP application server that replaces traditional PHP-FPM setups with better performance and simpler configuration. This test bench demonstrates the benefits of using FrankenPHP for Laravel applications.

Prerequisites

• Docker
• Docker Compose

Setup

1. Clone the repository:

   git clone <repository-url>
   cd laravel-franken-nginx-test-bench
   

2. (Optional) Run the environment diagnostic script to check your system:

   • Windows: Run docker-diag.bat

3. Build and start the containers:

   docker-compose up -d --build
   

4. The application will be available at http://localhost:8000

5. (Optional) HTTPS is available at https://localhost:8443 (you'll need to accept the self-signed certificate)

Note: The first build may take a few minutes as it installs all the required PHP extensions.

If you encounter issues during setup, try using the troubleshooting scripts:

• Windows: Run docker-troubleshoot.bat
• PowerShell: Run docker-troubleshoot.ps1

Project Structure

• Dockerfile: Configuration for the Laravel application container with FrankenPHP
• docker-compose.yml: Docker Compose configuration
• Caddyfile: Caddy server configuration for FrankenPHP
• docker-entrypoint.sh: Entry point script for the application container

API Endpoints

• GET /api/hello - Returns a simple JSON response with a "Hello World" message
• GET /api/cache-test - Tests Redis caching functionality
• GET /api/redis-status - Checks Redis connection status

Running Tests

Autocannon Performance Tests

Run basic performance test:

autocannon http://localhost:8000/api/hello

Run intensive test with 50 connections for 30 seconds:

autocannon -c 50 -d 30 http://localhost:8000/api/hello

Run high-load test with 100 connections for 20 seconds:

autocannon -c 100 -d 20 http://localhost:8000/api/hello

Automated Testing

Run the automated test script to verify the setup:

bash test-frankenphp.sh

The test script will:

• Check if the Docker container is running
• Verify the API endpoint is responding correctly
• Display the response from the API

Redis Testing

See REDIS-TESTING.md for detailed instructions on testing the Redis implementation.

Caddyfile Configuration

The Caddyfile in this project is configured specifically for Laravel applications:

• Uses php_server directive to handle PHP files directly within FrankenPHP
• Includes proper routing for Laravel's front controller pattern
• Adds security headers for better application security
• Enables compression for improved performance
• Configures logging for easier debugging

Docker Commands

• Start containers: docker-compose up -d
• Stop containers: docker-compose down
• View logs: docker-compose logs
• Check container status: docker-compose ps

Note: Two containers will be running:

• laravel_frankenphp - The main Laravel application container
• laravel_redis - The Redis caching service

Benefits of FrankenPHP

FrankenPHP offers several advantages over traditional PHP-FPM setups:

1. Better Performance: FrankenPHP embeds PHP directly into the Caddy web server, eliminating the need for FastCGI protocol overhead.

2. Simpler Configuration: A single container replaces both Nginx and PHP-FPM containers, reducing complexity.

3. Built-in Features: FrankenPHP includes HTTPS, HTTP/2, HTTP/3, automatic certificates, and more out of the box.

4. Worker Mode: FrankenPHP supports a worker mode that preloads the PHP application, significantly reducing response times for Laravel applications. This is configured through the FRANKENPHP_CONFIG environment variable.

5. Modern Architecture: FrankenPHP is built with modern Go and PHP technologies for improved reliability and performance.

Configuration

Environment Variables

The application uses a standard Laravel .env file for configuration. Redis is configured with:

• CACHE_DRIVER=redis
• REDIS_HOST=redis
• REDIS_PORT=6379

Docker Configuration

• Port mapping: 8000 (host) -> 80 (FrankenPHP container)
• Volume mapping: Current directory is mapped to /app in the container
• Worker Mode: Configured to preload Laravel application for better performance

The FrankenPHP container is configured to run in worker mode by setting the FRANKENPHP_CONFIG environment variable to worker ./public/index.php. This preloads the Laravel application, reducing the response time for subsequent requests.

The Redis container is configured as a separate service in the Docker Compose file.

Caddy Configuration

The Caddy server is configured through the Caddyfile which includes:

• PHP server configuration for handling Laravel requests
• Security headers for improved security
• Compression for better performance
• Proper routing for Laravel's front controller pattern

Redis Caching

This setup includes Redis as a caching layer with the following features:

1. Redis service running in a separate container
2. PHP Redis extension installed and configured
3. Laravel configured to use Redis for caching
4. Custom API endpoints to test caching functionality
5. Laravel command for testing Redis connectivity

See REDIS-TESTING.md for detailed testing instructions.

Troubleshooting

Common Issues

1. 500 Internal Server Error:

   • Check if all required Laravel configuration files exist in the config directory
   • Ensure proper permissions on storage directories

2. Connection Refused:

   • Verify that containers are running with docker-compose ps
   • Check container logs with docker-compose logs

3. Redis Connection Issues:

   • Verify that the Redis container is running
   • Check Redis container logs with docker-compose logs redis
   • Ensure the Redis configuration in .env is correct

4. Docker Desktop Issues:

   • Error: open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified
   • This error typically occurs when Docker Desktop's Linux container engine isn't running properly
   • Solutions:
     1. Close Docker Desktop completely
     2. Restart Docker Desktop as an administrator
     3. Ensure it's set to use Linux containers (not Windows containers)
     4. If the issue persists, try resetting Docker to factory defaults
     5. Run the provided troubleshooting scripts (docker-troubleshoot.bat or docker-troubleshoot.ps1)

5. Port Conflicts:

   • If port 8000 is already in use, either:
     • Stop the process using the port: netstat -ano | findstr :8000 then taskkill /PID <pid> /F
     • Or change the port mapping in docker-compose.yml

Checking Container Logs

docker-compose logs --tail=20

Performance

The application has been tested with autocannon and performs well under various loads:

Test 1: Basic Load (10 connections, 10 seconds)

• Requests: 477
• Latency: Average 213.96ms
• Throughput: 46.7 requests/second
• Data: 137 kB read

Note: Performance may vary based on system resources and current load.

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

License

This project is open source and available under the MIT License.