* weaverryan/config_definition_changes:
[SecurityBundle] Allowing the main Configuration tree to allow "factories" without a validation exception.
[SecurityBundle] Removing an old configuration key in a test - caught by the Configuration validation.
[SecurityBundle] Adding the ignoreExtraFields option to the factories tree so that there aren't validation errors on all the other unknown fields.
[Config] Adding an ignoreExtraKeys options, which allows you to let options simply be ignore without throwing a validation exception.
[Config] Reverting some meaningless changes that are no longer needed to minimize the true diff of the changes. Increasing the test precision.
[Config] Reverting the preventExtraKeys option. This is a revert of functionality that would have allowed "unnamed" children to be added to an array node.
[Config] Moving the removal of the key attribute on ArrayNode onto the setKeyAttribute() method per Johannes.
[Config] Renaming the key attribute removal property for consistency per Johannes' recommendation. Also fixing a PHPDoc typo per Stof.
[SwiftmailerBundle] Removing unnecessary "enabled" key in a test.
[FrameworkBundle] Removing the "namespace" key when it's defined in its own weird location in XML. This prevents that key, which we move in this same location, from looking like an invalid option during validation.
[Config] Renaming NodeBuilder::nodeBuilder() to NodeBuilder::builder() due to the fact that PHP can get confused when you have a __construct() method *and* a method that has the same name as the class (looks like two constructors to PHP).
[Config] Making the option to remove a key attribute optional.
[Config] Renaming the NodeBuilder::addNodeBuilder() to simply NodeBuilder::nodeBuilder() to be consistent with the other names: node(), arrayNode().
[Config] Making changes per the recent movement of the Config builder into the Config component.
[DependencyInjection] Renaming allowUnnamedChildren to preventExtraKeys. Also moved the place where validation of extra configs occurs.
[DependencyInjection] Being sure to remove XML-remapped singular options and key attribute options after processing.
[DependencyInjection] Adding a NodeBuilder::addNodeBuilder() method that helps achieve a fluid interface when a pre-built NodeBuilder needs to be added.
[DependencyInjection] Initial implementation of an allowUnnamedChildren method on NodeBuilder. Also added an "extra field" exception.
The main tree doesn't actually process the factories (that's done in an earlier step), so it doesn't actually need their real value. It does, however, need to *not* throw an exception when they're present. An alternative to this approach would be to call ignoreExtraKeys() on the root node of the main tree, but this would allow extra keys to be passed in at the root level, which I thought was a less-desirable solution.
Added config fixtures in each format to demonstrate the possible styles of all of the extension options. These should all be covered by the updated tests. Made XSD slightly more restrictive, with regards to the "type" attribute on globals. This is coupled with validation in the configuration class.
I double-checked with Stof - this is obviously unnecessary and there was no meaning behind including it. This caused the test to fail with the new validation.
Note that this commit removes the built-in support for MongoDB user providers.
This code can be moved back in once there is a stable release for MongoDB, but
for now you have to set-up that user provider just like you would set-up any
custom user provider:
security:
providers:
document_provider:
id: my.mongo.provider
How to upgrade?
For XML configuration files:
* All extensions should now use the config tag (this is just a convention as
the YAML configurations files do not use it anymore):
* The previous change means that the doctrine and security bundles now are
wrapped under a main "config" tag:
<doctrine:config>
<doctrine:orm />
<doctrine:dbal />
</doctrine:config>
<security:config>
<security:acl />
...
</security:config>
For YAML configuration files:
* The main keys have been renamed as follows:
* assetic:config -> assetic
* app:config -> framework
* webprofiler:config -> web_profiler
* doctrine_odm.mongodb -> doctrine_mongo_db
* doctrine:orm -> doctrine: { orm: ... }
* doctrine:dbal -> doctrine: { dbal: ... }
* security:config -> security
* security:acl -> security: { acl: ... }
* twig.config -> twig
* zend.config -> zend
This allows for better conventions and better error messages if you
use the wrong configuration alias in a config file.
This is also the first step for a bigger refactoring of how the configuration
works (see next commits).
* Bundle::registerExtensions() method has been renamed to Bundle::build()
* The "main" DIC extension must be renamed to the new convention to be
automatically registered:
SensioBlogBundle -> DependencyInjection\SensioBlogExtension
* The main DIC extension alias must follow the convention:
sensio_blog for SensioBlogBundle
* If you have more than one extension for a bundle (which should really
never be the case), they must be registered manually by overriding the
build() method
* If you use YAML or PHP for your configuration, renamed the following
configuration entry points in your configs:
app -> framework
webprofiler -> web_profiler
doctrine_odm -> doctrine_mongo_db
* Added the --format parameter to the InitBundleCommand.php file
* Moved all the non-format-dependent files from Resources/skeleton/bundle to Resources/skeleton/bundle/generic
* Created Resources/skeleton/bundle/[php,yml,xml] subfolders containing the files config/routing.[xml,yml,php]
The custom error page is now disabled by default as this would throw an
exception if the /access_denied url does not match a route.
This commit also remove the old parameter for this url which is not used
anymore in the code.
Moved the default value to the Configuration class
* Remove redundant null/true equivalent array() values for array nodes
* Profiler matcher should not be deep merged; subsequent configs can simply overwrite its array
* Per lsmith's suggestion, change "isset(x) && x" to "!empty(x)"
* Templating engines node should be required, which is necessary to ensure requiresAtLeastOneElement() applies to its prototype children
In routing files, import statements allow an optional "type" option to hint the resources' type (e.g. for ambiguous file extensions). This adds the same type option to the FrameworkExtension config, which defines the main routing resource.
This reverts commit f53080860a.
Revert "[Router] config fixes"
This reverts commit 51beecc6f2.
Revert "moved duplicated files to a new Config component"
This reverts commit a8ec9b27f0.
Methods within FormExtension later type-hint this parameter as an array, but it's convenient to allow a single string to be passed from Twig if we ensure it's wrapped in an array.
Updated load data fixtures command in DoctrineMongoDBBundle to be identical to the one in DoctrineBundle
Created custom loader, that passes $container to all ContainerAware DataFixtures
This fixes some BC problems introduced in f9138d313b. Some top-level can now be simply enabled by providing true/null in PHP/YAML. Additionally, the Configuration\Builder allows options to be unset by providing "false" (helpful for overriding activation in a previous config file). All options supporting these behaviors can be found in the Configuration.php file (look for canBeUnset() and treatNull/TrueLike()).
Major changes:
* Removed "enabled" option for profiler config. Profiler is now enabled if its config is true, null or a map.
* Restore original config structure for validation namespaces. In PHP/YAML, namespaces are defined under annotations as an alternative to false (disabled) and true/null (enabled). For XML, annotation remains a boolean attribute for validation and a one or more optional namespace tags may appear within <app:validation />. During config normalization, namespace tags under validation will be moved to annotations to conform to the PHP/YAML structure (this occurs transparently to the user).
* Restore behavior for router/templating config sections being optional (as shown in changes to session/validation test fixtures). If either top-level section is unset in the configuration, neither feature will be enabled and the user will no longer receive exceptions due to missing a resource option (router) or engines (templating). Resource/engines will still be properly required if the respective feature is enabled.
* Remove unused router type option from XML config XSD. Type is only relevant for import statements, so this option is likely useless.
Additional small changes:
* Added isset()'s, since config options may be unset
* Wrap registerXxxConfiguration() calls in isset() checks
* Load translation.xml in configLoad(), since it's always required
* Default cache_warmer value (!kernel.debug) is determined via Configuration class
Things to be fixed:
* Configuration\Builder doesn't seem to respect isRequired() and requiresAtLeastOneElement() (or I haven't set it properly); this should replace the need for FrameworkExtension to throw exceptions for bad router/templating configs
* The config nodes for session options don't have the "pdo." prefix, as dots are not allowed in node names. To preserve BC for now, the "pdo." prefix is still allowed (and mandated by XSD) in configuration files. In the future, we may just want to do away with the "pdo." prefix.
* Translator has an "enabled" option. If there's no use case for setting "fallback" independently (when "enabled" is false), perhaps "enabled" should be removed entirely and translator should function like profiler currently does.
* Profiler matcher merging might need to be adjusted so multiple configs simply overwrite matcher instead of merging its array keys.
The merging is done in three steps:
1. Normalization:
=================
All passed config arrays will be transformed into the same structure
regardless of what format they come from.
2. Merging:
===========
This is the step when the actual merging is performed. Starting at the root
the configs will be passed along the tree until a node has no children, or
the merging of sub-paths of the current node has been specifically disabled.
Left-Side Right-Side Merge Result
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-nothing- array Right-Side will be taken.
scalar scalar Right-Side will be taken.
array false Right-Side will be taken if ->canBeUnset()
was called on the array node.
false array Right-Side will be taken.
array array Each value in the array will be passed to
the specific child node, or the prototype
node (whatever is present).
3. Finalization:
================
The normalized, and merged config will be passed through the config tree to
perform final validation on the submitted values, and set default values
where this has been requested.
You can influence this process in various ways, here is a list with some examples.
All of these methods must be called on the node on which they should be applied.
* isRequired(): Node must be present in at least one config file.
* requiresAtLeastOneElement(): PrototypeNode must have at least one element.
* treatNullLike($value): Replaces null with $value during normalization.
* treatTrueLike($value): Same as above just for true
* treatFalseLike($value): Same as above just for false
* defaultValue($value): Sets a default value for this node (only for scalars)
* addDefaultsIfNotSet(): Whether to add default values of an array which has not
been defined in any configuration file.
* disallowNewKeysInSubsequentConfigs(): All keys for this array must be defined
in one configuration file, subsequent
configurations may only overwrite these.
* fixXmlConfig($key, $plural = null): Transforms XML config into same structure
as YAML, and PHP configurations.
* useAttributeAsKey($name): Defines which XML attribute to use as array key.
* cannotBeOverwritten(): Declares a certain sub-path as non-overwritable. All
configuration for this path must be defined in the same
configuration file.
* cannotBeEmpty(): If value is set, it must be non-empty.
* canBeUnset(): If array values should be unset if false is specified.
Architecture:
=============
The configuration consists basically out of two different sets of classes.
1. Builder classes: These classes provide the fluent interface and
are used to construct the config tree.
2. Node classes: These classes contain the actual logic for normalization,
merging, and finalizing configurations.
After you have added all the metadata to your builders, the call to
->buildTree() will convert this metadata to actual node classes. Most of the
time, you will not have to interact with the config nodes directly, but will
delegate this to the Processor class which will call the respective methods
on the config node classes.
Previously, the Definition class was used both for type inference and factory construction (if factoryService was absent). This is fine for cases where classes create instances of themselves (e.g. getInstance() or create()), but leads to ambiguity when we have a separate factory class.
Restructured config format to make processing more straightforward. Important changes that might break existing configs:
* Added "enabled" option for translator (improves multi-format compat)
* Removed hash variation of validation annotations option (only boolean)
* Moved namespace option directly under validation (improves multi-format compat)
The new merge process depends on an internal array of all supported options and their default values, which is used for both validating the config schema and inferring how to merge options (as an added benefit, it helps make the extension self-documenting). Exceptions will now be thrown for merge errors resulting from unrecognized options or invalid types. Since incoming configurations are all merged atop the defaults, many isset() checks were removed. As a rule of thumb, we probably only want to ignore null values when an option would be used to set a parameter.
Also:
* Added missing attributes to symfony-1.0.xsd
* profiler: added only-exceptions attribute
* session: fix types and add pdo attributes
* Create FrameworkExtension tests with PHP/XML/YAML fixtures
* Use "%" syntax instead of calling getParameter() within FrameworkExtension
* Normalize config keys and arrays with helper methods for PHP/XML/YAML compatibility
Earlier changes:
* Remove nonexistent "DependencyInjection/Resources/" path from XmlFileLoaders
* Remove hasDefinition() checks, as register methods should only execute once
* Remove first-run logic from registerTranslatorConfiguration(), as it is only run once
* Removed apparently obsolete clearTags() calls on definitions for non-enabled features
With the form factory there was no reasonable way to implement instantiation of custom form classes. So the implementation was changed to let the classes instantiate themselves. A FormContext instance with default settings has to be passed to the creation method. This context is by default configured in the DI container.
$context = $this->get('form.context');
// or
$context = FormContext::buildDefault();
$form = MyFormClass::create($context, 'author');
If you want to circumvent this process, you can also create a form manually. Remember that the services stored in the default context won't be available then unless you pass them explicitely.
$form = new MyFormClass('author');
The Request constructor no longer uses values from PHP's super globals. If you want a Request populated with these values you must use the new static method Request::fromGlobals().
Your front controllers (i.e. web/app.php, web/app_dev.php ...) will need to be updated:
// old
$kernel->handle(new Request())->send();
// new
$kernel->handle(Request::fromGlobals())->send();
A class in Symfony2 can be loaded by four different mechanisms:
* bootstrap.php: This file contains classes that are always required and
needed very early in the request handling;
* classes.php: This file contains classes that are always required and
managed by extensions via addClassesToCompile();
* MapFileClassLoader: This autoloader uses a map of class/file to load
classes (classes are managed by extensions via addClassesToAutoloadMap(),
and should contain often used classes);
* UniversalAutolaoder: This autoloader loads all other classes (it's the
slowest one).
The three notification methods do not return the Event instance anymore.
notify() does not return anything
notifyUntil() returns the returned value of the event that has processed the event
filter() returns the filtered value
Upgrading your listeners:
Listeners for notify() and filter() events: nothing to change
Listeners for notifyUntil() events:
Before:
$event->setReturnValue('foo');
return true;
After:
$event->setProcessed();
return 'foo';
If you notify events, the processing also need to be changed:
For filter() notifications: the filtered value is now available as
the returned value of the filter() method.
For notifyUntil() notifications:
Before:
$event = $dispatcher->notifyUntil($event);
if ($event->isProcessed()) {
$ret = $event->getReturnValue();
// do something with $ret
}
After:
$ret = $dispatcher->notifyUntil($event);
if ($event->isProcessed()) {
// do something with $ret
}
Cache warmer will come in the next commits.
To warm up the cache on a production server, you can use
the cache:warmup command:
./app/console_prod cache:warmup
* The register() method on all listeners has been removed
* Instead, the information is now put directly in the DIC tag
For instance, a listener on core.request had this method:
public function register(EventDispatcher $dispatcher, $priority = 0)
{
$dispatcher->connect('core.response', array($this, 'filter'), $priority);
}
And this tag in the DIC configuration:
<tag name="kernel.listener" />
Now, it only has the following configuration:
<tag name="kernel.listener" event="core.response" method="filter" priority="0" />
The event and method attributes are now mandatory.
You must now explicitly register the templating engine you want to use:
<app:templating>
<app:engine id="twig" />
</app:templating>
app.templating:
engines: ['twig']
Symfony2 comes with two such engines: 'twig', and 'php'.
