Merge branch '2.4' into 2.5

* 2.4: (30 commits)
  [#4166] Fixing small typo
  caution on `null` values in Expression constraint
  Fixed all the errors found by Ryan
  Removed two highlight formats which are "experimental" and not used by end users
  Reworded the explanation about the limitation of enablin PHP templates
  Improved the explanation thanks to @stof comments
  More and more fixes and improvements
  Added another bunch of fixes suggested by reviewers
  Added lots of fixes suggested by reviewers
  Added a note about not using relative internal links in the doc
  Switched another relative link into an absolute reference
  lways use absolute links instead of relative for internal doc links
  Added missing link
  Revamped the documentation about "Contributing Docs"
  do not reference services in parameters
  Fix reference label
  Add label book-security-roles
  Add formatting, links, and clarity
  Added a note about the side effects of enabling both PHP and Twig
  Caution that roles should start with ROLE_
  ...

book/security.rst

@@ -1782,6 +1782,8 @@ the default for the firewall as a whole).
 For more information about user provider and firewall configuration, see
 the :doc:`/reference/configuration/security`.
 
+.. _book-security-roles:
+
 Roles
 -----
 

components/dependency_injection/parameters.rst

@@ -336,76 +336,3 @@ To disable this behavior, use the ``string`` type:
 
     This is not available for YAML and PHP, because they already have built-in
     support for the PHP keywords.
-
-Syntax for Referencing Services
--------------------------------
-
-You can of course also reference services, which looks a bit different in
-each format. You can configure the behavior if the referenced service does
-not exist. By default, an exception is thrown when a non-existent service
-is referenced.
-
-YAML
-~~~~
-
-Start the string with  ``@`` or ``@?`` to reference a service in YAML.
-
-* ``@mailer`` references the ``mailer`` service. If the service does not
-  exist, an exception will be thrown;
-* ``@?mailer`` references the ``mailer`` service. If the service does not
-  exist, it will be ignored;
-
-.. code-block:: yaml
-
-    parameters:
-        # if 'my_mailer' service isn't defined, an exception will be raised
-        foo: @my_mailer
-
-        # if 'my_logger' service isn't defined, 'bar' will be null
-        bar: @?my_logger
-
-.. tip::
-
-    Use ``@@`` to escape the ``@`` symbol in YAML. ``@@mailer`` will be
-    converted into the string ``"@mailer"`` instead of referencing the
-    ``mailer`` service.
-
-XML
-~~~
-
-In XML, use the ``service`` type. The behavior if the service does not exist
-can be specified using the ``on-invalid`` argument. By default, an exception
-is thrown. Valid values for ``on-invalid`` are ``null`` (uses ``null`` in place
-of the missing service) or ``ignored`` (very similar, except if used on a
-method call, the method call is removed).
-
-.. code-block:: xml
-
-    <parameters>
-        <!-- if 'my_mailer' service isn't defined, an exception will be raised -->
-        <parameter key="foo" type="service" id="my_mailer" />
-
-        <!-- if 'my_logger' service isn't defined, 'bar' will be null -->
-        <parameter key="bar" type="service" id="my_logger" on-invalid="null" />
-    </parameters>
-
-PHP
-~~~
-
-In PHP, you can use the
-:class:`Symfony\\Component\\DependencyInjection\\Reference` class to reference
-a service. The invalid behavior is configured using the second constructor
-argument and constants from
-:class:`Symfony\\Component\\DependencyInjection\\ContainerInterface`.
-
-.. code-block:: php
-
-    use Symfony\Component\DependencyInjection\Reference;
-
-    // if 'my_mailer' service isn't defined, an exception will be raised
-    $container->setParameter('foo', new Reference('my_mailer'));
-
-    // if 'my_logger' service isn't defined, 'bar' will be null
-    $container->setParameter('bar', new Reference('my_logger',
-        ContainerInterface::NULL_ON_INVALID_REFERENCE
-    ));

components/map.rst.inc

@@ -141,6 +141,7 @@
 
   * :doc:`/components/translation/introduction`
   * :doc:`/components/translation/usage`
+  * :doc:`/components/translation/custom_formats`
 
 * :doc:`/components/yaml/index`
 

components/translation/custom_formats.rst

