You are browsing the Symfony 5.0 documentation, which changes significantly from Symfony 3.x. If your app doesn't use Symfony 5.0 yet, browse the Symfony 3.4 documentation.
Installing & Setting up the Symfony Framework
Installing & Setting up the Symfony Framework¶
Do you prefer video tutorials? Check out the Stellar Development with Symfony screencast series.
Before creating your first Symfony application you must:
- Install PHP 7.2.9 or higher and these PHP extensions (which are installed and enabled by default in most PHP 7 installations): Ctype, iconv, JSON, PCRE, Session, SimpleXML, and Tokenizer;
- Install Composer, which is used to install PHP packages;
- Install Symfony, which creates in your computer a binary called
symfonythat provides all the tools you need to develop your application locally.
symfony binary provides a tool to check if your computer meets these
requirements. Open your console terminal and run this command:
$ symfony check:requirements
Creating Symfony Applications¶
Open your console terminal and run any of these commands to create a new Symfony application:
1 2 3 4 5
# run this if you are building a traditional web application $ symfony new my_project_name --full # run this if you are building a microservice, console application or API $ symfony new my_project_name
The only difference between these two commands is the number of packages
installed by default. The
--full option installs all the packages that you
usually need to build web applications, so the installation size will be bigger.
If you can't or don't want to install Symfony for any reason, run these commands to create the new Symfony application using Composer:
1 2 3 4 5
# run this if you are building a traditional web application $ composer create-project symfony/website-skeleton my_project_name # run this if you are building a microservice, console application or API $ composer create-project symfony/skeleton my_project_name
No matter which command you run to create the Symfony application. All of them
will create a new
my_project_name/ directory, download some dependencies
into it and even generate the basic directories and files you'll need to get
started. In other words, your new application is ready!
The project's cache and logs directory (by default,
<project>/var/log/) must be writable by the web server. If you have
any issue, read how to set up permissions for Symfony applications.
Running Symfony Applications¶
On production, you should use a web server like Nginx or Apache (see configuring a web server to run Symfony). But for development, it's more convenient to use the local web server provided by Symfony.
This local server provides support for HTTP/2, TLS/SSL, automatic generation of security certificates and many other features. It works with any PHP application, not only Symfony projects, so it's a very useful development tool.
Open your console terminal, move into your new project directory and start the local web server as follows:
$ cd my-project/ $ symfony server:start
Open your browser and navigate to
http://localhost:8000/. If everything is
working, you'll see a welcome page. Later, when you are finished working, stop
the server by pressing
Ctrl+C from your terminal.
Setting up an Existing Symfony Project¶
In addition to creating new Symfony projects, you will also work on projects already created by other developers. In that case, you only need to get the project code and install the dependencies with Composer. Assuming your team uses Git, setup your project with the following commands:
1 2 3 4 5 6 7
# clone the project to download its contents $ cd projects/ $ git clone ... # make Composer install the project's dependencies into vendor/ $ cd my-project/ $ composer install
You'll probably also need to customize your .env file and do a few other project-specific tasks (e.g. creating a database). When working on a existing Symfony application for the first time, it may be useful to run this command which displays information about the project:
$ php bin/console about
A common practice when developing Symfony applications is to install packages (Symfony calls them bundles) that provide ready-to-use features. Packages usually require some setup before using them (editing some file to enable the bundle, creating some file to add some initial config, etc.)
Most of the time this setup can be automated and that's why Symfony includes Symfony Flex, a tool to simplify the installation/removal of packages in Symfony applications. Technically speaking, Symfony Flex is a Composer plugin that is installed by default when creating a new Symfony application and which automates the most common tasks of Symfony applications.
You can also add Symfony Flex to an existing project.
Symfony Flex modifies the behavior of the
remove Composer commands to provide advanced features. Consider the
$ cd my-project/ $ composer require logger
If you execute that command in a Symfony application which doesn't use Flex,
you'll see a Composer error explaining that
logger is not a valid package
name. However, if the application has Symfony Flex installed, that command
installs and enables all the packages needed to use the official Symfony logger.
This is possible because lots of Symfony packages/bundles define "recipes",
which are a set of automated instructions to install and enable packages into
Symfony applications. Flex keeps tracks of the recipes it installed in a
symfony.lock file, which must be committed to your code repository.
Symfony Flex recipes are contributed by the community and they are stored in two public repositories:
- Main recipe repository, is a curated list of recipes for high quality and maintained packages. Symfony Flex only looks in this repository by default.
- Contrib recipe repository, contains all the recipes created by the community. All of them are guaranteed to work, but their associated packages could be unmaintained. Symfony Flex will ask your permission before installing any of these recipes.
Read the Symfony Recipes documentation to learn everything about how to create recipes for your own packages.
Sometimes a single feature requires installing several packages and bundles. Instead of installing them individually, Symfony provides packs, which are Composer metapackages that include several dependencies.
For example, to add debugging features in your application, you can run the
composer require --dev debug command. This installs the
which in turn installs several packages like
By default, when installing Symfony packs, your
composer.json file shows the
pack dependency (e.g.
"symfony/debug-pack": "^1.0") instead of the actual
packages installed. To show the packages, add the
--unpack option when
installing a pack (e.g.
composer require debug --dev --unpack) or run this
command to unpack the already installed packs:
composer unpack PACK_NAME
composer unpack debug).
Checking Security Vulnerabilities¶
symfony binary created when you install Symfony provides a command to
check whether your project's dependencies contain any known security
$ symfony check:security
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,
composer.lock file is not sent on the network.
check:security 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.
Symfony LTS Versions¶
By default, the command that creates new Symfony applications uses the latest
stable version. If you want to use an LTS version, add the
1 2 3 4 5 6 7 8 9
# use the most recent 'lts' version $ symfony new my_project_name --version=lts # use the 'next' Symfony version to be released (still in development) $ symfony new my_project_name --version=next # use a specific Symfony version $ symfony new my_project_name --version=3.3.10 $ symfony new my_project_name --version=4.3.1
The Symfony Demo application¶
The Symfony Demo Application is a fully-functional application that shows the recommended way to develop Symfony applications. It's a great learning tool for Symfony newcomers and its code contains tons of comments and helpful notes.
Run this command to create a new project based on the Symfony Demo application:
$ symfony new my_project_name --demo
- Using Symfony with Homestead/Vagrant
- Configuring a Web Server
- Upgrading a Third-Party Bundle for a Major Symfony Version
- Setting up or Fixing File Permissions
- Upgrading Existing Applications to Symfony Flex
- Symfony Local Web Server
- How to Install or Upgrade to the Latest, Unreleased Symfony Version
- Upgrading a Major Version (e.g. 3.4.0 to 4.1.0)
- Upgrading a Minor Version (e.g. 4.0.0 to 4.1.0)
- Upgrading a Patch Version (e.g. 4.1.0 to 4.1.1)
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.