--- title: Running Symfony with FrankenPHP (Docker, worker mode, hot reload) description: How to run a Symfony application with FrankenPHP using Symfony Docker, a local install, worker mode, hot reload, AssetMapper, and X-Sendfile. --- # Symfony ## Running Symfony with Symfony Docker For [Symfony](https://symfony.com) projects, we recommend using [Symfony Docker](https://github.com/dunglas/symfony-docker), the official Symfony Docker setup maintained by FrankenPHP's author. It provides a complete Docker-based environment with FrankenPHP, automatic HTTPS, HTTP/2, HTTP/3, and worker mode support out of the box. ## Installing Symfony with FrankenPHP locally Alternatively, you can run your Symfony projects with FrankenPHP from your local machine: 1. [Install FrankenPHP](../#getting-started) 2. Add the following configuration to a file named `Caddyfile` in the root directory of your Symfony project: ```caddyfile # Caddyfile # The domain name of your server localhost root public/ php_server { # Optional: Enable worker mode for better performance worker ./public/index.php } ``` See the [performance documentation](performance.md) for further optimizations. 3. Start FrankenPHP from the root directory of your Symfony project: `frankenphp run` ## Symfony worker mode with FrankenPHP Since Symfony 7.4, FrankenPHP worker mode is natively supported. For older versions, install the FrankenPHP package of [PHP Runtime](https://github.com/php-runtime/runtime): ```console composer require runtime/frankenphp-symfony ``` Start your app server by defining the `APP_RUNTIME` environment variable to use the FrankenPHP Symfony Runtime: ```console docker run \ -e FRANKENPHP_CONFIG="worker ./public/index.php" \ -e APP_RUNTIME=Runtime\\FrankenPhpSymfony\\Runtime \ -v $PWD:/app \ -p 80:80 -p 443:443 -p 443:443/udp \ dunglas/frankenphp ``` Learn more about [the worker mode](worker.md). ### Auditing worker compatibility [Igor PHP](https://github.com/igor-php/igor-php) is a static linter that scans Symfony projects for state leaks before they bite in production: services missing `ResetInterface`, stateful properties that aren't reset, mutable local statics, `exit()`/`die()` calls, and superglobal writes. It audits your application code as well as services declared in `vendor/`. ```console composer require --dev igor-php/igor-php vendor/bin/igor-php . ``` ## Hot reload for Symfony Hot reloading is enabled by default in [Symfony Docker](https://github.com/dunglas/symfony-docker). To use the [hot reload](hot-reload.md) feature without Symfony Docker, enable [Mercure](mercure.md) and add the `hot_reload` sub-directive to the `php_server` directive in your `Caddyfile`: ```caddyfile localhost mercure { anonymous } root public/ php_server { hot_reload worker ./public/index.php } ``` Then, add the following code to your `templates/base.html.twig` file: ```twig {# templates/base.html.twig #} {% if app.request.server.has('FRANKENPHP_HOT_RELOAD') %} {% endif %} ``` Finally, run `frankenphp run` from the root directory of your Symfony project. ## Pre-compressing assets Symfony's [AssetMapper component](https://symfony.com/doc/current/frontend/asset_mapper.html) can pre-compress assets with Brotli and Zstandard during deployment. FrankenPHP (through Caddy's `file_server`) can serve these pre-compressed files directly, avoiding on-the-fly compression overhead. 1. Compile and compress your assets: ```console php bin/console asset-map:compile ``` 2. Update your `Caddyfile` to serve pre-compressed assets: ```caddyfile # Caddyfile localhost @assets path /assets/* file_server @assets { precompressed zstd br gzip } root public/ php_server { worker ./public/index.php } ``` The `precompressed` directive tells Caddy to look for pre-compressed versions of the requested file (e.g., `app.css.zst`, `app.css.br`) and serve them directly if the client supports it. ## Serving large static files (`X-Sendfile`) FrankenPHP supports [efficiently serving large static files](x-sendfile.md) after executing PHP code (for access control, statistics, etc.). Symfony HttpFoundation [natively supports this feature](https://symfony.com/doc/current/components/http_foundation.html#serving-files). After [configuring your `Caddyfile`](x-sendfile.md#configuring-x-accel-redirect-in-the-frankenphp-caddyfile), it will automatically determine the correct value for the `X-Accel-Redirect` header and add it to the response: ```php use Symfony\Component\HttpFoundation\BinaryFileResponse; BinaryFileResponse::trustXSendfileTypeHeader(); $response = new BinaryFileResponse(__DIR__.'/../private-files/file.txt'); // ... ``` ## Symfony apps as standalone binaries Using [FrankenPHP's application embedding feature](embed.md), it's possible to distribute Symfony apps as standalone binaries. Follow these steps to prepare and package your Symfony app: 1. Prepare your app: ```console # Export the project to get rid of .git/, etc mkdir $TMPDIR/my-prepared-app git archive HEAD | tar -x -C $TMPDIR/my-prepared-app cd $TMPDIR/my-prepared-app # Set proper environment variables echo APP_ENV=prod > .env.local echo APP_DEBUG=0 >> .env.local # Remove the tests and other unneeded files to save space # Alternatively, add these files with the export-ignore attribute in your .gitattributes file rm -Rf tests/ # Install the dependencies composer install --ignore-platform-reqs --no-dev -a # Optimize .env composer dump-env prod ``` 2. Create a file named `static-build.Dockerfile` in the repository of your app: ```dockerfile # static-build.Dockerfile FROM --platform=linux/amd64 dunglas/frankenphp:static-builder-gnu # If you intend to run the binary on musl-libc systems, use static-builder-musl instead # Copy your app WORKDIR /go/src/app/dist/app COPY . . # Build the static binary WORKDIR /go/src/app/ RUN EMBED=dist/app/ ./build-static.sh ``` > [!CAUTION] > > Some `.dockerignore` files (e.g. default [Symfony Docker `.dockerignore`](https://github.com/dunglas/symfony-docker/blob/main/.dockerignore)) > will ignore the `vendor/` directory and `.env` files. Be sure to adjust or remove the `.dockerignore` file before the build. 3. Build: ```console docker build -t static-symfony-app -f static-build.Dockerfile . ``` 4. Extract the binary: ```console docker cp $(docker create --name static-symfony-app-tmp static-symfony-app):/go/src/app/dist/frankenphp-linux-x86_64 my-app ; docker rm static-symfony-app-tmp ``` 5. Start the server: ```console ./my-app php-server ``` Learn more about the options available and how to build binaries for other OSes in the [applications embedding](embed.md) documentation.