Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Book
  4. Installing and Configuring Symfony
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Installing the Symfony Installer
    • Linux and Mac OS X Systems
    • Windows Systems
  • Creating the Symfony Application
    • Basing your Project on a Specific Symfony Version
  • Creating Symfony Applications without the Installer
    • Installing Composer Globally
    • Creating a Symfony Application with Composer
  • 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
    • Checking out a versioned Symfony Application
  • Beginning Development

Installing and Configuring Symfony

Edit this page

Warning: You are browsing the documentation for Symfony 2.3, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

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 https://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('https://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.

Note

If the installer doesn't work for you or doesn't output anything, make sure that the Phar extension is installed and enabled on your computer.

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
12
# 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 a beta or RC version (useful for testing new Symfony versions)
$ symfony new my_project 2.7.0-BETA1
$ symfony new my_project 2.7.0-RC1

The installer also supports a special version called lts which installs the most recent Symfony LTS version available:

1
$ 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.

Installing Composer Globally

Start with installing Composer globally.

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/ URL to see the Welcome Page of Symfony:

Symfony Welcome Page

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 by pressing `Ctrl+C` from terminal.

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.

Setting up Permissions

One common issue when installing Symfony is that the app/cache and app/logs directories must be writable both by the web server and the command line user. On a UNIX system, if your web server user is different from your command line user, you can try one of the following solutions.

1. Use the same user for the CLI and the web server

In development environments, it is a common practice to use the same UNIX user for the CLI and the web server because it avoids any of these permissions issues when setting up new projects. This can be done by editing your web server configuration (e.g. commonly httpd.conf or apache2.conf for Apache) and setting its user to be the same as your CLI user (e.g. for Apache, update the User and Group values).

Caution

If used in a production environment, be sure this user only has limited privileges (no access to private data or servers, launch of unsafe binaries, etc.) as a compromised server would give to the hacker those privileges.

2. Using ACL on a system that supports chmod +a (MacOS X)

MacOS X allows you to use the chmod +a command. This uses a command to try to determine your web server user and set it as HTTPDUSER:

1
2
3
4
5
6
$ rm -rf app/cache/*
$ rm -rf app/logs/*

$ HTTPDUSER=`ps axo user,comm | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
$ sudo chmod +a "$HTTPDUSER allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs
$ sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs

3. Using ACL on a system that supports setfacl (most Linux/BSD)

Most Linux and BSD distributions don't support chmod +a, but do support another utility called setfacl. You may need to enable ACL support on your partition and install setfacl before using it. This uses a command to try to determine your web server user and set it as HTTPDUSER:

1
2
3
$ HTTPDUSER=`ps axo user,comm | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
$ sudo setfacl -R -m u:"$HTTPDUSER":rwX -m u:`whoami`:rwX app/cache app/logs
$ sudo setfacl -dR -m u:"$HTTPDUSER":rwX -m u:`whoami`:rwX app/cache app/logs

If this doesn't work, try adding -n option.

Note

setfacl isn't available on NFS mount points. However, setting cache and logs over NFS is strongly not recommended for performance.

4. Without using ACL

If none of the previous methods work for you, change the umask so that the cache and log directories will be group-writable or world-writable (depending if the web server user and the command line user are in the same group or not). To achieve this, put the following line at the beginning of the app/console, web/app.php and web/app_dev.php files:

1
2
3
4
5
umask(0002); // This will let the permissions be 0775

// or

umask(0000); // This will let the permissions be 0777

Note that using the ACL is recommended when you have access to them on your server because changing the umask is not thread-safe.

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.

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.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    Take the exam at home

    Take the exam at home

    Code consumes server resources. Blackfire tells you how

    Code consumes server resources. Blackfire tells you how

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Paweł Farys, a Symfony contributor

    Thanks Paweł Farys for being a Symfony contributor

    1 commit • 2 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia