FrameworkBundle Configuration (“framework”)
FrameworkBundle Configuration (“framework”)¶
The FrameworkBundle contains most of the “base” framework functionality
and can be configured under the framework
key in your application
configuration. When using XML, you must use the
http://symfony.com/schema/dic/symfony
namespace.
This includes settings related to sessions, translation, forms, validation, routing and more.
Tip
The XSD schema is available at
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd
.
Configuration¶
- secret
- http_method_override
- trusted_proxies
- ide
- test
- default_locale
- trusted_hosts
- csrf_protection
- enabled
- field_name (deprecated as of 2.4)
secret¶
type: string
required
This is a string that should be unique to your application and it’s commonly used to add more entropy to security related operations. Its value should be a series of characters, numbers and symbols chosen randomly and the recommended length is around 32 characters.
In practice, Symfony uses this value for generating the CSRF tokens, for encrypting the cookies used in the remember me functionality and for creating signed URIs when using ESI (Edge Side Includes).
This option becomes the service container parameter named kernel.secret
,
which you can use whenever the application needs an immutable random string
to add more entropy.
As with any other security-related parameter, it is a good practice to change this value from time to time. However, keep in mind that changing this value will invalidate all signed URIs and Remember Me cookies. That’s why, after changing this value, you should regenerate the application cache and log out all the application users.
http_method_override¶
New in version 2.3: The http_method_override
option was introduced in Symfony 2.3.
type: boolean
default: true
This determines whether the _method
request parameter is used as the
intended HTTP method on POST requests. If enabled, the
Request::enableHttpMethodParameterOverride
method gets called automatically. It becomes the service container parameter
named kernel.http_method_override
.
See also
For more information, see How to Use HTTP Methods beyond GET and POST in Routes.
Caution
If you’re using the AppCache Reverse Proxy
with this option, the kernel will ignore the _method
parameter,
which could lead to errors.
To fix this, invoke the enableHttpMethodParameterOverride()
method
before creating the Request
object:
// web/app.php
// ...
$kernel = new AppCache($kernel);
Request::enableHttpMethodParameterOverride(); // <-- add this line
$request = Request::createFromGlobals();
// ...
trusted_proxies¶
type: array
Configures the IP addresses that should be trusted as proxies. For more details, see How to Configure Symfony to Work behind a Load Balancer or a Reverse Proxy.
New in version 2.3: CIDR notation support was introduced in Symfony 2.3, so you can whitelist
whole subnets (e.g. 10.0.0.0/8
, fc00::/7
).
- YAML
1 2 3
# app/config/config.yml framework: trusted_proxies: [192.0.0.1, 10.0.0.0/8]
- XML
1 2 3 4 5 6 7 8 9 10
<!-- app/config/config.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <framework:config trusted-proxies="192.0.0.1, 10.0.0.0/8" /> </container>
- PHP
1 2 3 4
// app/config/config.php $container->loadFromExtension('framework', array( 'trusted_proxies' => array('192.0.0.1', '10.0.0.0/8'), ));
ide¶
type: string
default: null
If you’re using an IDE like TextMate or Mac Vim, then Symfony can turn all of the file paths in an exception message into a link, which will open that file in your IDE.
Symfony contains preconfigured urls for some popular IDEs, you can set them using the following keys:
textmate
macvim
emacs
sublime
New in version 2.3.14: The emacs
and sublime
editors were introduced in Symfony 2.3.14.
You can also specify a custom url string. If you do this, all percentage
signs (%
) must be doubled to escape that character. For example, if
you use PHPstorm on the Mac OS platform, you will do something like:
- YAML
1 2 3
# app/config/config.yml framework: ide: "phpstorm://open?file=%%f&line=%%l"
- XML
1 2 3 4 5 6 7 8 9 10
<!-- app/config/config.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <framework:config ide="phpstorm://open?file=%%f&line=%%l" /> </container>
- PHP
1 2 3 4
// app/config/config.php $container->loadFromExtension('framework', array( 'ide' => 'phpstorm://open?file=%%f&line=%%l', ));
Tip
If you’re on a Windows PC, you can install the PhpStormProtocol to be able to use this.
Of course, since every developer uses a different IDE, it’s better to set
this on a system level. This can be done by setting the xdebug.file_link_format
in the php.ini
configuration to the url string. If this configuration
value is set, then the ide
option will be ignored.
test¶
type: boolean
If this configuration setting is present (and not false
), then the services
related to testing your application (e.g. test.client
) are loaded. This
setting should be present in your test
environment (usually via
app/config/config_test.yml
).
See also
For more information, see Testing.
default_locale¶
type: string
default: en
The default locale is used if no _locale
routing parameter has been
set. It is available with the
Request::getDefaultLocale
method.
See also
You can read more information about the default locale in Setting a Default Locale.
trusted_hosts¶
type: array
| string
default: array()
A lot of different attacks have been discovered relying on inconsistencies
in handling the Host
header by various software (web servers, reverse
proxies, web frameworks, etc.). Basically, everytime the framework is
generating an absolute URL (when sending an email to reset a password for
instance), the host might have been manipulated by an attacker.
See also
You can read “HTTP Host header attacks” for more information about these kinds of attacks.
The Symfony Request::getHost()
method might be vulnerable to some of these attacks because it depends on
the configuration of your web server. One simple solution to avoid these
attacks is to whitelist the hosts that your Symfony application can respond
to. That’s the purpose of this trusted_hosts
option. If the incoming
request’s hostname doesn’t match one in this list, the application won’t
respond and the user will receive a 500 response.
- YAML
1 2 3
# app/config/config.yml framework: trusted_hosts: ['acme.com', 'acme.org']
- XML
1 2 3 4 5 6 7 8 9 10 11 12 13 14
<!-- app/config/config.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <framework:config> <trusted-host>acme.com</trusted-host> <trusted-host>acme.org</trusted-host> <!-- ... --> </framework> </container>
- PHP
1 2 3 4
// app/config/config.php $container->loadFromExtension('framework', array( 'trusted_hosts' => array('acme.com', 'acme.org'), ));
Hosts can also be configured using regular expressions (e.g. .*\.?acme.com$
),
which make it easier to respond to any subdomain.
In addition, you can also set the trusted hosts in the front controller
using the Request::setTrustedHosts()
method:
// web/app.php
Request::setTrustedHosts(array('.*\.?acme.com$', '.*\.?acme.org$'));
The default value for this option is an empty array, meaning that the application can respond to any given host.
See also
Read more about this in the Security Advisory Blog post.
form¶
enabled¶
type: boolean
default: false
Whether to enable the form services or not in the service container. If
you don’t use forms, setting this to false
may increase your application’s
performance because less services will be loaded into the container.
This option will automatically be set to true
when one of the child
settings is configured.
Note
This will automatically enable the validation.
See also
For more details, see Forms.
csrf_protection¶
See also
For more information about CSRF protection in forms, see CSRF Protection.
enabled¶
type: boolean
default: true
if form support is enabled, false
otherwise
This option can be used to disable CSRF protection on all forms. But you can also disable CSRF protection on individual forms.
If you’re using forms, but want to avoid starting your session (e.g. using
forms in an API-only website), csrf_protection
will need to be set to
false
.
field_name¶
Caution
The framework.csrf_protection.field_name
setting is deprecated as
of Symfony 2.4, use framework.form.csrf_protection.field_name
instead.
type: string
default: "_token"
The name of the hidden field used to render the CSRF token.
esi¶
See also
You can read more about Edge Side Includes (ESI) in Using Edge Side Includes.
enabled¶
type: boolean
default: false
Whether to enable the edge side includes support in the framework.
You can also set esi
to true
to enable it:
- YAML
1 2 3
# app/config/config.yml framework: esi: true
- XML
1 2 3 4 5 6 7 8 9 10 11 12
<!-- app/config/config.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <framework:config> <esi /> </framework:config> </container>
- PHP
1 2 3 4
// app/config/config.php $container->loadFromExtension('framework', array( 'esi' => true, ));
fragments¶
See also
Learn more about fragments in the HTTP Cache article.
enabled¶
type: boolean
default: false
Whether to enable the fragment listener or not. The fragment listener is used to render ESI fragments independently of the rest of the page.
This setting is automatically set to true
when one of the child settings
is configured.
path¶
type: string
default: '/_fragment'
The path prefix for fragments. The fragment listener will only be executed when the request starts with this path.
profiler¶
enabled¶
New in version 2.2: The enabled
option was introduced in Symfony 2.2. Prior to Symfony
2.2, the profiler could only be disabled by omitting the framework.profiler
configuration entirely.
type: boolean
default: false
The profiler can be enabled by setting this option to true
. When you
are using the Symfony Standard Edition, the profiler is enabled in the dev
and test
environments.
Note
The profiler works independently from the Web Developer Toolbar, see the WebProfilerBundle configuration on how to disable/enable the toolbar.
collect¶
New in version 2.3: The collect
option was introduced in Symfony 2.3. Previously, when
profiler.enabled
was false
, the profiler was actually enabled,
but the collectors were disabled. Now, the profiler and the collectors
can be controlled independently.
type: boolean
default: true
This option configures the way the profiler behaves when it is enabled.
If set to true
, the profiler collects data for all requests (unless
you configure otherwise, like a custom matcher). If you want to only
collect information on-demand, you can set the collect
flag to false
and activate the data collectors manually:
$profiler->enable();
only_exceptions¶
type: boolean
default: false
When this is set to true
, the profiler will only be enabled when an
exception is thrown during the handling of the request.
only_master_requests¶
type: boolean
default: false
When this is set to true
, the profiler will only be enabled on the master
requests (and not on the subrequests).
dsn¶
type: string
default: 'file:%kernel.cache_dir%/profiler'
The DSN where to store the profiling information.
See also
See Switching the Profiler Storage for more information about the profiler storage.
lifetime¶
type: integer
default: 86400
The lifetime of the profiling storage in seconds. The data will be deleted when the lifetime is expired.
matcher¶
Matcher options are configured to dynamically enable the profiler. For instance, based on the ip or path.
See also
See How to Use Matchers to Enable the Profiler Conditionally for more information about using matchers to enable/disable the profiler.
router¶
resource¶
type: string
required
The path the main routing resource (e.g. a YAML file) that contains the routes and imports the router should load.
type¶
type: string
The type of the resource to hint the loaders about the format. This isn’t
needed when you use the default routers with the expected file extensions
(.xml
, .yml
/ .yaml
, .php
).
http_port¶
type: integer
default: 80
The port for normal http requests (this is used when matching the scheme).
https_port¶
type: integer
default: 443
The port for https requests (this is used when matching the scheme).
strict_requirements¶
type: mixed
default: true
Determines the routing generator behaviour. When generating a route that has specific requirements, the generator can behave differently in case the used parameters do not meet these requirements.
The value can be one of:
true
- Throw an exception when the requirements are not met;
false
- Disable exceptions when the requirements are not met and return
null
instead; null
- Disable checking the requirements (thus, match the route even when the requirements don’t match).
true
is recommended in the development environment, while false
or null
might be preferred in production.
session¶
storage_id¶
type: string
default: 'session.storage.native'
The service id used for session storage. The session.storage
service
alias will be set to this service id. This class has to implement
Symfony\Component\HttpFoundation\Session\Storage\SessionStorageInterface
.
handler_id¶
type: string
default: 'session.handler.native_file'
The service id used for session storage. The session.handler
service
alias will be set to this service id.
You can also set it to null
, to default to the handler of your PHP
installation.
See also
You can see an example of the usage of this in How to Use PdoSessionHandler to Store Sessions in the Database.
name¶
type: string
default: null
This specifies the name of the session cookie. By default it will use the
cookie name which is defined in the php.ini
with the session.name
directive.
cookie_lifetime¶
type: integer
default: null
This determines the lifetime of the session - in seconds. The default value
- null
- means that the sesssion.cookie_lifetime
value from php.ini
will be used. Setting this value to 0
means the cookie is valid for
the length of the browser session.
cookie_path¶
type: string
default: /
This determines the path to set in the session cookie. By default it will
use /
.
cookie_domain¶
type: string
default: ''
This determines the domain to set in the session cookie. By default it’s blank, meaning the host name of the server which generated the cookie according to the cookie specification.
cookie_secure¶
type: boolean
default: false
This determines whether cookies should only be sent over secure connections.
cookie_httponly¶
type: boolean
default: false
This determines whether cookies should only be accessible through the HTTP protocol. This means that the cookie won’t be accessible by scripting languages, such as JavaScript. This setting can effectively help to reduce identity theft through XSS attacks.
gc_probability¶
type: integer
default: 1
This defines the probability that the garbage collector (GC) process is
started on every session initialization. The probability is calculated by
using gc_probability
/ gc_divisor
, e.g. 1/100 means there is a 1%
chance that the GC process will start on each request.
gc_maxlifetime¶
type: integer
default: 1440
This determines the number of seconds after which data will be seen as “garbage” and potentially cleaned up. Garbage collection may occur during session start and depends on gc_divisor and gc_probability.
save_path¶
type: string
default: %kernel.cache.dir%/sessions
This determines the argument to be passed to the save handler. If you choose the default file handler, this is the path where the session files are created. For more information, see Configuring the Directory where Session Files are Saved.
You can also set this value to the save_path
of your php.ini
by
setting the value to null
:
- YAML
1 2 3 4
# app/config/config.yml framework: session: save_path: ~
- XML
1 2 3 4 5 6 7 8 9 10 11 12
<!-- app/config/config.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <framework:config> <framework:session save-path="null" /> </framework:config> </container>
- PHP
1 2 3 4 5 6
// app/config/config.php $container->loadFromExtension('framework', array( 'session' => array( 'save_path' => null, ), ));
templating¶
assets_version¶
type: string
This option is used to bust the cache on assets by globally adding a query
parameter to all rendered asset paths (e.g. /images/logo.png?v2
). This
applies only to assets rendered via the Twig asset
function (or PHP
equivalent) as well as assets rendered with Assetic.
For example, suppose you have the following:
- Twig
1
<img src="{{ asset('images/logo.png') }}" alt="Symfony!" />
- PHP
1
<img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>" alt="Symfony!" />
By default, this will render a path to your image such as /images/logo.png
.
Now, activate the assets_version
option:
- YAML
1 2 3 4
# app/config/config.yml framework: # ... templating: { engines: ['twig'], assets_version: v2 }
- XML
1 2 3 4 5 6 7 8 9 10 11 12 13
<!-- app/config/config.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <framework:templating assets-version="v2"> <!-- ... --> <framework:engine>twig</framework:engine> </framework:templating> </container>
- PHP
1 2 3 4 5 6 7 8
// app/config/config.php $container->loadFromExtension('framework', array( // ... 'templating' => array( 'engines' => array('twig'), 'assets_version' => 'v2', ), ));
Now, the same asset will be rendered as /images/logo.png?v2
If you use
this feature, you must manually increment the assets_version
value
before each deployment so that the query parameters change.
It’s also possible to set the version value on an asset-by-asset basis (instead
of using the global version - e.g. v2
- set here). See
Versioning by Asset for details.
You can also control how the query string works via the assets_version_format option.
Tip
As with all settings, you can use a parameter as value for the
assets_version
. This makes it easier to increment the cache on each
deployment.
assets_version_format¶
type: string
default: %%s?%%s
This specifies a sprintf
pattern that will be used with the
assets_version option to construct an asset’s path. By default, the pattern
adds the asset’s version as a query string. For example, if
assets_version_format
is set to %%s?version=%%s
and assets_version
is set to 5
, the asset’s path would be /images/logo.png?version=5
.
Note
All percentage signs (%
) in the format string must be doubled to
escape the character. Without escaping, values might inadvertently be
interpreted as Service Parameters.
Tip
Some CDN’s do not support cache-busting via query strings, so injecting
the version into the actual file path is necessary. Thankfully,
assets_version_format
is not limited to producing versioned query
strings.
The pattern receives the asset’s original path and version as its first
and second parameters, respectively. Since the asset’s path is one
parameter, you cannot modify it in-place (e.g. /images/logo-v5.png
);
however, you can prefix the asset’s path using a pattern of
version-%%2$s/%%1$s
, which would result in the path
version-5/images/logo.png
.
URL rewrite rules could then be used to disregard the version prefix before serving the asset. Alternatively, you could copy assets to the appropriate version path as part of your deployment process and forgot any URL rewriting. The latter option is useful if you would like older asset versions to remain accessible at their original URL.
hinclude_default_template¶
type: string
default: null
Sets the content shown during the loading of the fragment or when JavaScript is disabled. This can be either a template name or the content itself.
See also
See Asynchronous Content with hinclude.js for more information about hinclude.
form¶
resources¶
type: string[]
default: ['FrameworkBundle:Form']
A list of all resources for form theming in PHP. This setting is not required if you’re using the Twig format for your templates, in that case refer to the form book chapter.
Assume you have custom global form themes in
src/WebsiteBundle/Resources/views/Form
, you can configure this like:
- YAML
1 2 3 4 5 6
# app/config/config.yml framework: templating: form: resources: - 'WebsiteBundle:Form'
- XML
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
<!-- app/config/config.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <framework:config> <framework:templating> <framework:form> <framework:resource>WebsiteBundle:Form</framework:resource> </framework:form> </framework:templating> </framework:config> </container>
- PHP
1 2 3 4 5 6 7 8 9 10
// app/config/config.php $container->loadFromExtension('framework', array( 'templating' => array( 'form' => array( 'resources' => array( 'WebsiteBundle:Form' ), ), ), ));
Note
The default form templates from FrameworkBundle:Form
will always
be included in the form resources.
See also
See Global Form Theming for more information.
assets_base_urls¶
default: { http: [], ssl: [] }
This option allows you to define base URLs to be used for assets referenced
from http
and ssl
(https
) pages. If multiple base URLs are
provided, Symfony will select one from the collection each time it generates
an asset’s path:
- YAML
1 2 3 4 5 6 7 8 9 10
# app/config/config.yml framework: # ... templating: assets_base_urls: http: - "http://cdn.example.com/" # you can also pass just a string: # assets_base_urls: # http: "//cdn.example.com/"
- XML
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
<!-- app/config/config.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:framework="http://symfony.com/schema/dic/symfony"> <framework:config> <!-- ... --> <framework:templating> <framework:assets-base-url> <framework:http>http://cdn.example.com/</framework:http> </framework:assets-base-url> </framework:templating> </framework:config> </container>
- PHP
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
// app/config/config.php $container->loadFromExtension('framework', array( // ... 'templating' => array( 'assets_base_urls' => array( 'http' => array( 'http://cdn.example.com/', ), ), // you can also pass just a string: // 'assets_base_urls' => array( // 'http' => '//cdn.example.com/', // ), ), ));
For your convenience, you can pass a string or array of strings to
assets_base_urls
directly. This will automatically be organized into
the http
and ssl
base urls (https://
and protocol-relative
URLs will be added to both collections and http://
only to the http
collection):
- YAML
1 2 3 4 5 6 7 8
# app/config/config.yml framework: # ... templating: assets_base_urls: - "//cdn.example.com/" # you can also pass just a string: # assets_base_urls: "//cdn.example.com/"
- XML
1 2 3 4 5 6 7 8 9 10 11 12 13
<!-- app/config/config.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:framework="http://symfony.com/schema/dic/symfony"> <framework:config> <!-- ... --> <framework:templating> <framework:assets-base-url>//cdn.example.com/</framework:assets-base-url> </framework:templating> </framework:config> </container>
- PHP
1 2 3 4 5 6 7 8 9 10 11
// app/config/config.php $container->loadFromExtension('framework', array( // ... 'templating' => array( 'assets_base_urls' => array( '//cdn.example.com/', ), // you can also pass just a string: // 'assets_base_urls' => '//cdn.example.com/', ), ));
cache¶
type: string
The path to the cache directory for templates. When this is not set, caching is disabled.
Note
When using Twig templating, the caching is already handled by the TwigBundle and doesn’t need to be enabled for the FrameworkBundle.
engines¶
type: string[]
/ string
required
The Templating Engine to use. This can either be a string (when only one engine is configured) or an array of engines.
At least one engine is required.
loaders¶
type: string[]
An array (or a string when configuring just one loader) of service ids for
templating loaders. Templating loaders are used to find and load templates
from a resource (e.g. a filesystem or database). Templating loaders must
implement Symfony\Component\Templating\Loader\LoaderInterface
.
packages¶
You can group assets into packages, to specify different base URLs for them:
- YAML
1 2 3 4 5 6 7
# app/config/config.yml framework: # ... templating: packages: avatars: base_urls: 'http://static_cdn.example.com/avatars'
- XML
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
<!-- app/config/config.xml --> <?xml version="1.0" encoding="UTF-8" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:framework="http://symfony.com/schema/dic/symfony" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> <framework:config> <framework:templating> <framework:package name="avatars" base-url="http://static_cdn.example.com/avatars"> </framework:templating> </framework:config> </container>
- PHP
1 2 3 4 5 6 7 8 9 10 11
// app/config/config.php $container->loadFromExtension('framework', array( // ... 'templating' => array( 'packages' => array( 'avatars' => array( 'base_urls' => 'http://static_cdn.example.com/avatars', ), ), ), ));
Now you can use the avatars
package in your templates:
- Twig
1
<img src="{{ asset('...', 'avatars') }}">
- PHP
1
<img src="<?php echo $view['assets']->getUrl('...', 'avatars') ?>">
Each package can configure the following options:
translator¶
enabled¶
type: boolean
default: false
Whether or not to enable the translator
service in the service container.
fallbacks¶
type: string|array
default: array('en')
New in version 2.3.25: The fallbacks
option was introduced in Symfony 2.3.25. Prior
to Symfony 2.3.25, it was called fallback
and only allowed one fallback
language defined as a string. Please note that you can still use the
old fallback
option if you want define only one fallback.
This option is used when the translation key for the current locale wasn’t found.
See also
For more details, see Translations.
logging¶
New in version 2.6: The logging
option was introduced in Symfony 2.6.
default: true
when the debug mode is enabled, false
otherwise.
When true
, a log entry is made whenever the translator cannot find a translation
for a given key. The logs are made to the translation
channel and at the
debug
for level for keys where there is a translation in the fallback
locale and the warning
level if there is no translation to use at all.
property_accessor¶
magic_call¶
type: boolean
default: false
When enabled, the property_accessor
service uses PHP’s
magic __call() method when
its getValue()
method is called.
throw_exception_on_invalid_index¶
type: boolean
default: false
When enabled, the property_accessor
service throws an exception when you
try to access an invalid index of an array.
validation¶
enabled¶
type: boolean
default: true
if form support is enabled,
false
otherwise
Whether or not to enable validation support.
This option will automatically be set to true
when one of the child
settings is configured.
cache¶
type: string
The service that is used to persist class metadata in a cache. The service
has to implement the Symfony\Component\Validator\Mapping\Cache\CacheInterface
.
enable_annotations¶
type: boolean
default: false
If this option is enabled, validation constraints can be defined using annotations.
translation_domain¶
type: string
default: validators
The translation domain that is used when translating validation constraint error messages.
strict_email¶
New in version 2.5: The strict_email
option was introduced in Symfony 2.5.
type: Boolean
default: false
If this option is enabled, the egulias/email-validator library will be used by the Email constraint validator. Otherwise, the validator uses a simple regular expression to validate email addresses.
api¶
New in version 2.5: The api
option was introduced in Symfony 2.5.
type: string
Starting with Symfony 2.5, the Validator component introduced a new validation
API. The api
option is used to switch between the different implementations:
2.4
- Use the vaidation API that is compatible with older Symfony versions.
2.5
- Use the validation API introduced in Symfony 2.5.
2.5-bc
orauto
- If you omit a value or set the
api
option to2.5-bc
orauto
, Symfony will use an API implementation that is compatible with both the legacy implementation and the2.5
implementation. You have to use PHP 5.3.9 or higher to be able to use this implementation.
To capture these logs in the prod
environment, configure a
channel handler in config_prod.yml
for
the translation
channel and set its level
to debug
.
annotations¶
cache¶
type: string
default: 'file'
This option can be one of the following values:
- file
- Use the filesystem to cache annotations
- none
- Disable the caching of annotations
- a service id
- A service id referencing a Doctrine Cache implementation
file_cache_dir¶
type: string
default: '%kernel.cache_dir%/annotations'
The directory to store cache files for annotations, in case
annotations.cache
is set to 'file'
.
debug¶
type: boolean
default: %kernel.debug%
Whether to enable debug mode for caching. If enabled, the cache will automatically update when the original file is changed (both with code and annotation changes). For performance reasons, it is recommended to disable debug mode in production, which will happen automatically if you use the default value.
serializer¶
enabled¶
type: boolean
default: false
Whether to enable the serializer
service or not in the service container.
For more details, see How to Use the Serializer.
Full Default Configuration¶
- YAML
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 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
framework: secret: ~ http_method_override: true trusted_proxies: [] ide: ~ test: ~ default_locale: en csrf_protection: enabled: false field_name: _token # Deprecated since 2.4, to be removed in 3.0. Use form.csrf_protection.field_name instead # form configuration form: enabled: false csrf_protection: enabled: true field_name: ~ # esi configuration esi: enabled: false # fragments configuration fragments: enabled: false path: /_fragment # profiler configuration profiler: enabled: false collect: true only_exceptions: false only_master_requests: false dsn: file:%kernel.cache_dir%/profiler username: password: lifetime: 86400 matcher: ip: ~ # use the urldecoded format path: ~ # Example: ^/path to resource/ service: ~ # router configuration router: resource: ~ # Required type: ~ http_port: 80 https_port: 443 # * set to true to throw an exception when a parameter does not # match the requirements # * set to false to disable exceptions when a parameter does not # match the requirements (and return null instead) # * set to null to disable parameter checks against requirements # # 'true' is the preferred configuration in development mode, while # 'false' or 'null' might be preferred in production strict_requirements: true # session configuration session: storage_id: session.storage.native handler_id: session.handler.native_file name: ~ cookie_lifetime: ~ cookie_path: ~ cookie_domain: ~ cookie_secure: ~ cookie_httponly: ~ gc_divisor: ~ gc_probability: ~ gc_maxlifetime: ~ save_path: "%kernel.cache_dir%/sessions" # serializer configuration serializer: enabled: false # templating configuration templating: assets_version: ~ assets_version_format: "%%s?%%s" hinclude_default_template: ~ form: resources: # Default: - FrameworkBundle:Form assets_base_urls: http: [] ssl: [] cache: ~ engines: # Required # Example: - twig loaders: [] packages: # Prototype name: version: ~ version_format: "%%s?%%s" base_urls: http: [] ssl: [] # translator configuration translator: enabled: false fallbacks: [en] logging: "%kernel.debug%" # validation configuration validation: enabled: false cache: ~ enable_annotations: false translation_domain: validators # annotation configuration annotations: cache: file file_cache_dir: "%kernel.cache_dir%/annotations" debug: "%kernel.debug%"
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.