Up(sun) and running with FrankenPHP

We’re here to shed a little light on how you can use and configure FrankenPHP—a modern PHP app server, written in Go and designed to accelerate your PHP applications—on Upsun with our step-by-step guide.

How to start using FrankenPHP on Upsun

To perform the following steps in this guide, you need to host your PHP application on Upsun—for details on how to do so, follow this simple tutorial on how to host a Symfony Demo application on Upsun. 

upsun branch staging --type staging

Create a staging environment

As we never (ever) test new features directly on production, we will create a new environment to test and configure our Symfony Demo application to use FrankenPHP. 

To create a new environment on our project, use the following command:

symfony branch staging --type=staging

This command creates a new active staging environment (of type staging) and automatically switches your local Git branch to staging.

How to use FrankenPHP on Upsun 

Now it’s time to show you how to use FrankenPHP, this rad PHP web server was designed for a similar purpose to Swoole and RoadRunner: to increase the speed of your PHP application loading time. So, how do you configure it in Upsun? 

Kevin Dunglas, from Les Tilleuls, provides a built-in FrankenPHP image that can be used to run a FrankenPHP PHP server if preferred to the PHP-FPM server provided by Upsun.

To do so, open your source code in your favorite IDE, and let’s update your .upsun/config.yaml file by completing the following steps:

1. Find the applications.app.web section and change it accordingly: all of the HTTP calls need to pass through the application and the default upstream HTTP protocol needs to use tcp unix sockets. You also need to define a commands.start to start the FrankenPHP server. 

applications:
  app:
    ...
    web:
      locations:
        "/":
          root: "public"
          expires: 1h
          #passthru: "/index.php"
          passthru: true
          scripts: false
          allow: false
      upstream:
        # important for PHP we default to unix sockets
        socket_family: tcp
        protocol: http
      commands:
        start: ./frankenphp php-server --listen=localhost:$PORT --root=$PLATFORM_DOCUMENT_ROOT

2. As FrankenPHP needs to write access to a .local folder, you need to add a mount (=writable folder within your app container) for FrankenPHP to do so. Please find the applications.app.mounts section in your .upsun/config.yaml and add the following .local mount configuration:

applications:
  app:
    ...  
    mounts:
      ...
      ".local": { source: storage, source_path: frankenphp-local}

applications:
  app:
    ...
    hooks:
      build: |
        set -x -e

        curl -fs https://get.symfony.com/cloud/configurator | bash

        NODE_VERSION=18 symfony-build

        curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-frankenphp.sh | { bash /dev/fd/3 5.1.1 ; }

curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-frankenphp.sh | bash 

4. Add the FrankenPHP runtime to your Symfony project. According to the FrankenPHP documentation page, you need to add the following bundle to the application: 

composer require runtime/frankenphp-symfony

5. Add an APP_RUNTIME environment variable—to tell Symfony to use the new FrankenPHP runtime, you need an environment variable, named APP_RUNTIME. To do so, in your .upsun/config.yaml, find the applications.app.variables section and add the following:

applications:
  app:
    ...  
    variables:
      php: ... 
      env: 
        APP_RUNTIME: 'Runtime\\FrankenPhpSymfony\\Runtime'

6. Deploy your changes to staging.

git add composer.json composer.lock symfony.lock .upsun/config.yaml install_frankenphp.sh
git commit -m "Use FrankenPHP instead of PHP-FPM"
symfony deploy   # or upsun push

7. Open your staging environment URL. To open the corresponding environment URL, use the following command:

symfony environment:url

8. Merge to production. When you’re good to go with your application behavior, you can merge it to the main production branch, using the following: 

symfony merge
symfony checkout main
git pull upsun main
symfony environment:delete staging
git fetch --prune

./frankenphp php-cli bin/console 

If you want to dive deeper into how to use FrankenPHP or other PHP servers, such as Swoole or RoadRunner, with your Symfony application on Upsun, take a look at this inspiring article from Sergii Dolgushev that is worth the read.

While focusing on installing FrankenPHP, this guide also serves as an introduction to using alternative PHP servers—often considered for the impressive performance they could bring—on Upsun.

The application only needs to boot once and then it remains in memory and stored in the cache, eliminating the need for instantiation with every incoming request. When using PHP-FPM, each time your application runs a PHP script, this PHP script is loaded in memory and then removed at the end of its execution. Furthermore, some alternative servers have embedded asynchronous capabilities that expand the technical horizon even more.

While the performance improvements from using an alternative PHP server like FrankenPHP are promising, it’s essential to proceed cautiously. Simply switching servers won’t solve deep-seated performance issues or other underlying problems—it’s more like a temporary fix for a more significant issue.

An excellent first step is to delve into the application and architecture observability dashboards to identify critical areas that need improvement. Once you thoroughly understand your application’s performance, you can consider moving to an alternative server to enhance efficiency and handling. Find out more about observability here.

Stay up to date on the latest from us over on our social media and community channels: Dev.to, Reddit, and Discord. Happy FrankenPHP’ing!