DDEV FrankenPHP

Overview

FrankenPHP is a modern application server for PHP built on top of the Caddy web server.

This add-on integrates FrankenPHP into your DDEV project as an extra service.

Running it as a separate service lets you install additional PHP extensions. This differs from the official quckstart and another add-on, which bundle a static FrankenPHP build inside the web container.

Installation

ddev config --webserver-type=generic
ddev add-on get stasadev/ddev-frankenphp
ddev restart

After installation, make sure to commit the .ddev directory to version control.

Usage

Caveats

• To make Xdebug available on the host, create a .ddev/docker-compose.frankenphp_extra.yaml file:
  • For Linux and WSL2:

    services:
      frankenphp:
        extra_hosts:
          - "host.docker.internal:host-gateway"
    

  • For other setups, replace IP_ADDRESS with IP from the ddev exec ping -c1 host.docker.internal command:

    services:
      frankenphp:
        extra_hosts:
          - "host.docker.internal:IP_ADDRESS"
    

• ddev xdebug is only designed to work in the web container, it won’t work here.
• ddev launch doesn’t work. Open the website URL directly in your browser.

Advanced Customization

To change the Docker image:

ddev dotenv set .ddev/.env.frankenphp --frankenphp-docker-image="dunglas/frankenphp:php8.3"
ddev add-on get stasadev/ddev-frankenphp
ddev stop && ddev debug rebuild -s frankenphp && ddev start

Make sure to commit the .ddev/.env.frankenphp file to version control.

To add PHP extensions (see supported extensions here):

ddev dotenv set .ddev/.env.frankenphp --frankenphp-php-extensions="opcache xdebug spx"
ddev add-on get stasadev/ddev-frankenphp
ddev stop && ddev debug rebuild -s frankenphp && ddev start

Make sure to commit the .ddev/.env.frankenphp file to version control.

All customization options (use with caution):

Resources:

• FrankenPHP Documentation

Credits

Contributed and maintained by @stasadev