File structure explained

Overview

The tree structure of a symfony project is consistent, although it can be completely customized. This chapter will help you to get used to this structure and to understand the logic behind it.

Introduction

All web projects generally share the same architectural needs:

• database
• static files (HTML, images, javascripts, stylesheets, etc.)
• files uploaded by the site users and administrators
• PHP classes and libraries
• foreign libraries
• batch files
• log files
• configuration files
• etc.

To allow developers to adapt to any existing symfony project, it is recommended to follow the default tree structure described below. This also speeds up project creation, since the default tree structure is automatically created when initializing every project, application or module.

Root tree structure

These are the directories found at the root of a symfony project:

apps/
  fo/
  bo/
batch/
cache/
config/
data/
  sql/
doc/
  api/
lib/
  model/
log/
test/
web/
  css/
  images/
  js/
  uploads/

The batch directory is used for php files called from a command line or a scheduler to run batch processes.

The cache of the project, used to speed up the answer to web requests, is located in the cache directory. Each application will have a subdirectory in there, containing preprocessed HTML and configuration files.

The general configuration of the project is stored in the config directory.

In the data directory, you can store the data files of the project, like a database schema, a SQL file that creates tables, or even a SQLite database itself if you need.

The doc directory stores the project documentation, including your own documents and the documentation generated by phpdoc (in the api subdirectory).

The lib directory is dedicated to foreign classes or libraries. Here you can add the code that needs to be shared among your applications. The model subdirectory stores the object model of the project.

The log directory stores the applicable log files generated directly by symfony. It can also contain web server log files, database log files or log files from any part of the project. There is normally one file per application and per environment (ex: myapp_prod.log)

The test directory contains unit tests written in PHP and compatible with the SimpleTest testing framework. During the project setup, symfony automatically adds some stubs with a few basic tests.

The web directory is the root for the web server. The only files accessible from the Internet are the ones located in this directory. It will be described in detail in a few moments.

Last but not least, the apps directory contains one directory for each application of the project (typically fo and bo for the front and back office, myapp in the example).

Application tree structure

The tree structure of all application directories is the same:

config/
i18n/
lib/
modules/
templates/
  layout.php
  error.php
  error.txt

The config directory holds a hefty set of YAML configuration files. This is where most of the application configuration is, apart from the default parameters that can be found in the framework itself. Note that the default parameters can still be overridden here if needed. You can find more about application configuration in the next chapter.

The i18n directory contains files used for the internationalization of the application. These files can be in the XLIFF or in the GetText format. You can even bypass this directory if you choose to use a database for your internationalization.

The lib directory contains classes and libraries that are specific to the application.

The modules directory stores all the modules that contain the features of the application.

The templates directory lists the global templates of the application, the ones that are shared by all modules. By default, it contains a layout.php file, which is the main layout in which the module templates are inserted; an error.php file, used to output errors on a web request; and a error.txt file used to output errors when the application is called without a web browser (for instance during unit tests). Other global templates are to be added here - if your application uses popups sharing the same layout, you could add a popuplayout.php for example.

The directories i18n, lib and modules are empty for a new application.

The directory name of an application is to be determined during its setup. This name is accessible via the sfConfig object by referencing sfConfig::get('sf_app_dir').

The classes of an application are not able to access methods or attributes in other applications of the same project. Also note that hyperlinks between two applications of the same project must be in absolute form.

Module tree structure

Each application contains one or more modules. Each module has its own subdirectory in the modules directory, and the name of this directory is chosen during the setup.

This is the typical tree structure of a module:

actions/
  actions.class.php
config/
lib/
templates/
  indexSuccess.php
validate/

The actions directory generally contains a single class named actions.class.php, in which you can store all the actions of the module. Different actions of a module can also be written in separate files.

The config directory can contain custom configuration files with local parameters for the module.

The lib directory contains classes and libraries specific to the module.

The templates directory contains the templates corresponding to the actions of the module. A default template is created during module setup, called indexSuccess.php.

And the validate directory is dedicated to configuration files used for form validation.

The directories config, lib and validate are empty for a new module.

Web tree structure

There are very few constraints for the web directory, but following a few basic naming conventions will provide default behaviors and useful shortcuts in the templates.

Conventionally, the static files are distributed in the following directories:

