Configuring Symfony

#5

The Definitive Guide to symfony
Configuring symfony
Doc. v. 0.1 - 20/05/09

Wildan Maulana | wildan [at] tobethink.com

How the Configuration System Works

• The symfony configuration is kept in files written in
YAML, although you can always choose another format.
• Configuration files are at the project, application, and
module levels in a project's directory structure.
• You can define several sets of configuration settings; in
symfony, a set of configuration is called an
environment.
• The values defined in the configuration files are
available from the PHP code of your application.
• Additionally, symfony authorizes PHP code in YAML files
and other tricks to make the configuration system even
more flexible.

The Configuration System
• Ambition of the configuration system in symfony :
– Powerful: Almost every aspect that can be managed
using configuration files is managed using configuration
files.
– Simple: Many aspects of configuration are not shown in a
normal application, since they seldom need to be
changed.
– Easy: Configuration files are easy to read, to modify, and
to create by the developer.
– Customizable: The default configuration language is
YAML, but it can be INI, XML, or whatever format the
developer prefers.
– Fast: The configuration files are never processed by the
application but by the configuration system, which
compiles them into a fast-processing chunk of code for
the PHP server.

YAML Syntax and Symfony Conventions
Defining Long and Multiline Strings
YAML Files Forbid Tabs # Folded style, introduced by >
# Each line break is folded to a space
# Never use tabs # Makes YAML more readable
all: accomplishment: >
-> mail: Mark set a major league
-> -> webmaster: webmaster@example.com home run record in 1998.

# Use blanks instead # Literal style, introduced by |
all: # All line breaks count
mail: # Indentation doesn't appear in the resulting string
webmaster: webmaster@example.com stats: |
65 Home Runs
Nonstandard Strings Should Be 0.278 Batting Average
Enclosed in Single Quotes

error1: This field is compulsory
error2: ' This field is compulsory '
error3: 'Don''t leave this field blank' # Single quotes must be doubled

YAML Syntax and Symfony Conventions #2
YAML Array Syntax
YAML Boolean Values Syntax
# Shorthand syntax for arrays
players: [ Mark McGwire, Sammy Sosa, Ken Griffey ]
true_values: [ on, 1, true ]
# Expanded syntax for arrays false_values: [ off, 0, false ]
players:
- Mark McGwire
- Sammy Sosa
- Ken Griffey

YAML Associative Array Syntax

# Incorrect syntax, blanks are missing after the colon
mail: {webmaster:webmaster@example.com,contact:contact@example.com}

# Correct shorthand syntax for associative arrays
mail: { webmaster: webmaster@example.com, contact: contact@example.com }

# Expanded syntax for associative arrays
mail:
webmaster: webmaster@example.com
contact: contact@example.com


YAML Comments Syntax and Value Alignment

# This is a comment line
mail:
admin: admin@example.com # extra spaces allow nice alignment of values

Default Configuration Is Shown Commented

# The cache is off by default
settings:
# cache: off

# If you want to change this setting, uncomment the line first
settings:
cache: on


Category Headers Look Like Keys, But Start with a Dot

all:
.general:
tax: 19.6

mail:

Category Headers Are Only There for Readability and Are Actually Ignored

all:
tax: 19.6

mail:

Help, a YAML File Killed My App!

If your application suddenly stops working after a configuration change,
you should check that you didn't make any of the common mistakes
of the inattentive YAML coder:

You miss a space between a key and its value:

key1:value1 # A space is missing after the :

Keys in a sequence are not indented the same way:

all:
key1: value1
key2: value2 # Indentation is not the same as the other sequence members
key3: value3

There is a reserved YAML character in a key or a value, without string delimiters:

message: tell him: go way # :, [, ], { and } are reserved in YAML
message: 'tell him: go way' # Correct syntax

Help, a YAML File Killed My App!

You are modifying a commented line:
# key: value # Will never be taken into account due to the leading #

You set values with the same key name twice at the same level:

key1: value1
key2: value2
key1: value3 # key1 is defined twice, the value is the last one defined

You think that the setting takes a special type, while it is always a string, until you convert it:

income: 12,345 # Until you convert it, this is still a string

Overview of the Configuration Files

• Project Configuration
• Application Configuration
• Front Controller Configuration
• Main Application Configuration
• Internationalization Configuration
• Additional Application Configuration
• Module Configuration

Project Configuration
• There are a few project configuration files by default. Here are the
files that can be found in the myproject/config/ directory:
– ProjectConfiguration.class.php: This is the very first file included by any
request or command. It contains the path to the framework files, and you can
change it to use a different installation.
– databases.yml: This is where you define the access and connection settings to
the database (host, login, password, database name, and so on).It can also be
overridden at the application level.
– properties.ini: This file holds a few parameters used by the command line tool,
including the project name and the connection settings for distant servers.
– rsync_exclude.txt: This file specifies which directories must be excluded from the
synchronization between servers.
– schema.yml and propel.ini: These are data access configuration files used by
Propel (symfony's ORM layer). They are used to make the Propel libraries work
with the symfony classes and the data of your project. schema.yml contains a
representation of the project's relational data model. propel.ini is automatically
generated, so you probably do not need to modify it. If you don't use Propel, these
files are not needed.

Application Configuration
• The main part of the configuration is the application
configuration. It is defined in the front controller (in the web/
directory) for the main configuration, in YAML files located in
the application config/ directory, in i18n/ directories for the
internationalization files, and in the framework files for
invisible--although useful--additional application
configuration.

Front Controller Configuration
The Default Production Front Controller
<?php

require_once(dirname(__FILE__).'/../config/ProjectConfiguration.class.php');

$configuration = ProjectConfiguration::getApplicationConfiguration('frontend', 'prod', false);
sfContext::createInstance($configuration)->dispatch();

Some Methods available in the application configuration class :
• $configuration->getRootDir(): Project root directory (normally, should remain at its default value,
unless you change the file structure).

• $configuration->getApplication(): Application name in the project. Necessary to compute file paths.

• $configuration->getEnvironment(): Environment name (prod, dev, or any other project-specific
environment that you define). Will determine which configuration settings are to be used.

• $configuration->isDebug(): Activation of the debug mode

Main Application Configuration
The main application configuration is stored in files located in the
myproject/apps/frontend/config/ directory:
Configuration File Description

app.yml This file should contain the application-specific configuration; that is, global variables
defining business or applicative logic specific to an application, which don't need to
be stored in a database. Tax rates, shipping fares, and e-mail addresses are often
stored in this file. It is empty by default.
frontendConfiguration.class.php This class bootstraps the application, which means that it does all the very basic
initializations to allow the application to start. This is where you can customize your
directory structure or add application-specific constants (Chapter 19 provides more
details). It inherits from the sfApplicationConfiguration class.
factories.yml Symfony defines its own class to handle the view, the request, the response, the
session, and so on. If you want to use your own classes instead, this is where you
can specify them
filters.yml Filters are portions of code executed for every request. This file is where you define
which filters are to be processed, and it can be overridden for each module.
routing.yml The routing rules, which allow transforming unreadable and unbookmarkable URLs
into quot;smartquot; and explicit ones, are stored in this file. For new applications, a few
default rules exist.
settings.yml The main settings of a symfony application are defined in this file. This is where you
specify if your application has internationalization, its default language, the request
timeout and whether caching is turned on. With a one-line change in this file, you
can shut down the application so you can perform maintenance or upgrade one of
its components.
view.yml The structure of the default view (name of the layout, default style sheets and
JavaScript files to be included, default content-type, and so on) is set in this file.
These settings can be overridden for each module.

Internationalization Configuration

• Internationalized applications can display pages in several
languages. This requires specific configuration. There are two
configuration places for internationalization:
– The factories.yml of the application config/ directory:
This file defines the i18n factory and general translation
options, such as the default culture for the translation,
whether the translations come from files or a database,
and their format.
– Translation files in the application i18n/ directory: These
are basically dictionaries, giving a translation for each of
the phrases used in the application templates so that the
pages show translated text when the user switches
language.

Additional Application Configuration

• The configuration files in the symfony installation config/ directory
($sf_symfony_lib_dir/config/config/) :
– autoload.yml: This file contains the settings of the autoloading feature.
This feature exempts you from requiring custom classes in your code if
they are located in specific directories.
– core_compile.yml and bootstrap_compile.yml: These are lists of
classes to be included to start an application (in bootstrap_compile.yml)
and to process a request (in core_compile.yml). These classes are
actually concatenated into an optimized PHP file without comments,
which will accelerate the execution by minimizing the file access
operations (one file is loaded instead of more than forty for each
request). This is especially useful if you don't use a PHP accelerator.
– config_handlers.yml: This is where you can add or modify the handlers
used to process each configuration file.
–

Module Configuration
• By default, a module has no specific configuration. But, if required,
you can override some application-level settings for a given module.
For instance, you might do this to include a specific JavaScript file
for all actions of a module. You can also choose to add new
parameters restricted to a specific module to preserve
encapsulation.
• myproject/apps/frontend/modules/mymodule/config/
– generator.yml: For modules generated according to a database table
(scaffoldings and administrations), this file defines how the interface displays
rows and fields, and which interactions are proposed to the user (filters,
sorting, buttons, and so on).
– module.yml: This file contains custom parameters specific to a module
(equivalent to the app.yml, but at the module level) and action configuration.
– security.yml: This file sets access restrictions for actions. This is where you
specify that a page can be viewed only by registered users or by a subset of
registered users with special permissions.
– view.yml: This file contains configuration for the views of one or all of the
actions of a module.

Too many files?
You might be overwhelmed by the number of configuration files present in
the application. But please keep the following in mind:

Most of the time, you don't need to change the configuration, since
the default conventions match the most common requirements.
Each configuration file is related to a particular feature, and the next slide
will detail their use one by one. When you focus on a single file,
you can see clearly what it does and how it is organized. For professional
web development, the default configuration is often not completely adapted.
The configuration files allow for an easy modification of the symfony
mechanisms without code. Imagine the amount of PHP code necessary
to achieve the same amount of control. If all the configuration were located
in one file, not only would the file be completely unreadable,
but you could not redefine configuration at several levels
(see the quot;Configuration Cascadequot; section later in this chapter).

The configuration system is one of the great strengths of symfony,
because it makes symfony usable for almost every kind of web application,
and not only for the ones for which the framework was originally designed.

Environments
• What Is an Environment?

Configuration Cascade
• There are several configuration levels in symfony:
– Granularity levels:
• The default configuration located in the framework
• The global configuration for the whole project (in myproject/config/)
• The local configuration for an application of the project (in
myproject/apps/frontend/config/)
• The local configuration restricted to a module The Structure of Symfony Configuration File
(in myproject/apps/frontend/modules
/mymodule/config/) # Production environment settings
prod:
– Environment levels: ...
• Specific to one environment
# Development environment settings
• For all environments dev:
...

# Test environment settings
test:
...

# Custom environment settings
myenv:
...

# Settings for all environments
all:
...

The Configuration Cache

all: # Setting for all environments
mail:

<?php

sfConfig::add(array(
'app_mail_webmaster' => 'webmaster@example.com',
));

Accessing the Configuration from Code
All the configuration files are eventually transformed into PHP, and many of the
settings they contain are automatically used by the framework,
without further intervention. However, you sometimes need to access some of
the settings defined in the configuration files from your code
(in actions, templates, custom classes, and so on). The settings defined in
settings.yml, app.yml, and module.yml are available through a special class
called sfConfig.

// Retrieve a setting
parameter = sfConfig::get('param_name', $default_value);

// Define a setting
sfConfig::set('param_name', $value);

Accessing the Configuration from Code #2

• The parameter name is the concatenation of several elements, separated by
underscores, in this order:
– A prefix related to the configuration file name (sf_ for settings.yml, app_ for
app.yml, mod_ for module.yml)
– The parent keys (if defined), in lowercase
– The name of the key, in lowercase

Sample app.yml Configuration Accessing Configuration Settings in PHP in the
dev Environment
all:
.general:
echo sfConfig::get('app_tax'); // Remember
tax: 19.6
//that category headers are ignored
default_user:
=> '19.6'
name: John Doe
echo sfConfig::get('app_default_user_name');
mail:
=> 'John Doe'
echo sfConfig::get('app_mail_webmaster');
=> 'dummy@example.com'
dev:
echo sfConfig::get('app_mail_contact');
mail:
=> 'dummy@example.com'
webmaster: dummy@example.com
contact: dummy@example.com

Custom Application Settings and app.yml
Most of the settings related to the features of an application should be stored
in the app.yml file, located in the myproject/apps/frontend/config/ directory.
This file is environment-dependent and empty by default.
Put in every setting that you want to be easily changed,
and use the sfConfig class to access these settings from your code.

Sample app.yml to Define Credit Card Operators Accepted for a Given Site

all:
creditcards: To know if the fake credit cards are accepted in
the current environment, get the value of:
fake: off
visa: on sfConfig::get('app_creditcards_fake');
americanexpress: on

dev:
creditcards:
fake: on

Custom Application Settings and app.yml

When you should require an PHP array directly beneath the all key you need to use
a category header, otherwise symfony will make the values separately
available as shown above.
all:
.array:
creditcards:
fake: off
visa: on
americanexpress: on

[php]
print_r(sfConfig::get('app_creditcards'));

Array(
[fake] => false
[visa] => true
[americanexpress] => true
)

Tips for Getting More from Configuration Files

• Using Constants in YAML Configuration Files
• Using Scriptable Configuration
• Browsing Your Own YAML File

Using Constants in YAML Configuration Files

• Some configuration settings rely on the value of other settings. To
avoid setting the same value twice, symfony supports constants in
YAML files. On encountering a setting name (one that can be
accessed by sfConfig::get()) in capital letters enclosed in % signs,
the configuration handlers replace them with their current value
Using Constants in YAML Files, Example from autoload.yml

autoload:
symfony:
name: symfony
path: %SF_SYMFONY_LIB_DIR%
recursive: on
exclude: [vendor]

Using Scriptable Configuration

• It may happen that your configuration relies on external
parameters (such as a database or another configuration
file). To deal with these particular cases, the symfony
configuration files are parsed as PHP files before being
passed to the YAML parser. It means that you can put PHP
code in YAML file

YAML Files Can Contain PHP

all:
translation:
format: <?php echo (sfConfig::get('sf_i18n') == true ? 'xliff' : 'none').quot;nquot; ?>

Browsing Your Own YAML File
• Whenever you want to read a YAML file directly, you can use the
sfYaml class. It is a YAML parser that can turn a YAML file into a PHP
associative array
Using the sfYaml Class to Turn a YAML File into an Associative Array
$test = sfYaml::load('/path/to/test.yml');
print_r($test);

Array(
[house] => Array(
[family] => Array(
Sample test.yml File [name] => Doe
[parents] => Array(
[0] => John
house: [1] => Jane
)
family: [children] => Array(
name: Doe [0] => Paul
[1] => Mark
parents: [John, Jane] [2] => Simone
children: [Paul, Mark, Simone] )
)
address: [address] => Array(
number: 34 [number] => 34
[street] => Main Street
street: Main Street [city] => Nowheretown
city: Nowheretown [zipcode] => 12345
)
zipcode: 12345 )
)

Summary
• The symfony configuration system uses the YAML
language to be simple and readable. The ability to deal
with multiple environments and to set parameters
through a definition cascade offers versatility to the
developer. Some of the configuration can be accessed
from within the code via the sfConfig object, especially
the application settings stored in the app.yml file.

• Yes, symfony does have a lot of configuration files, but
this approach makes it more adaptable. Remember that
you don't need to bother with them unless your
application requires a high level of customization.

Reference
• The Definitive Guide to
symfony,Fabien Potencier, Apress

Configuring Symfony

Recommended

Recommended

More Related Content

Similar to Configuring Symfony

Similar to Configuring Symfony (20)

Recently uploaded

Recently uploaded (20)

Configuring Symfony