feature symfony#23665 Create an interface for TranslationWriter (Nyholm)

This PR was squashed before being merged into the 3.4 branch (closes symfony#23665).

Discussion
----------

Create an interface for TranslationWriter

| Q             | A
| ------------- | ---
| Branch?       | 3.4
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | ~~~no~~~ yes
| Tests pass?   | yes
| Fixed tickets |
| License       | MIT
| Doc PR        |

We should provide an interface for the TranslationWriter. This allows other libraries (php-translation) that depend on the Translation component provide different implementations.

Commits
-------

c25eafa Create an interface for TranslationWriter

Author: nicolas-grekas

UPGRADE-3.4.md

@@ -160,6 +160,13 @@ SecurityBundle
 
  * `FirewallContext::getListeners()` now returns `\Traversable|array`
 
+Translation
+-----------
+
+ * `Symfony\Component\Translation\Writer\TranslationWriter::writeTranslations` has been deprecated 
+   and will be removed in 4.0, use `Symfony\Component\Translation\Writer\TranslationWriter::write` 
+   instead. 
+
 TwigBridge
 ----------
 

UPGRADE-4.0.md

@@ -580,6 +580,9 @@ Translation
 -----------
 
  * Removed the backup feature from the file dumper classes.
+ 
+ * Removed `Symfony\Component\Translation\Writer\TranslationWriter::writeTranslations`, 
+   use `Symfony\Component\Translation\Writer\TranslationWriter::write` instead. 
 
 TwigBundle
 ----------

src/Symfony/Bundle/FrameworkBundle/Command/TranslationUpdateCommand.php

@@ -21,7 +21,7 @@
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Translation\Extractor\ExtractorInterface;
 use Symfony\Component\Translation\MessageCatalogue;
-use Symfony\Component\Translation\Writer\TranslationWriter;
+use Symfony\Component\Translation\Writer\TranslationWriterInterface;
 
 /**
  * A command that parses templates to extract translation messages and adds them
@@ -39,14 +39,14 @@ class TranslationUpdateCommand extends ContainerAwareCommand
     private $defaultLocale;
 
     /**
-     * @param TranslationWriter  $writer
-     * @param TranslationLoader  $loader
-     * @param ExtractorInterface $extractor
-     * @param string             $defaultLocale
+     * @param TranslationWriterInterface $writer
+     * @param TranslationLoader          $loader
+     * @param ExtractorInterface         $extractor
+     * @param string                     $defaultLocale
      */
     public function __construct($writer = null, TranslationLoader $loader = null, ExtractorInterface $extractor = null, $defaultLocale = null)
     {
-        if (!$writer instanceof TranslationWriter) {
+        if (!$writer instanceof TranslationWriterInterface) {
             @trigger_error(sprintf('Passing a command name as the first argument of "%s" is deprecated since version 3.4 and will be removed in 4.0. If the command was registered by convention, make it a service instead.', __METHOD__), E_USER_DEPRECATED);
 
             parent::__construct($writer);
@@ -276,7 +276,7 @@ protected function execute(InputInterface $input, OutputInterface $output)
                 $bundleTransPath = end($transPaths).'translations';
             }
 
-            $this->writer->writeTranslations($operation->getResult(), $input->getOption('output-format'), array('path' => $bundleTransPath, 'default_locale' => $this->defaultLocale));
+            $this->writer->write($operation->getResult(), $input->getOption('output-format'), array('path' => $bundleTransPath, 'default_locale' => $this->defaultLocale));
 
             if (true === $input->getOption('dump-messages')) {
                 $resultMessage .= ' and translation files were updated';

src/Symfony/Component/Translation/CHANGELOG.md

@@ -8,6 +8,8 @@ CHANGELOG
  * Added `TranslationExtractorPass`
  * Added `TranslatorPass`
  * Added <notes> section to the Xliff 2.0 dumper.
+ * Added `TranslationWriterInterface`
+ * Deprecated `TranslationWriter::writeTranslations` in favor of `TranslationWriter::write`
 
 3.2.0
 -----

src/Symfony/Component/Translation/Tests/Writer/TranslationWriterTest.php

@@ -18,6 +18,10 @@
 
 class TranslationWriterTest extends TestCase
 {
+    /**
+     * @group legacy
+     * @expectedDeprecation Method Symfony\Component\Translation\Writer\TranslationWriter::writeTranslations() is deprecated since version 3.4 and will be removed in 4.0. Use write() instead.
+     */
     public function testWriteTranslations()
     {
         $dumper = $this->getMockBuilder('Symfony\Component\Translation\Dumper\DumperInterface')->getMock();
@@ -30,6 +34,18 @@ public function testWriteTranslations()
         $writer->writeTranslations(new MessageCatalogue(array()), 'test');
     }
 
+    public function testWrite()
+    {
+        $dumper = $this->getMockBuilder('Symfony\Component\Translation\Dumper\DumperInterface')->getMock();
+        $dumper
+            ->expects($this->once())
+            ->method('dump');
+
+        $writer = new TranslationWriter();
+        $writer->addDumper('test', $dumper);
+        $writer->write(new MessageCatalogue(array()), 'test');
+    }
+
     public function testDisableBackup()
     {
         $nonBackupDumper = new NonBackupDumper();

src/Symfony/Component/Translation/Writer/TranslationWriter.php

@@ -21,7 +21,7 @@
  *
  * @author Michel Salib <michelsalib@hotmail.com>
  */
-class TranslationWriter
+class TranslationWriter implements TranslationWriterInterface
 {
     /**
      * Dumpers used for export.
@@ -66,13 +66,13 @@ public function getFormats()
     /**
      * Writes translation from the catalogue according to the selected format.
      *
-     * @param MessageCatalogue $catalogue The message catalogue to dump
+     * @param MessageCatalogue $catalogue The message catalogue to write
      * @param string           $format    The format to use to dump the messages
      * @param array            $options   Options that are passed to the dumper
      *
      * @throws InvalidArgumentException
      */
-    public function writeTranslations(MessageCatalogue $catalogue, $format, $options = array())
+    public function write(MessageCatalogue $catalogue, $format, $options = array())
     {
         if (!isset($this->dumpers[$format])) {
             throw new InvalidArgumentException(sprintf('There is no dumper associated with format "%s".', $format));
@@ -88,4 +88,21 @@ public function writeTranslations(MessageCatalogue $catalogue, $format, $options
         // save
         $dumper->dump($catalogue, $options);
     }
+
+    /**
+     * Writes translation from the catalogue according to the selected format.
+     *
+     * @param MessageCatalogue $catalogue The message catalogue to write
+     * @param string           $format    The format to use to dump the messages
+     * @param array            $options   Options that are passed to the dumper
+     *
+     * @throws InvalidArgumentException
+     *
+     * @deprecated since 3.4 will be removed in 4.0. Use write instead.
+     */
+    public function writeTranslations(MessageCatalogue $catalogue, $format, $options = array())
+    {
+        @trigger_error(sprintf('Method %s() is deprecated since version 3.4 and will be removed in 4.0. Use write() instead.', __METHOD__), E_USER_DEPRECATED);
+        $this->write($catalogue, $format, $options);
+    }
 }

src/Symfony/Component/Translation/Writer/TranslationWriterInterface.php

@@ -0,0 +1,34 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Translation\Writer;
+
+use Symfony\Component\Translation\Exception\InvalidArgumentException;
+use Symfony\Component\Translation\MessageCatalogue;
+
+/**
+ * TranslationWriter writes translation messages.
+ *
+ * @author Michel Salib <michelsalib@hotmail.com>
+ */
+interface TranslationWriterInterface
+{
+    /**
+     * Writes translation from the catalogue according to the selected format.
+     *
+     * @param MessageCatalogue $catalogue The message catalogue to write
+     * @param string           $format    The format to use to dump the messages
+     * @param array            $options   Options that are passed to the dumper
+     *
+     * @throws InvalidArgumentException
+     */
+    public function write(MessageCatalogue $catalogue, $format, $options = array());
+}