Merge branch '2.1'

Author: weaverryan

book/routing.rst

@@ -179,8 +179,10 @@ file:
 .. tip::
 
     Even though all routes are loaded from a single file, it's common practice
-    to include additional routing resources from inside the file. See the
-    :ref:`routing-include-external-resources` section for more information.
+    to include additional routing resources. To do so, just point out in the
+    main routing configuration file which external files should be included.
+    See the :ref:`routing-include-external-resources` section for more
+    information.
 
 Basic Route Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~

book/templating.rst

@@ -644,7 +644,7 @@ Asynchronous Content with hinclude.js
 .. versionadded:: 2.1
     hinclude.js support was added in Symfony 2.1
 
-Controllers can be embedded asyncronous using the hinclude.js_ javascript library.
+Controllers can be embedded asyncronously using the hinclude.js_ javascript library.
 As the embedded content comes from another page (or controller for that matter),
 Symfony2 uses the standard ``render`` helper to configure ``hinclude`` tags:
 

components/config/definition.rst

@@ -212,6 +212,168 @@ For all nodes:
 ``cannotBeOverwritten()``
     don’t let other configuration arrays overwrite an existing value for this node
 
+Appending sections
+------------------
+
+If you have a complex configuration to validate then the tree can grow to
+be large and you may want to split it up into sections. You can do this by
+making a section a separate node and then appending it into the main tree
+with ``append()``::
+
+    public function getConfigTreeBuilder()
+    {
+        $treeBuilder = new TreeBuilder();
+        $rootNode = $treeBuilder->root('database');
+
+        $rootNode
+            ->arrayNode('connection')
+                ->children()
+                    ->scalarNode('driver')
+                        ->isRequired()
+                        ->cannotBeEmpty()
+                    ->end()
+                    ->scalarNode('host')
+                        ->defaultValue('localhost')
+                    ->end()
+                    ->scalarNode('username')->end()
+                    ->scalarNode('password')->end()
+                    ->booleanNode('memory')
+                        ->defaultFalse()
+                    ->end()
+                ->end()
+                ->append($this->addParametersNode())
+            ->end()
+        ;
+
+        return $treeBuilder;
+    }
+
+    public function addParametersNode()
+    {
+        $builder = new TreeBuilder();
+        $node = $builder->root('parameters');
+
+        $node
+            ->isRequired()
+            ->requiresAtLeastOneElement()
+            ->useAttributeAsKey('name')
+            ->prototype('array')
+                ->children()
+                    ->scalarNode('name')->isRequired()->end()
+                    ->scalarNode('value')->isRequired()->end()
+                ->end()
+            ->end()
+        ;
+
+        return $node;
+    }
+
+This is also useful to help you avoid repeating yourself if you have sections
+of the config that are repeated in different places.
+
+Normalization
+-------------
+
+When the config files are processed they are first normalized, then merged
+and finally the tree is used to validate the resulting array. The normalization
+process is used to remove some of the differences that result from different
+configuration formats, mainly the differences between Yaml and XML.
+
+The separator used in keys is typically ``_`` in Yaml and ``-`` in XML. For
+example, ``auto_connect`` in Yaml and ``auto-connect``. The normalization would
+make both of these ``auto_connect``.
+
+Another difference between Yaml and XML is in the way arrays of values may
+be represented. In Yaml you may have:
+
+.. code-block:: yaml
+
+    twig:
+        extensions: ['twig.extension.foo', 'twig.extension.bar']
+
+and in XML:
+
+.. code-block:: xml
+
+    <twig:config>
+        <twig:extension>twig.extension.foo</twig:extension>
+        <twig:extension>twig.extension.bar</twig:extension>
+    </twig:config>
+
+This difference can be removed in normalization by pluralizing the key used
+in XML. You can specify that you want a key to be pluralized in this way with
+``fixXmlConfig()``::
+
+    $rootNode
+        ->fixXmlConfig('extension')
+        ->children()
+            ->arrayNode('extensions')
+                ->prototype('scalar')->end()
+            ->end()
+        ->end()
+    ;
+
+If it is an irregular pluralization you can specify the plural to use as
+a second argument::
+
+    $rootNode
+        ->fixXmlConfig('child', 'children')
+        ->children()
+            ->arrayNode('children')
+        ->end()
+    ;
+
+As well as fixing this, ``fixXmlConfig`` ensures that single xml elements
+are still turned into an array. So you may have:
+
+.. code-block:: xml
+
+    <connection>default</connection>
+    <connection>extra</connection>
+
+and sometimes only:
+
+.. code-block:: xml
+
+    <connection>default</connection>
+
+By default ``connection`` would be an array in the first case and a string
+in the second making it difficult to validate. You can ensure it is always
+an array with with ``fixXmlConfig``.
+
+You can further control the normalization process if you need to. For example,
+you may want to allow a string to be set and used as a particular key or several
+keys to be set explicitly. So that, if everything apart from id is optional in this
+config:
+
+.. code-block:: yaml
+
+    connection:
+        name: my_mysql_connection
+        host: localhost
+        driver: mysql
+        username: user
+        password: pass
+
+you can allow the following as well:
+
+.. code-block:: yaml
+
+    connection: my_mysql_connection
+
+By changing a string value into an associative array with ``name`` as the key::
+
+    $rootNode
+        ->arrayNode('connection')
+           ->beforeNormalization()
+               ->ifString()
+               ->then(function($v) { return array('name'=> $v); })
+           ->end()
+           ->scalarValue('name')->isRequired()
+           // ...
+        ->end()
+    ;
+
 Validation rules
 ----------------
 
