PHP Configuration
As PHP configurations can vary a lot from one OS to another, or even between different Linux distributions, you need to check that your PHP configuration meets the symfony minimum requirements.
First, ensure that you have PHP 5.2.4 at a minimum installed by using the phpinfo()
built-in function or by running php -v
on the command line. Be aware that on some configurations, you might have two different PHP versions installed: one for the command line, and another for the web.
Then, download the symfony configuration checker script at the following URL:
http://sf-to.org/1.4/check.php
Save the script somewhere under your current web root directory.
Launch the configuration checker script from the command line:
$ php check_configuration.php
If there is a problem with your PHP configuration, the output of the command will give you hints on what to fix and how to fix it.
You should also execute the checker from a browser and fix the issues it might discover. That's because PHP can have a distinct php.ini
configuration file for these two environments, with different settings.
Symfony Installation
Initializing the Project Directory
Before installing symfony, you first need to create a directory that will host all the files related to Jobeet:
$ mkdir -p /home/sfprojects/jobeet
$ cd /home/sfprojects/jobeet
Or on Windows:
c:/> mkdir c:/development/sfprojects/jobeet
c:/> cd c:/development/sfprojects/jobeet
Windows users are advised to run symfony and to setup their new project in a path which contains no spaces. Avoid using the
Documents and Settings
directory, including anywhere underMy Documents
.
If you create the symfony project directory under the web root directory, you won't need to configure your web server. Of course, for production environments, we strongly advise you to configure your web server as explained in the web server configuration section.
Choosing the Symfony Version
Now, you need to install symfony. As the symfony framework has several stable versions, you need to choose the one you want to install by reading the installation page on the symfony website.
This book assumes you want to install symfony 1.3 or symfony 1.4.
Choosing the Symfony Installation Location
You can install symfony globally on your machine, or embed it into each of your project. The latter is the recommended one as projects will then be totally independent from each others. Upgrading your locally installed symfony won't break some of your projects unexpectedly. It means you will be able to have projects on different versions of symfony, and upgrade them one at a time as you see fit.
As a best practice, many people install the symfony framework files in the lib/vendor
project directory. So, first, create this directory:
$ mkdir -p lib/vendor
Installing Symfony
Installing from an Archive
The easiest way to install symfony is to download the archive for the version you choose from the symfony website. Go to the installation page for the version you have just chosen, symfony 1.4 for instance.
Under the "Source Download " section, you will find the archive in .tgz
or in .zip
format. Download the archive, put it under the freshly created lib/vendor/
directory, un-archive it, and rename the directory to symfony
:
$ cd lib/vendor
$ tar zxpf symfony-1.4.0.tgz
$ mv symfony-1.4.0 symfony
$ rm symfony-1.4.0.tgz
Under Windows, unzipping the zip file can be achieved using Windows Explorer. After you rename the directory to symfony
, there should be a directory structure similar to c:/dev/sfprojects/jobeet/lib/vendor/symfony
.
Installing from Subversion (recommended)
If you use Subversion, it is even better to use the svn:externals
property to embed symfony into your project in the lib/vendor/
directory:
$ svn pe svn:externals lib/vendor/
Importing your project in a new Subversion repository is explained at the end of this chapter.
If everything goes well, this command will run your favorite editor to give you the opportunity to configure the external Subversion sources.
On Windows, you can use tools like TortoiseSVN to do everything without the need to use the console.
If you are conservative, tie your project to a specific release (a subversion tag):
symfony http://svn.symfony-project.com/tags/RELEASE_1_4_0
Whenever a new release comes out (as announced on the symfony blog ), you will need to change the URL to the new version.
If you want to go the bleeding-edge route, use the 1.4 branch:
symfony http://svn.symfony-project.com/branches/1.4/
Using the branch makes your project benefits from the bug fixes automatically whenever you run a svn update
.
Installation Verification
Now that symfony is installed, check that everything is working by using the symfony command line to display the symfony version (note the capital V
):
$ cd ../..
$ php lib/vendor/symfony/data/bin/symfony -V
On Windows:
c:/> cd ../..
c:/> php lib/vendor/symfony/data/bin/symfony -V
If you are curious about what this command line tool can do for you, type
symfony
to list the available options and tasks:$ php lib/vendor/symfony/data/bin/symfony
On Windows:
c:/> php lib/vendor/symfony/data/bin/symfony
The symfony command line is the developer's best friend. It provides a lot of utilities that improve your productivity for day-to-day activities like cleaning the cache, generating code, and much more.
Project Setup
In symfony, applications sharing the same data model are regrouped into projects . For most projects, you will have two different applications: a frontend and a backend.
Project Creation
From the sfprojects/jobeet
directory, run the symfony generate:project
task to actually create the symfony project:
$ php lib/vendor/symfony/data/bin/symfony generate:project jobeet
On Windows:
c:/> php lib/vendor/symfony/data/bin/symfony generate:project jobeet
The generate:project
task generates the default structure of directories and files needed for a symfony project:
Directory | Description |
---|---|
apps/ | Hosts all project applications |
cache/ | The files cached by the framework |
config/ | The project configuration files |
lib/ | The project libraries and classes |
log/ | The framework log files |
plugins/ | The installed plugins |
test/ | The unit and functional test files |
web/ | The web root directory (see below) |
Why does symfony generate so many files? One of the main benefits of using a full-stack framework is to standardize your developments. Thanks to symfony's default structure of files and directories, any developer with some symfony knowledge can take over the maintenance of any symfony project. In a matter of minutes, he will be able to dive into the code, fix bugs, and add new features.
The generate:project
task has also created a symfony
shortcut in the project root directory to shorten the number of characters you have to write when running a task.
So, from now on, instead of using the fully qualified path to the symfony program, you can use the symfony
shortcut.
Application Creation
Now, create the frontend application by running the generate:app
task:
$ php symfony generate:app frontend
Because the symfony shortcut file is executable, Unix users can replace all occurrences of '
php symfony
' by './symfony
' from now on.On Windows you can copy the '
symfony.bat
' file to your project and use 'symfony
' instead of 'php symfony
':c:/> copy lib/vendor/symfony/data/bin/symfony.bat .
Based on the application name given as an argument , the generate:app
task creates the default directory structure needed for the application under the apps/frontend/
directory:
Directory | Description |
---|---|
config/ | The application configuration files |
lib/ | The application libraries and classes |
modules/ | The application code (MVC) |
templates/ | The global template files |
Security
By default, the
generate:app
task has secured our application from the two most widespread vulnerabilities found on the web. That's right, symfony automatically takes security measures on our behalf.To prevent XSS attacks, output escaping has been enabled; and to prevent CSRF attacks, a random CSRF secret has been generated.
Of course, you can tweak these settings thanks to the following options :
--escaping-strategy
: Enables or disables output escaping--csrf-secret
: Enables session tokens in formsIf you know nothing about XSS or CSRF , take the time to learn more these security vulnerabilities.
Directory Structure Rights
Before trying to access your newly created project, you need to set the write permissions on the cache/
and log/
directories to the appropriate levels, so that your web server can write to them:
$ chmod 777 cache/ log/
Tips for People using a SCM Tool
symfony only ever writes in two directories of a symfony project,
cache/
andlog/
. The content of these directories should be ignored by your SCM (by editing thesvn:ignore
property if you use Subversion for instance).
Web Server Configuration: The ugly Way
If you have created the project directory it somewhere under the web root directory of your web server, you can already access the project in a web browser.
Of course, as there is no configuration, it is very fast to set up, but try to access the config/databases.yml
file in your browser to understand the bad consequences of such a lazy attitude. If the user knows that your website is developed with symfony, he will have access to a lot of sensitive files.
Never ever use this setup on a production server , and read the next section to learn how to configure your web server properly.
Web Server Configuration: The secure Way
A good web practice is to put under the web root directory only the files that need to be accessed by a web browser, like stylesheets, JavaScripts and images. By default, we recommend to store these files under the web/
sub-directory of a symfony project.
If you have a look at this directory, you will find some sub-directories for web assets (css/
and images/
) and the two front controller files. The front controllers are the only PHP files that need to be under the web root directory. All other PHP files can be hidden from the browser, which is a good idea as far as security is concerned.
Web Server Configuration
Now it is time to change your Apache configuration, to make the new project accessible to the world.
Locate and open the httpd.conf
configuration file and add the following configuration at the end:
# Be sure to only have this line once in your configuration
NameVirtualHost 127.0.0.1:8080
# This is the configuration for your project
Listen 127.0.0.1:8080
<VirtualHost 127.0.0.1:8080>
DocumentRoot "/home/sfprojects/jobeet/web"
DirectoryIndex index.php
<Directory "/home/sfprojects/jobeet/web">
AllowOverride All
Allow from All
</Directory>
Alias /sf /home/sfprojects/jobeet/lib/vendor/symfony/data/web/sf
<Directory "/home/sfprojects/jobeet/lib/vendor/symfony/data/web/sf">
AllowOverride All
Allow from All
</Directory>
</VirtualHost>
The
/sf
alias gives you access to images and javascript files needed to properly display default symfony pages and the web debug toolbar|Web Debug Toolbar.On Windows, you need to replace the
Alias
line with something like:Alias /sf "c:/dev/sfprojects/jobeet/lib/vendor/symfony/data/web/sf"
And
/home/sfprojects/jobeet/web
should be replaced with:c:/dev/sfprojects/jobeet/web
This configuration makes Apache listen to port 8080
on your machine, so the website will be accessible at the following URL:
http://localhost:8080/
You can change 8080
to any number, but favour numbers greater than 1024
as they do not require administrator rights.
Configure a dedicated Domain Name
If you are an administrator on your machine, it is better to setup virtual hosts instead of adding a new port each time you start a new project. Instead of choosing a port and add a
Listen
statement, choose a domain name (for instance the real domain name with.localhost
added at the end) and add aServerName
statement:# This is the configuration for your project
<VirtualHost 127.0.0.1:80>
ServerName www.jobeet.com.localhost
<!-- same configuration as before -->
</VirtualHost>
The domain name
www.jobeet.com.localhost
used in the Apache configuration has to be declared locally. If you run a Linux system, it has to be done in the/etc/hosts
file. If you run Windows XP, this file is located in theC:/WINDOWS/system32/drivers/etc/
directory.Add in the following line:
127.0.0.1 www.jobeet.com.localhost
Test the New Configuration
Restart Apache, and check that you now have access to the new application by opening a browser and typing http://localhost:8080/index.php/
, or http://www.jobeet.com.localhost/index.php/
depending on the Apache configuration you chose in the previous section.
If you have the Apache
mod_rewrite
module installed, you can remove theindex.php/
part of the URL. This is possible thanks to the rewriting rules configured in theweb/.htaccess
file.
You should also try to access the application in the development environment (see the next section for more information about environments). Type in the following URL:
http://www.jobeet.com.localhost/frontend_dev.php/
The web debug toolbar should show in the top right corner, including small icons proving that your sf/
alias configuration is correct.
The setup is a little different if you want to run symfony on an IIS server in a Windows environment. Find how to configure it in the related tutorial .