Installing symfony

Overview

This chapter describes the steps to install the symfony framework, either from a 'sandbox' archive, from a PEAR package or manually from the source repository.

Introduction

The symfony framework is a set of files written in PHP. A project based on symfony uses these files, so installing symfony means getting these files and making them available for your project.

Symfony can be used for one or many projects. If you work on a single project, you may want to embed the framework within the application you develop. On the other hand, if you choose to use symfony for more than one project, you will prefer to keep all the symfony files in one single place to make the upgrade easier.

In addition, when developing an application, you will probably need to install symfony twice: Once for your development environment, and once for the host server (unless your hosts already has symfony installed).

All these different needs have different answers, that's why you have several alternatives to install symfony:

• The sandbox is an empty symfony project where all the required libraries are already included, and where the basic configuration is already done. It is made mostly for symfony beginners, who want to play with the framework or try the tutorials without installing anything.
• The PEAR installation is recommended to those who want to run several symfony-based projects, with an easy way to upgrade. It requires PEAR version 1.4.0 or higher, which is bundled in most PHP distributions.
• The manual installation is meant to be used only by advanced PHP developers, who want to take advantage of the latest patches or add features of their own.

Note that the symfony framework evolves quickly, and that a new stable version can come out only a few days after your first installation. You have to think of the framework upgrade as a major concern, and that's why the first solution is not recommended if you develop a website for real. In fact, an application developed with the sandbox can not be upgraded easily.

Prerequisites

In order to use symfony, you need to have PHP5 and a web server installed. If you want to use the PEAR install, you will also need PEAR. If you plan on using persistent data, a database will be needed. Symfony is compatible with MySQL, PostgreSQL, Oracle, MSSQL, and any other database having a Creole driver.

Note: You can find many LAMP packages offered for download, which contain the Apache server, the MySQL database and PHP all bundled together and configured for a given platform (XAMPP for many platforms, MAMP for Macintosh, WAMP for Windows, etc.). If you don't have PHP5 installed, they are probably the best option for you to start.

The standard distributions of PHP5 normally work perfectly with symfony. However, as all the installations are different, and because many of the developers compile PHP themselves, it sometimes happens that your web server throws errors because of missing components in PHP. If you can't manage to get symfony working, check out the installation forum, where many individual cases were solved and can help to solve yours.

Note: Some packages sometimes embed both PHP4 and PHP5. Symfony only works with PHP5. To check the version of PHP that you are using, type in a command line:

    $ php -v

The sandbox

The sandbox is a simple archive of files. It contains an empty symfony project where all the required libraries (symfony, pake, creole, propel and phing) are already included. To install it, just unpack the archive under the root web directory configured for your server (usually web/). It will work "out of the box", without configuration or any additional package.

The sandbox is intended for you to practice with symfony in a local computer, not really to develop complex applications that may end up on the web. However, the version of symfony shipped with the sandbox is fully functional and equivalent to the one you can install via PEAR. Beware that the sandbox is not easily upgradeable.

Get the sandbox here: http://www.symfony-project.com/get/sf_sandbox.tgz. After unpacking the archive, test the sandbox by requesting the following URL:

http://oxyscrip.ipowermysql.com/sf_sandbox/web/

You should see a congratulations page.

f you are in the sf_sandbox/ directory, you can use the command line to do usual site management operations. For instance, to clear the cache, type:

$ ./symfony.sh clear-cache                      (*nix)
symfony clear-cache                             (Windows)

To discover all the available actions of the symfony command line, type:

$ ./symfony.sh -T                               (*nix)
symfony -T

Refer to the included README file for more information.

After downloading the sandbox, you might want to follow the My first project tutorial to discover the basics of symfony development.

Installing symfony from a PEAR Package

PEAR setup

PEAR is used by PHP to install libraries from a central repository. The symfony project has its own repository, or channel. Note that channels are only available since version 1.4.0 of PEAR, so you should upgrade if your version is older:

$ pear upgrade PEAR

The first thing to do is to add the 'symfony' channel:

$ pear channel-discover pear.symfony-project.com

To see the libraries available in this channel:

$ pear remote-list -c symfony

Symfony installation

Now you are ready to install the latest stable version of symfony and all its dependencies with:

$ pear install symfony/symfony

That's it: symfony is installed. You may now create a new project with the new command line tool symfony and use the classes and methods of the libraries.

Symfony needs a few other packages to run; some are included in the installation, and some require you to install them if they are not present:

