Frankenphp Symfony Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require runtime/frankenphp-symfony
   

   Ensure your composer.json includes the package under require.

2. Configure Environment Set APP_RUNTIME to Runtime\FrankenPhpSymfony\Runtime in your .env or deployment environment:

   APP_RUNTIME=Runtime\FrankenPhpSymfony\Runtime
   

3. Docker Deployment (Example) Use the provided Docker snippet, adjusting paths and ports as needed:

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

4. Kernel Bootstrapping Update public/index.php to use the Symfony Runtime autoloader:

   require_once dirname(__DIR__) . '/vendor/autoload_runtime.php';
   
   return function (array $context) {
       return new Kernel($context['APP_ENV'] ?? 'dev', (bool) ($context['APP_DEBUG'] ?? false));
   };
   

5. Verify Runtime Check logs (docker logs <container>) for confirmation of FrankenPHP-Symfony initialization.

First Use Case: Local Development

• Use APP_RUNTIME in .env.local for local testing.
• Test with FRANKENPHP_CONFIG="worker ./public/index.php" to validate FrankenPHP integration.
• Debug via docker exec -it <container> sh if issues arise.

Implementation Patterns

Workflow: Symfony + FrankenPHP Integration

1. Runtime Configuration

   • Set FRANKENPHP_CONFIG to define worker behavior (e.g., worker ./public/index.php).
   • Use frankenphp_loop_max (default: 500) to manage worker restarts:

     FRANKENPHP_CONFIG="worker ./public/index.php --loop-max 1000"
     

2. Dependency Injection

   • FrankenPHP-Symfony extends Symfony’s Runtime component, so existing ContainerBuilder or Kernel logic remains unchanged.
   • Leverage Symfony’s Context for environment-aware configurations (e.g., APP_ENV, APP_DEBUG).

3. Hybrid Request Handling

   • FrankenPHP’s PHP worker handles HTTP requests directly, bypassing traditional web servers (e.g., Nginx/Apache).
   • Use Symfony’s HttpKernel for routing, controllers, and middleware as usual.

4. Static Asset Serving

   • FrankenPHP serves static files natively (no Nginx needed). Configure via:

     FRANKENPHP_CONFIG="static ./public --index index.php"
     

5. Event-Driven Extensions

   • Hook into Symfony events (e.g., Kernel::TERMINATE) to interact with FrankenPHP’s lifecycle:

     // config/services.yaml
     App\EventListener\FrankenPhpListener:
         tags:
             - { name: kernel.event_listener, event: kernel.terminate, method: onTerminate }
     

Integration Tips

• Docker Compose: Use multi-stage builds to separate runtime and build contexts.
• CI/CD: Validate APP_RUNTIME in pipelines before deployment.
• Debugging: FrankenPHP logs to stdout; redirect to a file for persistence:

  docker run ... | tee frankenphp.log
  

• Performance: Monitor frankenphp_loop_max to balance memory leaks and restarts.

Gotchas and Tips

Pitfalls

1. Environment Variable Order

   • APP_RUNTIME must be set before Symfony’s DotenvComponent loads (e.g., via Docker -e or .env).
   • Fix: Ensure .env is loaded last or use explicit APP_RUNTIME in docker run.

2. Worker Restarts

   • Setting frankenphp_loop_max: -1 disables restarts, risking memory leaks in long-running apps.
   • Tip: Start with 500 and adjust based on memory profiles.

3. Static File Caching

   • FrankenPHP’s static file serving lacks Nginx’s caching headers. Use middleware to add Cache-Control:

     // src/EventListener/AddCacheHeadersListener.php
     public function onKernelRequest(RequestEvent $event) {
         $request = $event->getRequest();
         if ($request->isMethod('GET') && $request->getPathInfo() === '/static/file.jpg') {
             $response = $event->getResponse();
             $response->headers->set('Cache-Control', 'public, max-age=31536000');
         }
     }
     

4. Symfony Runtime Conflicts

   • Avoid mixing Runtime\Symfony\Runtime and Runtime\FrankenPhpSymfony\Runtime in the same app.
   • Fix: Stick to one runtime per project.

5. PHP Version Mismatch

   • FrankenPHP requires PHP 8.1+. Verify compatibility with your Symfony version (e.g., Symfony 6.4+).

Debugging

1. Logs

   • FrankenPHP logs to stdout. Use:

     docker logs --follow <container> | grep -i "frankenphp\|symfony"
     

   • Enable Symfony debug mode (APP_DEBUG=1) for stack traces.

2. Worker Isolation

   • If a worker crashes, check for unhandled exceptions in Symfony’s ErrorListener.
   • Tip: Use try-catch in public/index.php for graceful failures:

     return function (array $context) {
         try {
             return new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
         } catch (\Throwable $e) {
             file_put_contents('/tmp/runtime_error.log', $e->getMessage());
             throw $e;
         }
     };
     

3. Configuration Validation

   • Validate FRANKENPHP_CONFIG syntax. Example:

     FRANKENPHP_CONFIG="worker ./public/index.php --loop-max 500 --static ./public"
     

   • Gotcha: Missing --static may cause 404s for assets.

Extension Points

1. Custom Runtime Classes

   • Extend Runtime\FrankenPhpSymfony\Runtime to add pre/post-request hooks:

     class CustomRuntime extends Runtime\FrankenPhpSymfony\Runtime {
         public function __construct() {
             parent::__construct();
             $this->on('request', [$this, 'logRequest']);
         }
     
         public function logRequest(ServerRequestInterface $request) {
             file_put_contents(
                 '/tmp/requests.log',
                 $request->getUri() . "\n",
                 FILE_APPEND
             );
         }
     }
     

   • Register via APP_RUNTIME=App\CustomRuntime.

2. FrankenPHP CLI Commands

   • Use FRANKENPHP_CONFIG to enable CLI tools (e.g., cli ./bin/console):

     FRANKENPHP_CONFIG="cli ./bin/console"
     

   • Tip: Combine with Symfony’s ConsoleApplication for unified CLI/runtime.

3. Dynamic Configuration

   • Override getContext() in a custom runtime to inject dynamic values:

     public function getContext(): array {
         $context = parent::getContext();
         $context['CUSTOM_VAR'] = 'dynamic_value';
         return $context;
     }