As you've learned in previous chapters, the symfony framework is a set of files written in PHP. A symfony project uses these files, so installing symfony means getting these files and making them available for the project.
Being a PHP 5 framework, symfony requires PHP 5. Make sure you have it installed by opening a command line and typing this command:
> php -v
PHP 5.2.0 (cli) (built: Nov 2 2006 11:57:36)
Copyright (c) 1997-2006 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2006 Zend Technologies
If the version number is 5.0 or higher, then you're ready for the installation, as described in this chapter.
Installing the Sandbox
If you just want to see what symfony is capable of, you'll probably go for the fast installation. In that case, you need the sandbox.
The sandbox is a simple archive of files. It contains an empty symfony project including all the required libraries (symfony, pake, lime, Creole, Propel, and Phing), a default application, and basic configuration. It will work out of the box, without specific server configuration or any additional packages.
To install it, download the sandbox archive from http://www.symfony-project.org/get/sf_sandbox.tgz. Unpack it under the root web directory configured for your server (usually
www/). For the purposes of uniformity, this chapter will assume you unpacked it to the directory
Having all the files under the root web directory is fine for your own tests in a local host, but is a bad practice in a production server. It makes all the internals of your application visible to end users.
Test your installation by executing the symfony CLI. Go to the new
sf_sandbox/ directory and type the following on a *nix system:
> ./symfony -V
On Windows, issue this command:
> symfony -V
You should see the sandbox version number:
symfony version 1.0.0
Now make sure that your web server can browse the sandbox by requesting this URL:
You should see a congratulations page that looks like Figure 3-1, and it means that your installation is finished. If not, then an error message will guide you through the configuration changes needed. You can also refer to the "Troubleshooting" section later in this chapter.
Figure 3-1 - Sandbox congratulations page
The sandbox is intended for you to practice with symfony on a local computer, not 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.
To uninstall a sandbox, just remove the
sf_sandbox/ directory from your
Installing the Symfony Libraries
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 host already has symfony installed). For each server, you will probably want to avoid duplication by keeping all the symfony files in a single place, whether you develop only one application or several applications.
Since the symfony framework evolves quickly, a new stable version could very well be released only a few days after your first installation. You need to think of the framework upgrade as a major concern, and that's another reason why you should share one instance of the symfony libraries across all your symfony projects.
When it comes to installing the libraries for a real application development, you have two alternatives:
- The PEAR installation is recommended for most people. It can be easily shared and upgraded, and the installation process is straightforward.
- The Subversion (SVN) installation is meant to be used only by advanced PHP developers, who want to take advantage of the latest patches, add features of their own, and/or contribute to the symfony project.
Symfony integrates a few other packages:
- pake is a CLI utility.
- lime is a unit testing utility.
- Creole is a database abstraction engine. Just like PHP Data Objects (PDO), it provides an interface between your code and the database SQL code, and makes it possible to switch to another engine.
- Propel is for ORM. It provides object persistence and query service.
- Phing is a CLI for Propel.
Pake and lime are developed by the symfony team. Creole, Propel, and Phing come from another team and are released under the GNU Lesser Public General License (LGPL). All these packages are bundled with symfony.
Installing the Symfony PEAR Package
The symfony PEAR package contains the symfony libraries and all its dependencies. It also contains a script that will extend your CLI to include the
The first step to install it is to add the symfony channel to PEAR, by issuing this command:
> pear channel-discover pear.symfony-project.com
To see the libraries available in this channel, type the following:
> pear remote-list -c symfony
Now you are ready to install the latest stable version of symfony. Issue this command:
> pear install symfony/symfony
downloading symfony-1.0.0.tgz ...
Starting to download symfony-1.0.0.tgz (1,283,270 bytes)
.............done: 1,283,270 bytes
install ok: channel://pear.symfony-project.com/symfony-1.0.0
That's it. The symfony files and CLI are installed. Check that the installation succeeded by calling the new
symfony command line, asking for the version number:
> symfony -V
symfony version 1.0.0
If you prefer to install the most recent beta, which has the latest bug fixes and enhancements, type
pear install symfony/symfony-beta instead. Beta releases are not completely stable and are generally not recommended for production environments.
The symfony libraries are now installed in directories as follows:
$php_dir/symfony/ contains the main libraries.
$data_dir/symfony/ contains the skeleton of symfony applications; default modules; and configuration, i18n data, and so on.
$doc_dir/symfony/ contains the documentation.
$test_dir/symfony/ contains unit tests.
The _dir variables are part of your PEAR configuration. To see their values, type the following:
> pear config-show
Checking Out Symfony from the SVN Repository
For production servers, or when PEAR is not an option, you can download the latest version of the symfony libraries directly from the symfony Subversion repository by requesting a checkout:
> mkdir /path/to/symfony
> cd /path/to/symfony
> svn checkout http://svn.symfony-project.com/tags/RELEASE_1_0_0/ .
symfony command, available only for PEAR installations, is a call to the
/path/to/symfony/data/bin/symfony script. So the following would be the equivalent to the
symfony -V command for an SVN installation:
> php /path/to/symfony/data/bin/symfony -V
symfony version 1.0.0
If you chose an SVN installation, you probably already have an existing symfony project. For this project to make use of the symfony files, you need to change the two variables defined in your project's
config/config.php file, as follows:
$sf_symfony_lib_dir = '/path/to/symfony/lib/';
$sf_symfony_data_dir = '/path/to/symfony/data/';
Chapter 19 proposes other ways to link a project with a symfony installation (including symbolic links and relative paths).
Alternatively, you can also download the PEAR package (http://pear.symfony-project.com/get/symfony-1.0.0.tgz) and unpack it somewhere. You will have the same result as with a checkout.