@@ -0,0 +1,114 @@
+.. index::
+    single: Translation; Adding Custom Format Support
+
+Adding Custom Format Support
+============================
+
+Sometimes, you need to deal with custom formats for translation files. The
+Translation component is flexible enough to support this. Just create a
+loader (to load translations) and, optionally, a dumper (to dump translations).
+
+Imagine that you have a custom format where translation messages are defined
+using one line for each translation and parentheses to wrap the key and the
+message. A translation file would look like this:
+
+.. code-block:: text
+
+    (welcome)(accueil)
+    (goodbye)(au revoir)
+    (hello)(bonjour)
+
+Creating a Custom Loader
+------------------------
+
+To define a custom loader that is able to read these kinds of files, you must create a
+new class that implements the
+:class:`Symfony\\Component\\Translation\\Loader\\LoaderInterface`. The
+:method:`Symfony\\Component\\Translation\\Loader\\LoaderInterface::load`
+method will get a filename and parse it into an array. Then, it will
+create the catalog that will be returned::
+
+    use Symfony\Component\Translation\MessageCatalogue;
+    use Symfony\Component\Translation\Loader\LoaderInterface;
+
+    class MyFormatLoader implements LoaderInterface
+    {
+        public function load($resource, $locale, $domain = 'messages')
+        {
+            $messages = array();
+            $lines = file($resource);
+
+            foreach ($lines as $line) {
+                if (preg_match('/\(([^\)]+)\)\(([^\)]+)\)/', $line, $matches)) {
+                    $messages[$matches[1]] = $matches[2];
+                }
+            }
+
+            $catalogue = new MessageCatalogue($locale);
+            $catalogue->add($messages, $domain);
+
+            return $catalogue;
+        }
+
+    }
+
+Once created, it can be used as any other loader::
+
+    use Symfony\Component\Translation\Translator;
+
+    $translator = new Translator('fr_FR');
+    $translator->addLoader('my_format', new MyFormatLoader());
+
+    $translator->addResource('my_format', __DIR__.'/translations/messages.txt', 'fr_FR');
+
+    echo $translator->trans('welcome');
+
+It will print *"accueil"*.
+
+Creating a Custom Dumper
+------------------------
+
+It is also possible to create a custom dumper for your format, which is
+useful when using the extraction commands. To do so, a new class
+implementing the
+:class:`Symfony\\Component\\Translation\\Dumper\\DumperInterface`
+must be created. To write the dump contents into a file, extending the
+:class:`Symfony\\Component\\Translation\\Dumper\\FileDumper` class
+will save a few lines::
+
+    use Symfony\Component\Translation\MessageCatalogue;
+    use Symfony\Component\Translation\Dumper\FileDumper;
+
+    class MyFormatDumper extends FileDumper
+    {
+        protected function format(MessageCatalogue $messages, $domain = 'messages')
+        {
+            $output = '';
+
+            foreach ($messages->all($domain) as $source => $target) {
+                $output .= sprintf("(%s)(%s)\n", $source, $target);
+            }
+
+            return $output;
+        }
+
+        protected function getExtension()
+        {
+            return 'txt';
+        }
+    }
+
+The :method:`Symfony\\Component\\Translation\\Dumper\\FileDumper::format`
+method creates the output string, that will be used by the
+:method:`Symfony\\Component\\Translation\\Dumper\\FileDumper::dump` method
+of the FileDumper class to create the file. The dumper can be used like any other
+built-in dumper. In the following example, the translation messages defined in the
+YAML file are dumped into a text file with the custom format::
+
+    use Symfony\Component\Translation\Loader\YamlFileLoader;
+
+    $loader = new YamlFileLoader();
+    $catalogue = $loader->load(__DIR__ . '/translations/messages.fr_FR.yml' , 'fr_FR');
+
+    $dumper = new MyFormatDumper();
+    $dumper->dump($catalogue, array('path' => __DIR__.'/dumps'));

components/translation/index.rst

@@ -6,3 +6,4 @@ Translation
 
     introduction
     usage
+    custom_formats

components/translation/introduction.rst

@@ -95,6 +95,9 @@ Loader too. The default loaders are:
 
 All file loaders require the :doc:`Config component </components/config/index>`.
 
+You can also :doc:`create your own Loader </components/translation/custom_formats>`,
+in case the format is not already supported by one of the default loaders.
+
 At first, you should add one or more loaders to the ``Translator``::
 
     // ...