⚠️ Technical skills needed: to follow this post, you need a basic understanding of PHP language and of Unix-like Shell scripting.

It’s been a while since I started using the Symfony Framework. Here are some lessons learned after setting up some Symfony 2 projects.

Before you start: set up a development environment

Most frequently, the development environment is your PC (running WAMP, MAMP or any other PHP application server and Db server), whilst the test and/or production environment is a remote server that you reach via FTP or SSH.

I highly recommend that you use an IDE to help you automating certain tasks, like the creation of bundles, controllers or entities. There are dozens, just pick the one you prefer.

Some Free IDEs: NetBeans, Eclipse, Aptana studio.

Install Symfony and these must-have bundles

Start by installing Symfony 2 in your development environment.

📣 Learn how to install Symfony here.

These three bundles definitely make Symfony development easier:

1. FOS (Friends Of Symfony) User Bundle

Handles user accounts, including two-step activation, forgot password automated emails, and more.

2. Doctrine Migrations

Allows for a smarter management of db schema updates. In fact, the console command app/console doctrine:schema:update which is the default choice, sometimes will just refuse to work because of foreign keys constraints.

3. Doctrine Extensions

Automates several database operations. Just to mention a few ones:

To install them, first of all, edit the composer.json  file located in the root folder of your Symfony install, adding the following lines to the require   section:

1
2
3
4
5
6
7

"require": {
    ...
    "friendsofsymfony/user-bundle": "~2.0@dev",
    "stof/doctrine-extensions-bundle": "~1.1@dev",
    "doctrine/migrations": "dev-master",
    "doctrine/doctrine-migrations-bundle": "dev-master"
}

Then, issue the following command to download the bundles:

php composer.phar update

⚠️ Please note: Composer is not part of Symfony.

Next, you’ll have to configure the bundles.

📣 Learn how to configure FOSUserBundle here.

Create a ViewBundle and its controllers

I usually have one bundle to manage all the view, and I call it MyApp/ViewBundle.

This bundle is responsible for all the rendering actions: HTML pages, JSON responses and dynamically generated files (like e.g. Xlsx and Pdf files) will all be rendered by an action (a function) in a controller of MyApp/ViewBundle .

📣 Learn how to generate a Symfony bundle here.

Controllers: you’d better keep’em separated

Inside MyApp/ViewBundle I usually create one controller per output type. This allows me to instantly know which source file to edit when I want to change e.g. a JSON feed.

1. HTML pages: Symfony adds a controller to each auto-generated bundle and calls it DefaultController. I usually leave this controller to render HTML pages only;
2. JSON/REST responses: handled by a controller called RestController; the output of the actions in there is always a JSON object;
3. File downloads: handled by a controller called DownloadController .

📣 Learn how to generate a Symfony controller here.

Choose a deploy technique

As I wrote above, most commonly you’ll develop locally on your machine, and then upload the sources to a production environment -a remote server- via FTP or SSH.

Personally I prefer having SSH access to the production machine, because it gives you fine-grained control.

It is not always possible, e.g. in shared hostings, but if this is your case, you can set up a deploy shell script using the template in the following section.

SSH + rsync deploy

This deploy strategy will do a one-way synchronization of your development and production machines (that is, it will copy newer source files from development to production).

You’ll need:

• a Unix-like Shell – it won’t run easily on Windows systems, unless you use a bash emulator like CygWin;
• the rsync command on your development machine;
• SSH access to the production machine – you won’t have it in a shared hosting environment;
• passwordless SSH access to production – see how to set it up on MacOS here or on Linux here.
• a list of the files that must not be synchronized, to be placed in app/config/rsync_exclude.txt . A sample of this file is provided below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

deploy.sh
- app/config/rsync_exclude.txt
.*
*.md
*.pem
sftp-*.json
nbproject
- app/cache
- app/logs
- app/config/parameters.yml
- app/DoctrineMigrations/*

Let’s see the meaning of each line.

• deploy.sh and app/config/rsync_exclude.txt : do not copy the deploy script and the list to production;
• .*,  *.md, *.pem : respectively, hidden and system files, markdown files and private ssh keys;
• sftp-*.json and nbproject: reserved files of Sublime Text (a text editor) and Netbeans, respectively – you don’t want to sync them.

The following directories and files are all server-specific.

• app/cache and app/logs  : syncing them would only create  problems and confuse Symfony on the production machine;
• app/config/parameters.yml : you’ll have at least different database passwords for development and production machines (if you don’t, please change one of them immediately! 🙂 ).
• app/DoctrineMigrations/ is where the db migrations will be stored. This is also specific to a server, and most frequently you’ll make many more updates to the db structure in development than in production. Anyway, syncing it would be a bad idea.

A sample deploy script can be found below.

❗ Please note: this script won’t work out of the box. To make it work, please change the paths according to your local and remote environments.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

#!/bin/bash
#
# Symfony2 Project Name
# =====================
# Deploy to prod server
#
# Save this file in the root of your Symfony project
# and make it executable e.g. with:
# chmod u+x deploy.sh
#
# Create an exclusion file named app/config/rsync_exclude.txt *before* you run this script.
#
# All paths are just examples
# *No* trailing slashes in the paths please! ;-)
#
LOCAL_DIR='/Users/[you]/Sites/[your_project_path]'
REMOTE_DIR='/var/www/[your_project_path]'
PHP_EXE='php'

# Passwordless connection alias
REMOTE=remote_alias
# Here you should specify the user and group under which your webserver is running
# Usually it is www-data for both
REMOTE_USER=user[:group]

cd $LOCAL_DIR

echo ". Deploying files ..."
rsync -rlptvz ./ $REMOTE:$REMOTE_DIR --exclude-from=./app/config/rsync_exclude.txt
echo ". Done deploy."

echo ". Post deploy remote operations ..."

# Update remote Symfony configuration file
# If you prefer not to handle remote config from the development machine, just add
# app/config/parameters.yml
# to the rsync_exclude.txt file
ssh $REMOTE "cp $REMOTE_DIR/app/config/parameters.remote.yml $REMOTE_DIR/app/config/parameters.yml"

# Migrate database if needed
echo ". Updating db schema..."
ssh $REMOTE "$PHP_EXE $REMOTE_DIR/app/console doctrine:migrations:diff"
ssh $REMOTE "$PHP_EXE $REMOTE_DIR/app/console doctrine:migrations:migrate"

# Clear remote Symfony cache in both environments
ssh $REMOTE "$PHP_EXE $REMOTE_DIR/app/console cache:clear --no-warmup"
ssh $REMOTE "$PHP_EXE $REMOTE_DIR/app/console cache:clear --no-warmup --env=prod"

echo ". Dumping assets..."
ssh $REMOTE "$PHP_EXE $REMOTE_DIR/app/console assetic:dump"
ssh $REMOTE "$PHP_EXE $REMOTE_DIR/app/console assetic:dump --env=prod"

echo ". Making directories writable by web server..."
ssh $REMOTE "chown -R $REMOTE_USER $REMOTE_DIR/app/cache/ $REMOTE_DIR/app/logs/ $REMOTE_DIR/src $REMOTE_DIR/web"
echo ". Deploy completed."