Project creation and the 'symfony' command

Overview

This chapter describes the logical structure of a Symfony project, and details the use of the symfony command to initiate your project structure.

Introduction

In symfony, a project is a set of services and operations available under a given domain name, sharing the same object model.

Inside a project, the operations are grouped logically into applications; an application can normally run independently of the other applications of the same project.

In most cases, a project will contain two applications, one for the front-office, and one for the back-office, sharing the same database. But you can also have one project containing lots of mini-sites, each site being a different application. Note that hyperlinks between applications have to be in the absolute form.

Each application is a set of one or more modules, each module bringing a particular feature. A module usually represents a page or a group of pages with a similar purpose. Example modules could be home, articles, help, shoppingCart, account, etc.

Modules contain actions. They represent the various actions that can be done in a module, for instance a shoppingCart module can have add, show and update actions. Dealing with actions is almost like dealing with pages in a classic web application.

If this represents too many levels for a beginning project, it is very easy to group all actions into one module, so that the file structure can be kept simple. When the application gets more complex, it will be time to organize actions into logical modules.

An application can run in various environments to use, for instance, different configurations or databases. By default, every new application can run in three environments (development, test and production). An application can have as many environments as needed. The difference between environments is the configuration.

For instance, a test environment will log alerts and errors, while a production environment will only log errors. The cache acceleration is often deactivated in a development environment but activated in test and production environments. The development and test environments may need test data, stored in a database distinct from the production one. All environments can live together on the same machine, although a production server generally contains only the production environment.

Note: If you use symfony from a sandbox, you don't need to setup a project nor an application, since the sandbox already has one 'sf_sandbox' project and one 'frontend' application. You don't need to setup the web server either, since your application is in the web/ root directory.

Pake

SymFony uses a dedicated tool called Pake to administer projects, applications, and modules. Pake is a php tool similar to the Rake command, a Ruby translation of the make command. It automates some administration tasks according to a specific configuration file called pakefile.php. But since you use the pake tool just by typing symfony in a command line, everything becomes much simpler than it sounds.

To get the full list of the available administration operations, simply type from your project directory:

$ symfony -T

The description of the CLI tasks used during the early stage of a project follows. A full reference of the CLI tasks is available in the CLI chapter.

Project setup

First of all, you must create the directory that will contain all your project files:

$ mkdir /home/steve/myproject

Then, in order to initialize the project and generate the basic files and directories necessary for runtime, simply type:

$ cd /home/steve/myproject
$ symfony init-project myproject

Here is an overview of the file structure created:

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

Note: If you have specific requirements for your project, symfony can adapt to any custom file structure. All the paths in the symfony scripts use a set of special parameters defined in a file called constants.php, which can be customized as described in the file structure chapter.

The symfony command must always be called from a project root directory (myproject/ in the example above), because all the tasks performed by this command are project specific. If called from one of the project subdirectories, the command will raise an error.

Application Setup

The project is not yet ready to be seen; it requires at least one application. To initialize it, use the symfony init-app command and pass the name of the application as an argument:

$ symfony init-app myapp

This will create a myapp directory in the apps/ folder of the project root, with a default application configuration and a set of directories ready to host the file of your website:

apps/
  myapp/
    config/
    i18n/
    lib/
    modules/
    templates/

Some php files corresponding to the front controllers of each default environment are also created in the project root web directory:

web/
  index.php
  myapp_dev.php

index.php is the production front controller of the new application. Because you created the first application of the project, symfony created a file called index.php instead of myapp.php (if you now add a new application called mynewapp, the new production front controller will be named mynewapp.php). To run your application in the development environment, call the front controller myapp_dev.php.

Note: If you carefully read the introduction, you may wonder where the myapp_test.php file is located. As a matter of fact, the test environment is used to do unit testing of your applications components and doesn't require a front controller. Refer to the unit testing chapter to learn more about it.

From now on, the /home/steve/myproject/ directory will be considered as the root of your project. The root path is stored in a constant called SF_ROOT_DIR, defined in the file index.php, and we will use this name instead of the real path to avoid confusing the readers who aren't named Steve.

Web server setup

To be able to access and test the new application, the web server has to be configured. Here is an example for Apache, where a new VirtualHost is added in the httpd.conf file:

<Directory "/$data_dir/symfony/web/sf">
  AllowOverride All
  Allow from All
