From d55513660ee02163d892ea53bea005984614d392 Mon Sep 17 00:00:00 2001
From: Dmitriy Derepko <xepozz@list.ru>
Date: Sun, 27 Nov 2022 19:23:20 +0300
Subject: [PATCH] Add write method to category source (#95)

* Add write method to category source

* Apply fixes from StyleCI

* [ci-review] Apply changes from Rector action.

* Add changelog

* Add BC layer

* Add test

* Apply fixes from StyleCI

* Resort arguments and add a test

* Fix psalm

* Apply review suggestion

* Check exception code

* Update src/CategorySource.php

Co-authored-by: Rustam Mamadaminov <rmamdaminov@gmail.com>

Co-authored-by: StyleCI Bot <bot@styleci.io>
Co-authored-by: rector-bot <rector@yiiframework.com>
Co-authored-by: Rustam Mamadaminov <rmamdaminov@gmail.com>
Co-authored-by: Alexander Makarov <sam@rmcreative.ru>
---
 CHANGELOG.md                              |  1 +
 config/common.php                         |  1 +
 src/CategorySource.php                    | 37 ++++++++++++++++++++++-
 src/UnwritableCategorySourceException.php | 20 ++++++++++++
 tests/CategoryTest.php                    | 29 ++++++++++++++++++
 5 files changed, 87 insertions(+), 1 deletion(-)
 create mode 100644 src/UnwritableCategorySourceException.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 93f397a..3fb4a66 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## 2.2.0 under development
 
 - New #94: Add `getMessages()` method to `CategorySource` (@xepozz)
+- New #95: Add `write()` method to `CategorySource` (@xepozz)
 
 ## 2.1.1 November 23, 2022
 
diff --git a/config/common.php b/config/common.php
index 7dabe98..67afddd 100644
--- a/config/common.php
+++ b/config/common.php
@@ -19,6 +19,7 @@
     //        return new \Yiisoft\Translator\CategorySource(
     //            $params['yiisoft/translator']['defaultCategory'],
     //            $messageSource,
+    //            $messageSource,
     //            $messageFormatter,
     //        );
     //    },
diff --git a/src/CategorySource.php b/src/CategorySource.php
index 6806d66..341e33f 100644
--- a/src/CategorySource.php
+++ b/src/CategorySource.php
@@ -17,15 +17,18 @@ final class CategorySource
      * @param string $name Category name.
      * @param MessageReaderInterface $reader Message reader to get messages from for this category.
      * @param MessageFormatterInterface|null $formatter Message formatter to format messages with for this category.
+     * @param MessageWriterInterface|null $writer Message writer to write messages for this category.
      */
     public function __construct(
         string $name,
         private MessageReaderInterface $reader,
-        private ?MessageFormatterInterface $formatter = null
+        private ?MessageFormatterInterface $formatter = null,
+        private ?MessageWriterInterface $writer = null,
     ) {
         if (!preg_match('/^[a-z0-9_-]+$/i', $name)) {
             throw new RuntimeException('Category name is invalid. Only letters and numbers are allowed.');
         }
+
         $this->name = $name;
     }
 
@@ -80,6 +83,38 @@ public function getMessages(string $locale): array
         return $this->reader->getMessages($this->name, $locale);
     }
 
+    /**
+     * Writes a set of messages for a specified category and locale.
+     *
+     * @psalm-param array<string, array<string, string>> $messages
+     *
+     * @param string $locale Locale to write messages for.
+     * @param array $messages A set of messages to write. The format is the following:
+     * ```php
+     * [
+     *   'key1' => [
+     *     'message' => 'translation1',
+     *     // Extra metadata that writer may use:
+     *     'comment' => 'Translate carefully!',
+     *   ],
+     *   'key2' => [
+     *     'message' => 'translation2',
+     *     // Extra metadata that writer may use:
+     *     'comment' => 'Translate carefully!',
+     *   ],
+     * ]
+     * ```
+     *
+     * @throws UnwritableCategorySourceException When $write is not configured, or it's impossible to write the messages into the source.
+     */
+    public function write(string $locale, array $messages): void
+    {
+        if ($this->writer === null) {
+            throw new UnwritableCategorySourceException($this->name);
+        }
+        $this->writer->write($this->name, $locale, $messages);
+    }
+
     /**
      * Format the message given parameters and locale.
      *
diff --git a/src/UnwritableCategorySourceException.php b/src/UnwritableCategorySourceException.php
new file mode 100644
index 0000000..3ac8924
--- /dev/null
+++ b/src/UnwritableCategorySourceException.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Translator;
+
+use Exception;
+use Throwable;
+
+final class UnwritableCategorySourceException extends Exception
+{
+    public function __construct(string $categoryName, int $code = 0, ?Throwable $previous = null)
+    {
+        parent::__construct(
+            sprintf('The category source "%s" does not support writing.', $categoryName),
+            $code,
+            $previous
+        );
+    }
+}
diff --git a/tests/CategoryTest.php b/tests/CategoryTest.php
index 8b8d86d..eacd35c 100644
--- a/tests/CategoryTest.php
+++ b/tests/CategoryTest.php
@@ -9,8 +9,10 @@
 use Yiisoft\Translator\CategorySource;
 use Yiisoft\Translator\MessageFormatterInterface;
 use Yiisoft\Translator\MessageReaderInterface;
+use Yiisoft\Translator\MessageWriterInterface;
 use Yiisoft\Translator\NullMessageFormatter;
 use Yiisoft\Translator\SimpleMessageFormatter;
+use Yiisoft\Translator\UnwritableCategorySourceException;
 
 final class CategoryTest extends TestCase
 {
@@ -34,6 +36,33 @@ public function testNameException(): void
         );
     }
 
+    public function testWriterAbsence(): void
+    {
+        $category = new CategorySource(
+            'app',
+            $this->createMessageReader(),
+            $this->createMessageFormatter(),
+        );
+
+        $this->expectException(UnwritableCategorySourceException::class);
+        $this->expectExceptionCode(0);
+        $this->expectExceptionMessage('The category source "app" does not support writing.');
+        $category->write('en', []);
+    }
+
+    public function testWriterAvailable(): void
+    {
+        $category = new CategorySource(
+            'app',
+            $this->createMessageReader(),
+            $this->createMessageFormatter(),
+            $this->createMock(MessageWriterInterface::class)
+        );
+
+        $category->write('en', []);
+        $this->expectNotToPerformAssertions();
+    }
+
     public function dataWithoutFormatter(): array
     {
         return [