Symfony Local Web Server

Installation

The Symfony server is part of the symfony binary created when you install Symfony and has support for Linux, macOS and Windows.

Getting Started

The Symfony server is started once per project, so you may end up with several instances (each of them listening to a different port). This is the common workflow to serve a Symfony project:

1
2
3
4
5
6
7
8

$ cd my-project/
$ symfony server:start

  [OK] Web server listening on http://127.0.0.1:....
  ...

# Now, browse the given URL, or run this command:
$ symfony open:local

Running the server this way makes it display the log messages in the console, so you won't be able to run other commands at the same time. If you prefer, you can run the Symfony server in the background:

1
2
3
4
5
6
7
8
9

$ cd my-project/

# start the server in the background
$ symfony server:start -d

# continue working and running other commands...

# show the latest log messages
$ symfony server:log

1

$ sudo codesign --force --deep --sign - $(whereis -q symfony)

Enabling PHP-FPM

When the server starts, it checks for web/index_dev.php, web/index.php, public/app_dev.php, public/app.php in that order. If one is found, the server will automatically start with PHP-FPM enabled. Otherwise the server will start without PHP-FPM and will show a Page not found page when trying to access a .php file in the browser.

Enabling TLS

Browsing the secure version of your applications locally is important to detect problems with mixed content early, and to run libraries that only run in HTTPS. Traditionally this has been painful and complicated to set up, but the Symfony server automates everything. First, run this command:

1

$ symfony server:ca:install

This command creates a local certificate authority, registers it in your system trust store, registers it in Firefox (this is required only for that browser) and creates a default certificate for localhost and 127.0.0.1. In other words, it does everything for you.

Before browsing your local application with HTTPS instead of HTTP, restart its server stopping and starting it again.

Different PHP Settings Per Project

1
2
3
4
5
6
7

$ cd my-project/

# use a specific PHP version
$ echo 7.4 > .php-version

# use any PHP 8.x version available
$ echo 8 > .php-version

1
2
3
4
5

$ symfony local:php:list

  # You'll see all supported SAPIs (CGI, FastCGI, etc.) for each version.
  # FastCGI (php-fpm) is used when possible; then CGI (which acts as a FastCGI
  # server as well), and finally, the server falls back to plain CGI.

1
2
3
4
5
6

$ cd my-project/

# this project only overrides the default PHP timezone
$ cat php.ini
[Date]
date.timezone = Asia/Tokyo

1
2
3
4
5
6

# runs the command with the default PHP version
$ php -r "..."

# runs the command with the PHP version selected by the project
# (or the default PHP version if the project didn't select one)
$ symfony php -r "..."

Local Domain Names

By default, projects are accessible at some random port of the 127.0.0.1 local IP. However, sometimes it is preferable to associate a domain name to them:

• It's more convenient when you work continuously on the same project because port numbers can change but domains don't;
• The behavior of some applications depend on their domains/subdomains;
• To have stable endpoints, such as the local redirection URL for OAuth2.

1

$ symfony proxy:start

1
2

$ cd my-project/
$ symfony proxy:domain:attach my-domain

1

$ symfony proxy:domain:attach "*.my-domain"

1
2
3
4
5
6
7
8

# Example with curl
$ https_proxy=$(symfony proxy:url) curl https://my-domain.wip

# Example with Blackfire and curl
$ https_proxy=$(symfony proxy:url) blackfire curl https://my-domain.wip

# Example with Cypress
$ https_proxy=$(symfony proxy:url) ./node_modules/bin/cypress open

Long-Running Commands

Long-running commands, such as the ones that compile front-end web assets, block the terminal and you can't run other commands at the same time. The Symfony server provides a run command to wrap them as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# compile Webpack assets using Symfony Encore ... but do that in the
# background to not block the terminal
$ symfony run -d npx encore dev --watch

# continue working and running other commands...

# from time to time, check the command logs if you want
$ symfony server:log

# and you can also check if the command is still running
$ symfony server:status
Web server listening on ...
Command "npx ..." running with PID ...

# stop the web server (and all the associated commands) when you are finished
$ symfony server:stop

Configuration file

There are several options that you can set using a .symfony.local.yaml config file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Sets domain1.wip and domain2.wip for the current project
proxy:
    domains:
        - domain1
        - domain2

http:
    document_root: public/ # Path to the project document root
    passthru: index.php # Project passthru index
    port: 8000 # Force the port that will be used to run the server
    preferred_port: 8001 # Preferred HTTP port [default: 8000]
    p12: path/to/p12_cert # Name of the file containing the TLS certificate to use in p12 format
    allow_http: true # Prevent auto-redirection from HTTP to HTTPS
    no_tls: true # Use HTTP instead of HTTPS
    daemon: true # Run the server in the background
    use_gzip: true # Toggle GZIP compression

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# .symfony.local.yaml
workers:
    # built-in command that builds and watches front-end assets
    # npm_encore_watch:
    #     cmd: ['npx', 'encore', 'dev', '--watch']
    npm_encore_watch: ~

    # built-in command that starts messenger consumer
    # messenger_consume_async:
    #     cmd: ['symfony', 'console', 'messenger:consume', 'async']
    #     watch: ['config', 'src', 'templates', 'vendor']
    messenger_consume_async: ~

    # you can also add your own custom commands
    build_spa:
        cmd: ['npm', '--cwd', './spa/', 'dev']

    # auto start Docker compose when starting server (available since Symfony CLI 5.7.0)
    docker_compose: ~

Docker Integration

The local Symfony server provides full Docker integration for projects that use it. To learn more about Docker & Symfony, see Using Docker with Symfony.

When the web server detects that Docker Compose is running for the project, it automatically exposes some environment variables.

Via the docker-compose API, it looks for exposed ports used for common services. When it detects one it knows about, it uses the service name to expose environment variables.

Consider the following configuration:

1
2
3
4

# docker-compose.yaml
services:
    database:
        ports: [3306]

The web server detects that a service exposing port 3306 is running for the project. It understands that this is a MySQL service and creates environment variables accordingly with the service name (database) as a prefix: DATABASE_URL, DATABASE_HOST, ...

If the service is not in the supported list below, generic environment variables are set: PORT, IP, and HOST.

If the docker-compose.yaml names do not match Symfony's conventions, add a label to override the environment variables prefix:

1
2
3
4
5
6

# docker-compose.yaml
services:
    db:
        ports: [3306]
        labels:
            com.symfony.server.service-prefix: 'DATABASE'

In this example, the service is named db, so environment variables would be prefixed with DB_, but as the com.symfony.server.service-prefix is set to DATABASE, the web server creates environment variables starting with DATABASE_ instead as expected by the default Symfony configuration.

Here is the list of supported services with their ports and default Symfony prefixes:

You can open web management interfaces for the services that expose them:

1
2

$ symfony open:local:webmail
$ symfony open:local:rabbitmq

Or click on the links in the "Server" section of the web debug toolbar.

When Docker services are running, browse a page of your Symfony application and check the "Symfony Server" section in the web debug toolbar; you'll see that "Docker Compose" is "Up".

1
2
3
4
5
6

# docker-compose.yaml
services:
    db:
        ports: [3306]
        labels:
            com.symfony.server.service-ignore: true

If your Docker Compose file is not at the root of the project, use the COMPOSE_FILE and COMPOSE_PROJECT_NAME environment variables to define its location, same as for docker-compose:

1
2
3
4
5

# start your containers:
COMPOSE_FILE=docker/docker-compose.yaml COMPOSE_PROJECT_NAME=project_name docker-compose up -d

# run any Symfony CLI command:
COMPOSE_FILE=docker/docker-compose.yaml COMPOSE_PROJECT_NAME=project_name symfony var:export

Platform.sh Integration

The local Symfony server provides full, but optional, integration with Platform.sh, a service optimized to run your Symfony applications on the cloud. It provides features such as creating environments, backups/snapshots, and even access to a copy of the production data from your local machine to help debug any issues.

Read Platform.sh for Symfony technical docs.