Installing and Configuring Symfony
Edit this pageWarning: You are browsing the documentation for Symfony 2.6, which is no longer maintained.
Read the updated version of this page for Symfony 6.1 (the current stable version).
- Installing the Symfony Installer
- Creating the Symfony Application
- Creating Symfony Applications without the Installer
- Running the Symfony Application
- Checking Symfony Application Configuration and Setup
- Updating Symfony Applications
- Installing the Symfony Demo Application
- Installing a Symfony Distribution
- Using Source Control
- Beginning Development
Installing and Configuring Symfony
The goal of this chapter is to get you up and running with a working application built on top of Symfony. In order to simplify the process of creating new applications, Symfony provides an installer application.
Installing the Symfony Installer
Using the Symfony Installer is the only recommended way to create new Symfony applications. This installer is a PHP application that has to be installed in your system only once and then it can create any number of Symfony applications.
Note
The installer requires PHP 5.4 or higher. If you still use the legacy PHP 5.3 version, you cannot use the Symfony Installer. Read the Installing and Configuring Symfony section to learn how to proceed.
Depending on your operating system, the installer must be installed in different ways.
Linux and Mac OS X Systems
Open your command console and execute the following commands:
1 2
$ sudo curl -LsS http://symfony.com/installer -o /usr/local/bin/symfony
$ sudo chmod a+x /usr/local/bin/symfony
This will create a global symfony
command in your system.
Windows Systems
Open your command console and execute the following command:
1
c:\> php -r "readfile('http://symfony.com/installer');" > symfony
Then, move the downloaded symfony
file to your project's directory and
execute it as follows:
1 2
c:\> move symfony c:\projects
c:\projects\> php symfony
Creating the Symfony Application
Once the Symfony Installer is available, create your first Symfony application
with the new
command:
1 2 3 4 5 6
# Linux, Mac OS X
$ symfony new my_project_name
# Windows
c:\> cd projects/
c:\projects\> php symfony new my_project_name
This command creates a new directory called my_project_name
that contains a
fresh new project based on the most recent stable Symfony version available. In
addition, the installer checks if your system meets the technical requirements
to execute Symfony applications. If not, you'll see the list of changes needed
to meet those requirements.
Tip
For security reasons, all Symfony versions are digitally signed before distributing them. If you want to verify the integrity of any Symfony version, follow the steps explained in this post.
Basing your Project on a Specific Symfony Version
In case your project needs to be based on a specific Symfony version, use the
optional second argument of the new
command:
1 2 3 4 5 6 7 8 9 10 11
# use the most recent version in any Symfony branch
$ symfony new my_project_name 2.3
$ symfony new my_project_name 2.5
$ symfony new my_project_name 2.6
# use a specific Symfony version
$ symfony new my_project_name 2.3.26
$ symfony new my_project_name 2.6.5
# use the most recent LTS (Long Term Support) version
$ symfony new my_project_name lts
If you want your project to be based on the latest Symfony LTS version,
pass lts
as the second argument of the new
command:
1 2 3 4 5
# Linux, Mac OS X
$ symfony new my_project_name lts
# Windows
c:\projects\> php symfony new my_project_name lts
Read the Symfony Release process to better understand why there are several Symfony versions and which one to use for your projects.
Creating Symfony Applications without the Installer
If you still use PHP 5.3, or if you can't execute the installer for any reason, you can create Symfony applications using the alternative installation method based on Composer.
Composer is the dependency manager used by modern PHP applications and it can also be used to create new applications based on the Symfony Framework. If you don't have it installed globally, start by reading the next section.
Creating a Symfony Application with Composer
Once Composer is installed on your computer, execute the create-project
command to create a new Symfony application based on its latest stable version:
1
$ composer create-project symfony/framework-standard-edition my_project_name
If you need to base your application on a specific Symfony version, provide that
version as the second argument of the create-project
command:
1
$ composer create-project symfony/framework-standard-edition my_project_name "2.3.*"
Tip
If your Internet connection is slow, you may think that Composer is not
doing anything. If that's your case, add the -vvv
flag to the previous
command to display a detailed output of everything that Composer is doing.
Running the Symfony Application
Symfony leverages the internal web server provided by PHP to run applications while developing them. Therefore, running a Symfony application is a matter of browsing the project directory and executing this command:
1 2
$ cd my_project_name/
$ php app/console server:run
Then, open your browser and access the http://localhost:8000/app/example
URL to see the
Welcome page of Symfony:

