Symfony Local Web Server
Edit this pageWarning: You are browsing the documentation for Symfony 4.2, which is no longer maintained.
Read the updated version of this page for Symfony 6.1 (the current stable version).
Symfony Local Web Server
You can run Symfony applications with any web server (Apache, nginx, the internal PHP web server, etc.). However, Symfony provides its own web server to make you more productive while developing your applications.
Although this server is not intended for production use, it supports HTTP/2, TLS/SSL, automatic generation of security certificates, local domains, and many other features that sooner or later you'll need when developing web projects. Moreover, the server is not tied to Symfony and you can also use it with any PHP application and even with HTML/SPA (single page applications).
Installation
The Symfony server is distributed as a free installable binary and has support for Linux, macOS and Windows. Go to symfony.com/download and follow the instructions for your operating system.
Note
If you want to report a bug or suggest a new feature, please create an issue on symfony/cli.
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
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
Selecting a Different PHP Version
If you have multiple PHP versions installed on your computer, you can tell
Symfony which one to use creating a file called .php-version
at the project
root directory:
1 2 3 4 5 6 7
$ cd my-project/
# use a specific PHP version
$ echo "7.2" > .php-version
# use any PHP 7.x version available
$ echo "7" > .php-version
Tip
The Symfony server traverses the directory structure up to the root
directory, so you can create a .php-version
file in some parent
directory to set the same PHP version for a group of projects under that
directory.
Run the command below if you don't remember all the PHP versions installed on your computer:
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.
Overriding PHP Config Options Per Project
You can change the value of any PHP runtime config option per project by creating a
file called php.ini
at the project root directory. Add only the options you want
to override:
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
Running Commands with Different PHP Versions
When running different PHP versions it's useful to use the main symfony
command as a wrapper for the php
command. This allows you to always select
the most appropriate PHP version according to the project which is running the
commands. It also loads the env vars automatically, which is important when
running non-Symfony commands:
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 "..."
If you are using this wrapper frequently, consider aliasing the php
command
to it:
1 2 3 4 5 6 7 8
$ cd ~/.symfony/bin
$ cp symfony php
# now you can run "php ..." and the "symfony" command will be executed instead
# other PHP commands can be wrapped too using this trick
$ cp symfony php-config
$ cp symfony pear
$ cp symfony pecl
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.
Setting up the Local Proxy
Local domains are possible thanks to a local proxy provided by the Symfony server. First, start the proxy:
1
$ symfony proxy:start
If this is the first time you run the proxy, you must follow these additional steps:
- Open the network configuration of your operating system;
- Find the proxy settings and select the "Automatic Proxy Configuration";
- Set the following URL as its value:
http://127.0.0.1:7080/proxy.pac
Defining the Local Domain
By default, Symfony proposes .wip
(for Work in Progress) for the local
domains. You can define a local domain for your project as follows:
1 2
$ cd my-project/
$ symfony proxy:domain:attach my-domain
If you have installed the local proxy as explained in the previous section, you
can now browse https://my-domain.wip
to access your local project with the
new custom domain.
Tip
Browse the http://127.0.0.1:7080 URL to get the full list of local project directories, their custom domains, and port numbers.
When running console commands, add the HTTPS_PROXY
env var to make custom
domains work:
1
$ HTTPS_PROXY=http://127.0.0.1:7080 curl https://my-domain.wip
Tip
If you prefer to use a different TLD, edit the ~/.symfony/proxy.json
file (where ~
means the path to your user directory) and change the
value of the tld
option from wip
to any other TLD.
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 yarn 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 "yarn ..." running with PID ...
# stop the web server (and all the associated commands) when you are finished
$ symfony server:stop
Docker Integration
The local Symfony server provides full Docker integration for projects that use it. First, make sure to expose the container ports:
1 2 3 4 5 6 7 8 9 10 11
# docker-compose.override.yaml
services:
database:
ports:
- "3306"
redis:
ports:
- "6379"
# ...
Then, check your service names and update them if needed (Symfony creates environment variables following the name of the services so they can be autoconfigured):
1 2 3 4 5 6 7 8 9 10 11 12
# docker-compose.yaml
services:
# DATABASE_URL
database: ...
# MONGODB_DATABASE, MONGODB_SERVER
mongodb: ...
# REDIS_URL
redis: ...
# ELASTISEARCH_HOST, ELASTICSEARCH_PORT
elasticsearch: ...
# RABBITMQ_DSN
rabbitmq: ...
If your docker-compose.yaml
file doesn't use the environment variable names
expected by Symfony (e.g. you use MYSQL_URL
instead of DATABASE_URL
)
then you need to rename all occurrences of those environment variables in your
Symfony application. A simpler alternative is to use the .env.local
file to
reassign the environment variables:
1 2 3
# .env.local
DATABASE_URL=${MYSQL_URL}
# ...
Now you can start the containers and all their services will be exposed. Browse any page of your application and check the "Symfony Server" section in the web debug toolbar. You'll see that "Docker Compose" is "Up".
SymfonyCloud Integration
The local Symfony server provides full, but optional, integration with SymfonyCloud, 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.
Bonus Features
In addition to being a local web server, the Symfony server provides other useful features:
Looking for Security Vulnerabilities
Run the following command to check whether your project's dependencies contain any known security vulnerability:
1
$ symfony security:check
A good security practice is to execute this command regularly to be able to
update or replace compromised dependencies as soon as possible. The security
check is done locally by cloning the public PHP security advisories database,
so your composer.lock
file is not sent on the network.
Tip
The security:check
command terminates with a non-zero exit code if
any of your dependencies is affected by a known security vulnerability.
This way you can add it to your project build process and your continuous
integration workflows to make them fail when there are vulnerabilities.
Creating Symfony Projects
In addition to the different ways of installing Symfony, you can use these commands from the Symfony server:
1 2 3 4 5 6 7 8
# creates a new project based on symfony/skeleton
$ symfony new my_project_name
# creates a new project based on symfony/website-skeleton
$ symfony new --full my_project_name
# creates a new project based on the Symfony Demo application
$ symfony new --demo my_project_name
You can create a project depending on a development version as well (note
that Composer will also set the stability to dev
for all root dependencies):
1 2 3 4 5
# creates a new project based on Symfony's master branch
$ symfony new --version=dev-master my_project_name
# creates a new project based on Symfony's 4.3 dev branch
$ symfony new --version=4.3.x-dev my_project_name