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 that must be installed before
creating the first application.

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
only once and then it can create any number of Symfony applications.

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.

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 installed it globally, start by reading the next section.

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.

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:

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:

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).

2. Using ACL on a system that supports chmod +a

Many systems allow you to use the chmod +a command. Try this first,
and if you get an error - try the next method. This uses a command to
try to determine your web server user and set it as HTTPDUSER:

Some systems 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 (as is the case with Ubuntu). This
uses a command to try to determine your web server user and set it as
HTTPDUSER:

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// orumask(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.

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.

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.

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.

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.

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 "Creating Pages 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.