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

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. Build and start the containers:

   docker-compose up -d --build
   

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

4. (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.

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

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

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: Only one container (laravel_frankenphp) will be running, as FrankenPHP replaces both the Nginx and PHP-FPM containers.

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.

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.

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

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

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.