Instead of the Welcome Page, you may see a blank page or an error page. This is caused by a directory permission misconfiguration. There are several possible solutions depending on your operating system. All of them are explained in the Setting up Permissions section.
Note
PHP's internal web server is available in PHP 5.4 or higher versions. If you still use the legacy PHP 5.3 version, you'll have to configure a virtual host in your web server.
The server:run
command is only suitable while developing the application. In
order to run Symfony applications on production servers, you'll have to configure
your Apache or Nginx web server as explained in
Configuring a Web Server.
When you are finished working on your Symfony application, you can stop the
server with the server:stop
command:
1
$ php app/console server:stop
Checking Symfony Application Configuration and Setup
Symfony applications come with a visual server configuration tester to show if your environment is ready to use Symfony. Access the following URL to check your configuration:
1
http://localhost:8000/config.php
If there are any issues, correct them now before moving on.
Updating Symfony Applications
At this point, you've created a fully-functional Symfony application in which
you'll start to develop your own project. A Symfony application depends on
a number of external libraries. These are downloaded into the vendor/
directory
and they are managed exclusively by Composer.
Updating those third-party libraries frequently is a good practice to prevent bugs
and security vulnerabilities. Execute the update
Composer command to update
them all at once:
1 2
$ cd my_project_name/
$ composer update
Depending on the complexity of your project, this update process can take up to several minutes to complete.
Tip
Symfony provides a command to check whether your project's dependencies contain any known security vulnerability:
1
$ php app/console 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.
Installing the Symfony Demo Application
The Symfony Demo application is a fully-functional application that shows the recommended way to develop Symfony applications. The application has been conceived as a learning tool for Symfony newcomers and its source code contains tons of comments and helpful notes.
In order to download the Symfony Demo application, execute the demo
command
of the Symfony Installer anywhere in your system:
1 2 3 4 5
# Linux, Mac OS X
$ symfony demo
# Windows
c:\projects\> php symfony demo
Once downloaded, enter into the symfony_demo/
directory and run the PHP's
built-in web server executing the php app/console server:run
command. Access
to the http://localhost:8000
URL in your browser to start using the Symfony
Demo application.
Installing a Symfony Distribution
Symfony project packages "distributions", which are fully-functional applications that include the Symfony core libraries, a selection of useful bundles, a sensible directory structure and some default configuration. In fact, when you created a Symfony application in the previous sections, you actually downloaded the default distribution provided by Symfony, which is called Symfony Standard Edition.
The Symfony Standard Edition is by far the most popular distribution and it's also the best choice for developers starting with Symfony. However, the Symfony Community has published other popular distributions that you may use in your applications:
- The Symfony CMF Standard Edition is the best distribution to get started with the Symfony CMF project, which is a project that makes it easier for developers to add CMS functionality to applications built with the Symfony Framework.
- The Symfony REST Edition shows how to build an application that provides a RESTful API using the FOSRestBundle and several other related bundles.
Using Source Control
If you're using a version control system like Git, you can safely commit all
your project's code. The reason is that Symfony applications already contain a
.gitignore
file specially prepared for Symfony.
For specific instructions on how best to set up your project to be stored in Git, see How to Create and Store a Symfony Project in Git.
Checking out a versioned Symfony Application
When using Composer to manage application's dependencies, it's recommended to
ignore the entire vendor/
directory before committing its code to the
repository. This means that when checking out a Symfony application from a Git
repository, there will be no vendor/
directory and the application won't
work out-of-the-box.
In order to make it work, check out the Symfony application and then execute the
install
Composer command to download and install all the dependencies required
by the application:
1 2
$ cd my_project_name/
$ composer install
How does Composer know which specific dependencies to install? Because when a
Symfony application is committed to a repository, the composer.json
and
composer.lock
files are also committed. These files tell Composer which
dependencies (and which specific versions) to install for the application.
Beginning Development
Now that you have a fully-functional Symfony application, you can begin
development! Your distribution may contain some sample code - check the
README.md
file included with the distribution (open it as a text file)
to learn about what sample code was included with your distribution.
If you're new to Symfony, check out "Create your First Page in Symfony", where you'll learn how to create pages, change configuration, and do everything else you'll need in your new application.
Be sure to also check out the Cookbook, which contains a wide variety of articles about solving specific problems with Symfony.
Note
If you want to remove the sample code from your distribution, take a look at this cookbook article: "How to Remove the AcmeDemoBundle"