feat(format)!: simplify format reader and writer interfaces (#21)

BREAKING CHANGE: change to interface arguments for ReaderInterface and WriterInterface

Author: ramsey

CHANGELOG.md

@@ -17,6 +17,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - The `Extractor\MessageExtractor` constructor now requires `Util\FormatHelper` as a fifth parameter
 - Use `ConfigInterface` instead of `Config` as the type-hint on `Format\ReaderInterface`
+- Remove `$localeResolved` argument from `Format\ReaderInterface`
+- Change type on `$options` argument in `Format\WriterInterface` from `MessageExtractorOptions` to a dedicated `WriterOptions` type
 
 ### Deprecated
 

src/Extractor/MessageExtractor.php

@@ -32,11 +32,14 @@
 use FormatPHP\Extractor\Parser\Descriptor\PhpParser;
 use FormatPHP\Extractor\Parser\DescriptorParserInterface;
 use FormatPHP\Extractor\Parser\ParserErrorCollection;
+use FormatPHP\Format\WriterInterface;
+use FormatPHP\Format\WriterOptions;
 use FormatPHP\Util\FileSystemHelper;
 use FormatPHP\Util\FormatHelper;
 use FormatPHP\Util\Globber;
 use LogicException;
 use Psr\Log\LoggerInterface;
+use Ramsey\Collection\Exception\CollectionMismatchException;
 
 use function class_exists;
 use function count;
@@ -47,6 +50,9 @@
 
 /**
  * Extracts message descriptors from application source code
+ *
+ * @psalm-import-type DescriptorParserCallable from DescriptorParserInterface
+ * @psalm-import-type WriterType from WriterInterface
  */
 class MessageExtractor
 {
@@ -82,6 +88,7 @@ public function __construct(
      * @throws InvalidArgumentException
      * @throws ImproperContextException
      * @throws LogicException
+     * @throws CollectionMismatchException
      */
     public function process(array $files): void
     {
@@ -129,6 +136,7 @@ public function getErrors(): ParserErrorCollection
      * @throws UnableToProcessFileException
      * @throws ImproperContextException
      * @throws LogicException
+     * @throws CollectionMismatchException
      */
     private function parse(DescriptorCollection $descriptors, string $filePath): DescriptorCollection
     {
@@ -163,15 +171,14 @@ private function getDescriptorParsers(): array
      */
     private function loadDescriptorParser(string $parserNameOrScript): DescriptorParserInterface
     {
-        switch (strtolower($parserNameOrScript)) {
-            case 'php':
-                return new PhpParser($this->file);
+        if (strtolower($parserNameOrScript) === 'php') {
+            return new PhpParser($this->file);
         }
 
         if (class_exists($parserNameOrScript) && is_a($parserNameOrScript, DescriptorParserInterface::class, true)) {
             $parser = new $parserNameOrScript();
         } else {
-            /** @var Closure(string,MessageExtractorOptions,ParserErrorCollection):DescriptorCollection | null $parser */
+            /** @var DescriptorParserCallable | null $parser */
             $parser = $this->file->loadClosureFromScript($parserNameOrScript);
         }
 
@@ -194,7 +201,9 @@ private function loadDescriptorParser(string $parserNameOrScript): DescriptorPar
     }
 
     /**
-     * @param callable(DescriptorCollection,MessageExtractorOptions):array<mixed> $formatter
+     * @see WriterInterface
+     *
+     * @param WriterType $formatter
      *
      * @throws UnableToWriteFileException
      * @throws InvalidArgumentException
@@ -203,7 +212,11 @@ private function write(callable $formatter, DescriptorCollection $descriptors):
     {
         $file = $this->options->outFile ?? 'php://output';
 
-        $messages = $formatter($descriptors, $this->options);
+        $writerOptions = new WriterOptions();
+        $writerOptions->includesSourceLocation = $this->options->extractSourceLocation;
+        $writerOptions->includesPragma = $this->options->pragma !== null;
+
+        $messages = $formatter($descriptors, $writerOptions);
         if (count($messages) === 0) {
             $messages = (object) $messages;
         }

src/Extractor/Parser/DescriptorParserInterface.php

@@ -28,6 +28,9 @@
 
 /**
  * Parses message descriptors from application source code files
+ *
+ * @psalm-type DescriptorParserCallable = callable(string,MessageExtractorOptions,ParserErrorCollection):DescriptorCollection
+ * @psalm-type DescriptorParserType = DescriptorParserInterface | DescriptorParserCallable
  */
 interface DescriptorParserInterface
 {

src/Format/Reader/FormatPHPReader.php

@@ -26,7 +26,6 @@
 use FormatPHP\Exception\InvalidMessageShapeException;
 use FormatPHP\Format\ReaderInterface;
 use FormatPHP\Format\Writer\FormatPHPWriter;
-use FormatPHP\Intl\LocaleInterface;
 use FormatPHP\Message;
 use FormatPHP\MessageCollection;
 
@@ -46,7 +45,7 @@ class FormatPHPReader implements ReaderInterface
     /**
      * @inheritdoc
      */
-    public function __invoke(ConfigInterface $config, array $data, LocaleInterface $localeResolved): MessageCollection
+    public function __invoke(ConfigInterface $config, array $data): MessageCollection
     {
         $messages = new MessageCollection();
 

src/Format/Reader/SimpleReader.php

@@ -26,7 +26,6 @@
 use FormatPHP\Exception\InvalidMessageShapeException;
 use FormatPHP\Format\ReaderInterface;
 use FormatPHP\Format\Writer\SimpleWriter;
-use FormatPHP\Intl\LocaleInterface;
 use FormatPHP\Message;
 use FormatPHP\MessageCollection;
 
@@ -46,7 +45,7 @@ class SimpleReader implements ReaderInterface
     /**
      * @inheritdoc
      */
-    public function __invoke(ConfigInterface $config, array $data, LocaleInterface $localeResolved): MessageCollection
+    public function __invoke(ConfigInterface $config, array $data): MessageCollection
     {
         $messages = new MessageCollection();
 

src/Format/Reader/SmartlingReader.php

@@ -26,7 +26,6 @@
 use FormatPHP\Exception\InvalidMessageShapeException;
 use FormatPHP\Format\ReaderInterface;
 use FormatPHP\Format\Writer\SmartlingWriter;
-use FormatPHP\Intl\LocaleInterface;
 use FormatPHP\Message;
 use FormatPHP\MessageCollection;
 
@@ -46,7 +45,7 @@ class SmartlingReader implements ReaderInterface
     /**
      * @inheritdoc
      */
-    public function __invoke(ConfigInterface $config, array $data, LocaleInterface $localeResolved): MessageCollection
+    public function __invoke(ConfigInterface $config, array $data): MessageCollection
     {
         $messages = new MessageCollection();
 

src/Format/ReaderInterface.php

@@ -24,24 +24,21 @@
 
 use FormatPHP\ConfigInterface;
 use FormatPHP\Exception\InvalidMessageShapeException;
-use FormatPHP\Intl\LocaleInterface;
 use FormatPHP\MessageCollection;
 
 /**
  * Returns a collection of messages parsed from JSON-decoded message data
+ *
+ * @psalm-type ReaderCallableType = callable(ConfigInterface,mixed[]):MessageCollection
+ * @psalm-type ReaderType = ReaderInterface | ReaderCallableType
  */
 interface ReaderInterface
 {
     /**
      * @param array<array-key, mixed> $data An arbitrary array of JSON-decoded
      *     data, loaded from a message file.
-     * @param LocaleInterface $localeResolved We utilize a "fallback" algorithm
-     *     to look up a suitable replacement locale (i.e., if we receive "en-US"
-     *     and have only a locale for "en," we will use "en" instead). This
-     *     parameter is the actual locale we used, which may be different from
-     *     the one provided on Config.
      *
      * @throws InvalidMessageShapeException
      */
-    public function __invoke(ConfigInterface $config, array $data, LocaleInterface $localeResolved): MessageCollection;
+    public function __invoke(ConfigInterface $config, array $data): MessageCollection;
 }

src/Format/Writer/FormatPHPWriter.php

@@ -24,9 +24,9 @@
 
 use FormatPHP\DescriptorCollection;
 use FormatPHP\ExtendedDescriptorInterface;
-use FormatPHP\Extractor\MessageExtractorOptions;
 use FormatPHP\Format\Reader\FormatPHPReader;
 use FormatPHP\Format\WriterInterface;
+use FormatPHP\Format\WriterOptions;
 
 use function array_merge;
 use function ksort;
@@ -64,7 +64,7 @@ class FormatPHPWriter implements WriterInterface
     /**
      * @inheritdoc
      */
-    public function __invoke(DescriptorCollection $collection, MessageExtractorOptions $options): array
+    public function __invoke(DescriptorCollection $collection, WriterOptions $options): array
     {
         $format = [];
 
@@ -76,7 +76,7 @@ public function __invoke(DescriptorCollection $collection, MessageExtractorOptio
                 $message['description'] = $item->getDescription();
             }
 
-            if ($options->extractSourceLocation === true && $item instanceof ExtendedDescriptorInterface) {
+            if ($options->includesSourceLocation && $item instanceof ExtendedDescriptorInterface) {
                 $message = array_merge($message, [
                     'end' => $item->getSourceEndOffset(),
                     'file' => $item->getSourceFile(),
@@ -85,7 +85,7 @@ public function __invoke(DescriptorCollection $collection, MessageExtractorOptio
                 ]);
             }
 
-            if ($options->pragma !== null && $item instanceof ExtendedDescriptorInterface) {
+            if ($options->includesPragma && $item instanceof ExtendedDescriptorInterface) {
                 $message = array_merge($message, [
                     'meta' => $item->getMetadata(),
                 ]);

src/Format/Writer/SimpleWriter.php

@@ -23,9 +23,9 @@
 namespace FormatPHP\Format\Writer;
 
 use FormatPHP\DescriptorCollection;
-use FormatPHP\Extractor\MessageExtractorOptions;
 use FormatPHP\Format\Reader\SimpleReader;
 use FormatPHP\Format\WriterInterface;
+use FormatPHP\Format\WriterOptions;
 
 /**
  * A simple formatter for FormatPHP, producing message key-value pairs
@@ -45,7 +45,7 @@ class SimpleWriter implements WriterInterface
     /**
      * @inheritdoc
      */
-    public function __invoke(DescriptorCollection $collection, MessageExtractorOptions $options): array
+    public function __invoke(DescriptorCollection $collection, WriterOptions $options): array
     {
         $simple = [];
         foreach ($collection as $item) {

src/Format/Writer/SmartlingWriter.php

@@ -23,9 +23,9 @@
 namespace FormatPHP\Format\Writer;
 
 use FormatPHP\DescriptorCollection;
-use FormatPHP\Extractor\MessageExtractorOptions;
 use FormatPHP\Format\Reader\SmartlingReader;
 use FormatPHP\Format\WriterInterface;
+use FormatPHP\Format\WriterOptions;
 
 /**
  * Smartling formatter for FormatPHP
@@ -61,7 +61,7 @@ class SmartlingWriter implements WriterInterface
     /**
      * @inheritdoc
      */
-    public function __invoke(DescriptorCollection $collection, MessageExtractorOptions $options): array
+    public function __invoke(DescriptorCollection $collection, WriterOptions $options): array
     {
         $format = [
             'smartling' => [