DDEV FrankenPHP

See the blog Using FrankenPHP with DDEV.

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, which bundles 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

Command	Description
ddev describe	View service status and ports used by FrankenPHP
ddev php	Run PHP in the FrankenPHP container
ddev xdebug on	Enable Xdebug in the FrankenPHP container
ddev xdebug off	Disable Xdebug in the FrankenPHP container
ddev exec -s frankenphp bash	Enter the FrankenPHP container
ddev logs -s frankenphp -f	View FrankenPHP logs

Caveats

• ddev xhprof and ddev xhgui are only designed to work in the web container, it won't work here.

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="redis pdo_mysql"
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 modify the default Caddyfile configuration, create a file .ddev/docker-compose.frankenphp_extra.yaml with the following content:

# See all configurable variables in
# https://github.com/php/frankenphp/blob/main/caddy/frankenphp/Caddyfile
services:
  frankenphp:
    environment:
      # enable worker script
      # change some php.ini settings
      FRANKENPHP_CONFIG: |
        worker ${DDEV_DOCROOT:-.}/index.php
        php_ini {
          memory_limit 256M
          max_execution_time 15
        }
      # add a stub for Mercure module
      CADDY_SERVER_EXTRA_DIRECTIVES: |
        # mercure {
        #   ...
        # }

---

All customization options (use with caution):

Variable	Flag	Default
FRANKENPHP_DOCKER_IMAGE	--frankenphp-docker-image	dunglas/frankenphp:php8.3
FRANKENPHP_PHP_EXTENSIONS	--frankenphp-php-extensions	(not set)

Resources:

• FrankenPHP Documentation
• Using FrankenPHP with DDEV
• DDEV FrankenPHP Benchmark

Credits

Contributed and maintained by @stasadev