</Directory>
<VirtualHost *:80>
  ServerName myapp.example.com
  DocumentRoot "/home/steve/myproject/web"
  DirectoryIndex index.php
  Alias /sf /$data_dir/symfony/web/sf

  <Directory "/home/steve/myproject/web">
    AllowOverride All
    Allow from All
  </Directory>
</VirtualHost>

Note: In the above configuration, the $data_dir placeholders have to be replaced by your PEAR data directory. For example, for *nix, you should type:

    Alias /sf /usr/local/lib/php/data/symfony/web/sf

You will find more about the PEAR directories in the installation chapter.

Restart Apache, and that's it: the newly created application can now be called and viewed through a standard web browser at the url:

http://myapp.example.com/index.php/

or, in debug mode:

http://myapp.example.com/myapp_dev.php/

Note: Symfony uses the mod_rewrite module to display 'smart' urls. If your version of apache is not compiled with mod_rewrite, check that you have the mod_rewrite DSO installed and the following lines in your httpd.conf:

AddModule mod_rewrite.c
LoadModule rewrite_module modules/mod_rewrite.so

You will learn more about the smart urls in the routing chapter.

Symfony is compatible with other server configurations. You can, for instance, access a symfony application using an alias instead of a virtual host. To discover more about web server configuration, refer to the related chapter.

Module setup

Your new application is not very impressive; it dramatically lacks functionalities. If you want functionalities, you need a module to put them into. Once again, the symfony command will be used for that, with the parameters init-module, the application name and the new module name:

$ symfony init-module myapp mymodule

The created tree structure is:

modules/
  mymodule/
    actions/
    config/
    lib/
    templates/
    validate/

The new module is ready to be used:

http://myapp.example.com/index.php/mymodule

Since you need to start getting to work right away, edit the file myapp/modules/mymodule/templates/indexSuccess.php and type in:

Hello, world !

Save it, refresh the page in the browser and voilà!

Source versioning

Once the setup of the application is done, it is recommended to start a source versioning process. Symfony natively supports CVS, although Subversion is recommended. The following examples will show the commands for Subversion, and take for granted that you already have a Subversion server installed and that you wish to create a new repository for your project. For Windows users, a recommended Subversion client is TortoiseSVN. For more information about source versioning and the commands used here, please consult the Subversion documentation.

The example below assumes that $SVNREP_DIR is defined as an environment variable. If you don't have it defined, you will need to substitute the actual location of the repository in place of $SVNREP_DIR.

So let's create the new repository for the myproject project:

$ svnadmin create $SVNREP_DIR/myproject

Then the base structure (layout) of the repository is created with the trunk, tags and branches directories with this pretty long command:

$ svn mkdir -m "layout creation" file:///$SVNREP_DIR/myproject/trunk file:///$SVNREP_DIR/myproject/tags file:///$SVNREP_DIR/myproject/branches

This will be your first revision. Now you have to import the files of the project except the cache and log temporary files:

$ cd /home/steve/myproject
$ rm -rf cache/*
$ rm -rf log/*
$ svn import -m "initial import" . file:///$SVNREP_DIR/myproject/trunk

Check the committed files by typing

$ svn ls file:///$SVNREP_DIR/myproject/trunk/

That seems good. Now the SVN repository has the reference version (and the history) of all your project files. This means that the files of the actual /home/steve/myproject directory need to refer to the repository. To do that, first rename the myproject directory - you will erase it soon if everything works well - and do a checkout of the repository in a new directory:

$ cd /home/steve
$ mv myproject myproject.origin
$ svn co file:///$SVNREP_DIR/myproject/trunk myproject
$ ls myproject

That's it. Now you can work on the files located in /home/steve/myproject/ and commit your modifications to the repository. Don't forget to do some cleanup and erase the myproject.origin directory, which is now useless.

There is one remaining thing to setup. If you commit your working directory to the repository, you may copy some unwanted files, like the ones located in the cache and log directories of your project. So you need to specify an ignore list to svn for this project. You also need to set full access to the cache/ and log/ directories again - SVN doesn't store the access rights:

$ cd /home/steve/myproject
$ svn propedit svn:ignore .
$ chmod 777 cache
$ chmod 777 log

The default text editor configured for SVN should launch. If this doesn't happen, make subversion use your preferred editor by typing

$ export SVN_EDITOR=<name of editor>
$ svn propedit svn:ignore .

Now simply add the subdirectories of myproject that SVN should ignore when committing:

cache
log

Save and quit. You're done.