frankenphp

What this skill does

# FrankenPHP Skill

Comprehensive assistance with FrankenPHP development - a modern PHP application server built on top of the Caddy web server. FrankenPHP enables persistent PHP processes with worker mode, automatic HTTPS, HTTP/2, HTTP/3, and real-time capabilities via Mercure integration.

## When to Use This Skill

This skill should be triggered when:
- Setting up or configuring FrankenPHP server
- Implementing FrankenPHP worker mode for performance optimization
- Integrating FrankenPHP with Laravel, Symfony, or other PHP frameworks
- Deploying PHP applications with Docker using FrankenPHP
- Converting traditional PHP apps to use persistent workers
- Configuring automatic HTTPS, HTTP/2, or HTTP/3
- Implementing real-time features with Mercure
- Creating standalone, self-executable PHP applications
- Optimizing PHP application performance with persistent processes
- Troubleshooting FrankenPHP worker mode or configuration issues

## Quick Reference

### Installation & Basic Server

**Install via curl (Linux/macOS):**
```bash
curl https://frankenphp.dev/install.sh | sh
mv frankenphp /usr/local/bin/

# Start server in current directory
frankenphp php-server
```

**Install via Homebrew:**
```bash
brew install dunglas/frankenphp/frankenphp
frankenphp php-server
```

**Quick Docker deployment:**
```bash
docker run -v $PWD:/app/public \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp
```

### Basic Worker Mode

**Start worker with standalone binary:**
```bash
frankenphp php-server --worker /path/to/your/worker/script.php
```

**Docker with worker mode:**
```bash
docker run \
    -e FRANKENPHP_CONFIG="worker /app/public/index.php" \
    -v $PWD:/app \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp
```

**Worker with 42 processes:**
```bash
docker run \
    -e FRANKENPHP_CONFIG="worker ./public/index.php 42" \
    -v $PWD:/app \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp
```

### Custom Worker Script

**Basic worker pattern:**
```php
<?php
// public/index.php

ignore_user_abort(true);

require __DIR__.'/vendor/autoload.php';

$myApp = new \App\Kernel();
$myApp->boot();

$handler = static function () use ($myApp) {
    try {
        echo $myApp->handle($_GET, $_POST, $_COOKIE, $_FILES, $_SERVER);
    } catch (\Throwable $exception) {
        (new \MyCustomExceptionHandler)->handleException($exception);
    }
};

$maxRequests = (int)($_SERVER['MAX_REQUESTS'] ?? 0);
for ($nbRequests = 0; !$maxRequests || $nbRequests < $maxRequests; ++$nbRequests) {
    $keepRunning = \frankenphp_handle_request($handler);
    $myApp->terminate();
    gc_collect_cycles();
    if (!$keepRunning) break;
}

$myApp->shutdown();
```

### Laravel Integration

**Laravel Octane installation:**
```bash
composer require laravel/octane
php artisan octane:install --server=frankenphp
php artisan octane:frankenphp
```

**Laravel with Docker:**
```bash
docker run -p 80:80 -p 443:443 -p 443:443/udp \
    -v $PWD:/app \
    dunglas/frankenphp
```

**Laravel Caddyfile:**
```
{
	frankenphp
}

localhost {
	root public/
	encode zstd br gzip
	php_server {
		try_files {path} index.php
	}
}
```

**Octane with file watching:**
```bash
php artisan octane:frankenphp --watch
```

### Symfony Integration

**Symfony worker with runtime:**
```bash
composer require runtime/frankenphp-symfony

docker run \
    -e FRANKENPHP_CONFIG="worker ./public/index.php" \
    -e APP_RUNTIME=Runtime\\FrankenPhpSymfony\\Runtime \
    -v $PWD:/app \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp
```

### Worker Management

**Watch files for changes (auto-reload):**
```bash
frankenphp php-server --worker /path/to/worker.php \
    --watch="/path/to/your/app/**/*.php"
```

**Restart workers via API:**
```bash
curl -X POST http://localhost:2019/frankenphp/workers/restart
```

**Configure max consecutive failures (Caddyfile):**
```
frankenphp {
    worker {
        max_consecutive_failures 10
    }
}
```

### Superglobals in Worker Mode

**Accessing worker-bound vs request-bound values:**
```php
<?php
// Capture worker-level values before request loop
$workerServer = $_SERVER;

$handler = static function () use ($workerServer) {
    var_dump($_SERVER);      // Current request superglobals
    var_dump($workerServer); // Original worker values
};
```

## Key Concepts

### Worker Mode
FrankenPHP's worker mode keeps your PHP application loaded in memory between requests, dramatically improving performance. Instead of bootstrapping your application for each request (traditional PHP), the application boots once and handles thousands of requests with the same process.

**Benefits:**
- Boot your application once, handle requests in milliseconds
- Persistent database connections
- Preloaded classes and configuration
- Significantly reduced memory overhead

**Key Pattern:** Use `frankenphp_handle_request($handler)` to process each request within a persistent loop, calling `gc_collect_cycles()` after each request to prevent memory leaks.

### Caddy Integration
FrankenPHP is built on top of Caddy, meaning you get:
- **Automatic HTTPS** - Zero-config TLS certificates via Let's Encrypt
- **HTTP/2 & HTTP/3** - Modern protocol support out of the box
- **Powerful configuration** - Use Caddyfile for server configuration

### Early Hints (103 Status)
FrankenPHP supports HTTP 103 Early Hints, allowing browsers to start loading critical resources (CSS, JS, fonts) while the server is still generating the full response.

### Mercure Real-Time
Built-in support for Mercure protocol enables real-time push notifications from server to browser using Server-Sent Events (SSE). Perfect for live updates, notifications, and collaborative features.

## Reference Files

This skill includes comprehensive documentation in `references/`:

- **other.md** - Core FrankenPHP documentation including installation, configuration, worker mode, framework integration, deployment, and production setup

The reference file contains detailed information from the official FrankenPHP documentation at https://frankenphp.dev/docs/

Use the reference file when you need:
- Detailed installation instructions for different platforms
- Advanced Caddyfile configuration examples
- Framework-specific integration patterns (Laravel, Symfony, WordPress, etc.)
- Production deployment strategies
- Performance optimization techniques
- Static binary compilation guides
- Docker configuration options

## Working with This Skill

### For Beginners
1. **Start with basic installation** - Use the curl install script or Docker for quickest setup
2. **Run traditional PHP first** - Use `frankenphp php-server` without worker mode to verify setup
3. **Test with simple scripts** - Create a basic `index.php` to understand the server behavior
4. **Learn Caddyfile basics** - Understand how to configure domains and paths
5. **Gradually adopt worker mode** - Once comfortable, convert to worker mode for performance

### For Laravel Developers
1. **Use Laravel Octane** - The official integration provides the smoothest experience
2. **Start with Docker** - Use the official `dunglas/frankenphp` image
3. **Configure Mercure** - Add real-time capabilities to your Laravel app
4. **Optimize workers** - Tune worker count based on your traffic patterns
5. **Use file watching** - Enable `--watch` during development for auto-reload

### For Symfony Developers
1. **Install Symfony runtime** - Use `runtime/frankenphp-symfony` package
2. **Set APP_RUNTIME** - Configure environment variable for automatic integration
3. **Use worker mode** - Leverage persistent processes for maximum performance
4. **Deploy with Docker** - Use official containers for production

### For Production Deployment
1. **Review worker configuration** - Set appropriate worker count and max requests
2. **Configure failure handling** - Set `max_consecutive_failures` threshold
3. **Enable monitoring** - Use Caddy admin API for health checks and metrics
4. **Set up log analytics** - Config