• css/: stylesheets with a .css extension
• js/: javascripts with a .js extension
• images/: images with a .jpg, .png or .gif format

The files uploaded by the users have to be stored in the uploads directory. Even though, most of the time, the uploads directory contains images, it is distinct from the image directory so that the synchronization of the development and production environments does not affect the uploaded images.

Tree structure customization

Even if it is highly recommended to keep the default tree structure, it is possible to modify it for specific needs, for instance in order to match the requirements of a client who already has its own tree structure and coding conventions.

Every path to a key directory is determined by a parameter ending with _dir. These parameters are defined in the framework, in a file called $pear_data_dir/symfony/config/constants.php, used by every symfony project. To customize the tree structure of an application, you simply need to override these settings. For that, use the config.php file located in the apps/myapp/config/ directory (for an application-wide directory structure), or the config/config.php (for a project-wide structure).

You will probably have to copy the default configuration from the symfony directory if you need to modify it. Here is an extract of the default configuration:

// root directory structure
'sf_cache_dir_name'   => 'cache',
'sf_log_dir_name'     => 'log',
'sf_lib_dir_name'     => 'lib',
'sf_model_dir_name'   => 'model',
'sf_web_dir_name'     => 'web',
'sf_data_dir_name'    => 'data',
'sf_config_dir_name'  => 'config',
'sf_apps_dir_name'    => 'apps',
 
// global directory structure
'sf_app_dir'        => $sf_root_dir.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.$sf_app,
'sf_model_dir'      => $sf_root_dir.DIRECTORY_SEPARATOR.'model',
'sf_lib_dir'        => $sf_root_dir.DIRECTORY_SEPARATOR.'lib',
'sf_web_dir'        => $sf_root_dir.DIRECTORY_SEPARATOR.'web',
'sf_upload_dir'     => $sf_root_dir.DIRECTORY_SEPARATOR.'web'.DIRECTORY_SEPARATOR.'uploads',
'sf_base_cache_dir' => $sf_root_dir.DIRECTORY_SEPARATOR.'cache'.DIRECTORY_SEPARATOR.$sf_app,
'sf_cache_dir'      => $sf_root_dir.DIRECTORY_SEPARATOR.'cache'.DIRECTORY_SEPARATOR.$sf_app.DIRECTORY_SEPARATOR.$sf_environment,
'sf_log_dir'        => $sf_root_dir.DIRECTORY_SEPARATOR.'log',
'sf_data_dir'       => $sf_root_dir.DIRECTORY_SEPARATOR.'data',
'sf_config_dir'     => $sf_root_dir.DIRECTORY_SEPARATOR.'config',

Names and paths are both defined here. While this file is not that easy to read, it is easy to modify.

Important: It is strongly recommended to use these parameters (via the sfConfig object) instead of their values when building and coding a project. That way, the applications created can be independent of the tree structure, more particularly for the first level directories.

 [php]
 // always prefer
 if(file_exists(sfConfig::get('sf_log_dir').'myLogFile.log'))
 // instead of
 if(file_exists('/home/myproject/log/myLogFile.log'))

For instance, if you want your file structure to look like this (it is a standard shared host structure):

cgi-bin/
  apps/
    fo/
    bo/
  batch/
  cache/
  config/
  data/
    sql/
  doc/
    api/
  lib/
    model/
  log/
  test/
public_html/
  css/
  images/
  js/
  uploads/
  index.php

Change the SF_ROOT_DIR constant defined in the index.php (and the other front controllers) from:

define('SF_ROOT_DIR', realpath(dirname(__FILE__).'/..'));

to

define('SF_ROOT_DIR', realpath(dirname(__FILE__).'/../../cgi-bin'));

Then add the following lines to your config/config.php:

$sf_root_dir = sfConfig::get('sf_root_dir');   
sfConfig::add(array(
  'sf_web_dir_name' => $sf_web_dir_name    = 'public_html',
  'sf_web_dir'      => $sf_root_dir.DIRECTORY_SEPARATOR.'..'.DIRECTORY_SEPARATOR.$sf_web_dir_name,
  'sf_upload_dir'   => $sf_root_dir.DIRECTORY_SEPARATOR.'..'.DIRECTORY_SEPARATOR.$sf_web_dir_name.DIRECTORY_SEPARATOR.$sf_upload_dir_name,       
));