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.

Note

FrankenPHP support is available for PHP 8.2+ ZTS (Zend Thread Safety) versions only.

Installation

ddev add-on get ddev/ddev-frankenphp
ddev restart

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

Usage

Command	Description
ddev describe	View project status
ddev php -v	Check installed PHP ZTS version
ddev exec frankenphp -v	Check installed FrankenPHP version
ddev php -m	View installed PHP extensions
ddev logs -f	View FrankenPHP logs

Tip

FrankenPHP is updated automatically when you update DDEV.

To update it manually, run ddev utility rebuild.

Advanced Customization

Install pre-packaged extensions using the php-zts- prefix (see supported extensions):

# install mongodb and sqlsrv extensions
ddev config --webimage-extra-packages="php-zts-mongodb,php-zts-sqlsrv"
ddev restart

For extensions not available as pre-packaged, use PHP/PIE, create a file .ddev/web-build/Dockerfile.frankenphp_extra with the following content:

# .ddev/web-build/Dockerfile.frankenphp_extra
# Replace asgrim/example-pie-extension with the desired extension https://packagist.org/extensions
RUN (apt-get update || true) && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y -o Dpkg::Options::="--force-confold" \
        autoconf bison gcc libtool make pie-zts pkg-config re2c && \
    rm -rf /var/lib/apt/lists/* && \
    pie-zts install asgrim/example-pie-extension

And run ddev restart.

Make sure to commit the .ddev/web-build/Dockerfile.frankenphp_extra file to version control.

---

To change the default Caddyfile configuration, remove the #ddev-generated line from .ddev/web-build/Caddyfile.frankenphp and edit it.

Alternatively, create a file .ddev/docker-compose.frankenphp_extra.yaml with the following content:

# .ddev/docker-compose.frankenphp_extra.yaml
# See all configurable variables in
# https://github.com/php/frankenphp/blob/main/caddy/frankenphp/Caddyfile
services:
  web:
    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 {
        #   ...
        # }

And run ddev restart.

Make sure to commit the .ddev/docker-compose.frankenphp_extra.yaml file to version control.

Resources:

• FrankenPHP Documentation
• FrankenPHP Static PHP Package Repository
• Using FrankenPHP with DDEV
• DDEV FrankenPHP Benchmark

Credits

Contributed by @stasadev

Maintained by the DDEV team