@@ -278,3 +440,4 @@ Otherwise the result is a clean array of configuration values::
     $processor = new Processor();
     $configuration = new DatabaseConfiguration;
     $processedConfiguration = $processor->processConfiguration($configuration, $configs);
+

components/dependency_injection/compilation.rst

@@ -278,7 +278,7 @@ will then be called when the container is compiled::
 .. note::
 
     Compiler passes are registered differently is you are using the full
-    stack framework, see :doc:`cookbook/service_container/compiler_passes`
+    stack framework, see :doc:`/cookbook/service_container/compiler_passes`
     for more details.
 
 Controlling the Pass Ordering

components/dependency_injection/tags.rst

@@ -161,7 +161,7 @@ run when the container is compiled::
 .. note::
 
     Compiler passes are registered differently is you are using the full
-    stack framework, see :doc:`cookbook/service_container/compiler_passes`
+    stack framework, see :doc:`/cookbook/service_container/compiler_passes`
     for more details.
 
 Adding additional attributes on Tags

components/http_foundation/sessions.rst

@@ -200,7 +200,7 @@ the array::
     $tokens['c'] = $value;
     $session->set('tokens', $tokens);
 
-With structured namespacing, the the key can be translated to the array
+With structured namespacing, the key can be translated to the array
 structure like this using a namespace character (defaults to `/`)::
 
     $session->set('tokens/c', $value);

components/map.rst.inc

@@ -31,7 +31,7 @@
 
 * **DOM Crawler**
 
-* :doc:`/components/dom_crawler`
+  * :doc:`/components/dom_crawler`
 
 * :doc:`/components/event_dispatcher/index`
 

components/process.rst

@@ -28,7 +28,7 @@ a command in a sub-process::
     $process->setTimeout(3600);
     $process->run();
     if (!$process->isSuccessful()) {
-        throw new RuntimeException($process->getErrorOutput());
+        throw new \RuntimeException($process->getErrorOutput());
     }
 
     print $process->getOutput();

contributing/code/conventions.rst

@@ -74,5 +74,5 @@ must be used instead (where ``XXX`` is the name of the related thing):
 
     While "setXXX" and "replaceXXX" are very similar, there is one notable 
     difference: "setXXX" may replace, or add new elements to the relation. 
-    "replaceXXX" on the other hand is specifically forbidden to add new 
-    elements, but most throw an exception in these cases.
+    "replaceXXX", on the other hand, cannot add new elements. If an unrecognized
+    key as passed to "replaceXXX" it must throw an exception.

contributing/code/standards.rst

@@ -96,7 +96,7 @@ Naming Conventions
 * Use camelCase, not underscores, for variable, function and method
   names, arguments;
 
-* Use underscores for option, parameter names;
+* Use underscores for option names and parameter names;
 
 * Use namespaces for all classes;