• pake: installed automatically. You will learn more about the Pake utility in the next chapter.
• creole: installed automatically (used for database access)
• propel: installed automatically (used for object/relational mapping)

• phing: requires manual installation

  $ pear install http://phing.info/pear/phing-current.tgz

To have a glimpse of all the tasks that you can perform directly with the command-line tool, type:

$ symfony -T

Where are the symfony files ?

The symfony libraries are now installed in:

$php_dir/symfony/      main libraries
$data_dir/symfony/     skeleton of symfony applications, default modules and configuration
$doc_dir/symfony/      documentation
$test_dir/symfony/     unit tests

The _dir variables are part of your PEAR configuration. To see their value, type:

$ pear config-show

As a matter of fact, the exact location of files is not very important, since the installation provides you with a new executable, symfony, which will do all the work for you (project creation, application installation and initialization, etc.). Only the $doc_dir directory will be needed in your web server configuration, since it contains some default files (stylesheets and images) that can be required by some pages of symfony projects. This configuration will be detailed in the next chapter.

Just as a reminder, the default locations for Unix and Windows are as follow:

Getting nightly builds

The process described above will install the latest stable version. In order to have the latest bug corrections between two stable versions, you may wish to install the latest nightly build. These builds are published in the symfony channel with a 'beta' tag, and you can install them with:

$ pear install symfony/symfony-beta

If you already have a beta version installed, get the latest build with:

$ pear upgrade symfony/symfony-beta

Note: in some Windows platforms, it appears that the PEAR utility uses its own web cache and doesn't actually require the symfony channel to check the latest version. Make sure you empty your PEAR cache before you ask for an upgrade (use pear config-show to get the location of the cache folder).

When upgrading your symfony installation, don't forget to clear the cache of all the applications using it:

$ cd myproject
$ symfony clear-cache

If you want to be be more selective in clearing the cache (to keep any existing HTML cache and clear only the configuration of each application), you'd rather use:

$ cd myproject
$ symfony clear-cache myapp1 config
$ symfony clear-cache myapp2 config

You can check which version of symfony is installed by typing:

$ symfony -V

Installing symfony by hand

If you don't want to use PEAR, you can still download the latest version directly from the SVN repository, by requesting a checkout, and install it by hand:

$ mkdir /home/steve/mysymfony
$ cd /home/steve/mysymfony
$ svn co http://svn.symfony-project.com/trunk/ .

For your project to make use of this installation, you will have to create two symbolic links in you project from the lib directory to the symfony lib directory:

$ cd /home/steve/myproject
$ ln -sf /home/steve/mysymfony/lib lib/symfony
$ ln -sf /home/steve/mysymfony/data data/symfony

In addition, you will have to make the shortcuts to allow the call to the command line tools pake and symfony.

Note: You must also install Phing and Pake. Just install them under the lib/symfony directory.

Installing symfony without command line

If you want to host your website in a server that you can't access with a command line (and that might happen if your hosting provider only allows FTP access), you will need to install the two symfony directories manually in your project tree structure.

First, get the .tgz file of the symfony framework package from the symfony project website. Unpack it into a temporary folder. You will see the following file structure:

package.xml
symfony/
  LICENSE
  bin/
  data/
  lib/

The bin directory will not be of any use since you can't call a command.

Let's suppose that you already transferred your symfony-enabled project to a distant server. The distant tree structure will look like:

myproject/
  apps/
    myapp/
  batch/
  cache/
  config/
  data/
  doc/
  lib/
  log/
  test/
  web/

To learn more about the file structure of symfony projects, read the related chapter.

Now you need to copy some files from the symfony package into your project directory. First, create a symfony subdirectory in the data and lib directories of your distant project. Second, transfer the files as follows:

If you're unsure of what to expect, you can download the sandbox to see how a project embedded with the framework should look like. In addition, the sandox creation script details all the operations needed to built a project able to run on its own.

Hint: some hosting providers won't run scripts in php5 unless their suffix is .php5. If this is the case of your distant server, you will need to rename the index.php file found in myproject/web/ into index.php5. Don't bother to rename the other files : since symfony uses a front controller, only the index.php file will have to be declared as a php5 script (learn more about the front controller feature in the controller chapter)

User-contributed guides

The symfony wiki contains a few articles describing step-by-step installations on various platforms.

The forum has a dedicated section where many installation issues have already been solved, and where you will find a symfony user willing to help you in minutes if you have a new problem.