fix: accept any callable of the correct shape as a format reader (#29)

Author: ramsey

phpstan.neon.dist

@@ -9,3 +9,4 @@ parameters:
         - */tests/*/fixtures/*
     ignoreErrors:
         - '#Cannot call method getName\(\) on ReflectionType\|null#'
+        - '#Method FormatPHP\\Util\\FormatHelper::loadFormatter\(\) never returns callable\(array\): FormatPHP\\MessageCollection so it can be removed from the return type#'

src/MessageLoader.php

@@ -22,45 +22,60 @@
 
 namespace FormatPHP;
 
+use FormatPHP\Exception\ImproperContextException;
 use FormatPHP\Exception\InvalidArgumentException;
 use FormatPHP\Exception\InvalidMessageShapeException;
 use FormatPHP\Exception\LocaleNotFoundException;
 use FormatPHP\Exception\UnableToProcessFileException;
 use FormatPHP\Format\Reader\FormatPHPReader;
 use FormatPHP\Format\ReaderInterface;
 use FormatPHP\Util\FileSystemHelper;
+use FormatPHP\Util\FormatHelper;
 
 use function array_filter;
 use function array_unique;
 use function array_values;
 use function implode;
+use function is_callable;
 use function sprintf;
 
 use const DIRECTORY_SEPARATOR;
 
 /**
  * Loads messages for a given locale from the file system or cache
+ *
+ * @psalm-import-type ReaderType from ReaderInterface
  */
 class MessageLoader
 {
     private ConfigInterface $config;
     private FileSystemHelper $fileSystemHelper;
-    private ReaderInterface $formatReader;
+    private FormatHelper $formatHelper;
     private string $messagesDirectory;
 
     /**
+     * @var ReaderType
+     */
+    private $formatReader;
+
+    /**
+     * @param ReaderType | string | null $formatReader
+     *
      * @throws InvalidArgumentException
+     * @throws ImproperContextException
      */
     public function __construct(
         string $messagesDirectory,
         ConfigInterface $config,
-        ?ReaderInterface $formatReader = null,
-        ?FileSystemHelper $fileSystemHelper = null
+        $formatReader = null,
+        ?FileSystemHelper $fileSystemHelper = null,
+        ?FormatHelper $formatHelper = null
     ) {
         $this->config = $config;
-        $this->formatReader = $formatReader ?? new FormatPHPReader();
         $this->fileSystemHelper = $fileSystemHelper ?? new FileSystemHelper();
+        $this->formatHelper = $formatHelper ?? new FormatHelper($this->fileSystemHelper);
         $this->messagesDirectory = $this->fileSystemHelper->getRealPath($messagesDirectory);
+        $this->formatReader = $this->loadFormatReader($formatReader);
 
         if (!$this->fileSystemHelper->isDirectory($this->messagesDirectory)) {
             throw new InvalidArgumentException(sprintf(
@@ -131,4 +146,29 @@ private function getFallbackLocales(): array
         /** @var string[] */
         return array_values(array_unique(array_filter($fallbacks)));
     }
+
+    /**
+     * @param ReaderType | string | null $formatReader
+     *
+     * @return ReaderType
+     *
+     * @throws ImproperContextException
+     * @throws InvalidArgumentException
+     */
+    private function loadFormatReader($formatReader): callable
+    {
+        if ($formatReader === null) {
+            return new FormatPHPReader();
+        }
+
+        if ($formatReader instanceof ReaderInterface) {
+            return $formatReader;
+        }
+
+        if (is_callable($formatReader)) {
+            return $this->formatHelper->validateReaderCallable($formatReader);
+        }
+
+        return $this->formatHelper->getReader($formatReader);
+    }
 }

src/Util/FormatHelper.php

@@ -132,7 +132,7 @@ public function getWriter(?string $format): callable
     /**
      * @param class-string<ReaderInterface> | class-string<WriterInterface> $type
      *
-     * @return ReaderCallableType | WriterCallableType
+     * @return ReaderType | WriterType
      *
      * @throws ImproperContextException
      * @throws InvalidArgumentException
@@ -147,24 +147,30 @@ private function loadFormatter(string $format, string $type): callable
         $formatter = $this->fileSystemHelper->loadClosureFromScript($format);
 
         if ($type === ReaderInterface::class) {
-            $formatter = $this->validateReaderClosure($formatter);
+            $formatter = $this->validateReaderCallable($formatter);
         } else {
-            $formatter = $this->validateWriterClosure($formatter);
+            $formatter = $this->validateWriterCallable($formatter);
         }
 
         return $formatter;
     }
 
     /**
+     * @return ReaderCallableType
+     *
      * @throws InvalidArgumentException
      *
      * @psalm-suppress UndefinedMethod, PossiblyNullReference
      */
-    private function validateReaderClosure(?Closure $formatter): Closure
+    public function validateReaderCallable(?callable $formatter): callable
     {
         try {
             assert($formatter !== null);
 
+            if (!$formatter instanceof Closure) {
+                $formatter = Closure::fromCallable($formatter);
+            }
+
             $reflected = new ReflectionFunction($formatter);
 
             assert($reflected->getNumberOfParameters() === 1);
@@ -186,15 +192,21 @@ private function validateReaderClosure(?Closure $formatter): Closure
     }
 
     /**
+     * @return WriterCallableType
+     *
      * @throws InvalidArgumentException
      *
      * @psalm-suppress UndefinedMethod, PossiblyNullReference
      */
-    private function validateWriterClosure(?Closure $formatter): Closure
+    public function validateWriterCallable(?callable $formatter): callable
     {
         try {
             assert($formatter !== null);
 
+            if (!$formatter instanceof Closure) {
+                $formatter = Closure::fromCallable($formatter);
+            }
+
             $reflected = new ReflectionFunction($formatter);
 
             assert($reflected->getNumberOfParameters() === 2);

tests/CustomMessageLoaderReader.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace FormatPHP\Test;
+
+use FormatPHP\Format\Reader\FormatPHPReader;
+
+class CustomMessageLoaderReader extends FormatPHPReader
+{
+}

tests/MessageLoaderTest.php

@@ -10,11 +10,15 @@
 use FormatPHP\Format\Reader\FormatPHPReader;
 use FormatPHP\Format\ReaderInterface;
 use FormatPHP\Intl\Locale;
+use FormatPHP\MessageCollection;
 use FormatPHP\MessageInterface;
 use FormatPHP\MessageLoader;
 
 use function sprintf;
 
+/**
+ * @psalm-import-type ReaderType from ReaderInterface
+ */
 class MessageLoaderTest extends TestCase
 {
     public function testExceptionWhenDirectoryIsNotValid(): void
@@ -25,10 +29,13 @@ public function testExceptionWhenDirectoryIsNotValid(): void
             __FILE__,
         ));
 
+        /** @var ReaderInterface $reader */
+        $reader = $this->mockery(ReaderInterface::class);
+
         new MessageLoader(
             __FILE__,
             new Config(new Locale('en')),
-            $this->mockery(ReaderInterface::class),
+            $reader,
         );
     }
 
@@ -37,10 +44,13 @@ public function testExceptionWhenUnableToFindSuitableLocale(): void
         // Esperanto, Latin script, US region.
         $locale = new Locale('eo-Latn-US');
 
+        /** @var ReaderInterface $reader */
+        $reader = $this->mockery(ReaderInterface::class);
+
         $loader = new MessageLoader(
             __DIR__ . '/fixtures/locales',
             new Config($locale),
-            $this->mockery(ReaderInterface::class),
+            $reader,
         );
 
         $this->expectException(LocaleNotFoundException::class);
@@ -91,4 +101,47 @@ public function testLoadMessagesWithFallback(): void
             $collection['about.inspire']->getMessage(),
         );
     }
+
+    /**
+     * @param ReaderType $customReader
+     *
+     * @dataProvider provideCustomReader
+     */
+    public function testLoadMessagesWithCustomReader($customReader): void
+    {
+        $locale = new Locale('ar');
+
+        $loader = new MessageLoader(
+            __DIR__ . '/fixtures/locales',
+            new Config($locale),
+            $customReader,
+        );
+
+        $collection = $loader->loadMessages();
+
+        $this->assertCount(1, $collection);
+        $this->assertNotNull($collection['about.inspire']);
+        $this->assertInstanceOf(MessageInterface::class, $collection['about.inspire']);
+        $this->assertSame(
+            'في Skillshare ، نقوم بتمكين الأعضاء للحصول على الإلهام.',
+            $collection['about.inspire']->getMessage(),
+        );
+    }
+
+    /**
+     * @return mixed[]
+     */
+    public function provideCustomReader(): array
+    {
+        $customReader = new CustomMessageLoaderReader();
+
+        return [
+            ['customReader' => CustomMessageLoaderReader::class],
+            ['customReader' => $customReader],
+            ['customReader' => fn (array $data): MessageCollection => (new FormatPHPReader())($data)],
+            ['customReader' => [$customReader, '__invoke']],
+            ['customReader' => __DIR__ . '/fixtures/custom-reader.php'],
+            ['customReader' => null],
+        ];
+    }
 }

tests/Util/FormatHelperTest.php

@@ -150,7 +150,7 @@ public function testGetWriter(string $writer, string $expectedType): void
     }
 
     /**
-     * @return array<string, array{writer: string, expectedType: string}>
+     * @return mixed[]
      */
     public function validWriterProvider(): array
     {
@@ -235,4 +235,40 @@ public function invalidWriterProvider(): array
             ],
         ];
     }
+
+    /**
+     * @dataProvider validateWriterCallableProvider
+     */
+    public function testValidateWriterCallable(callable $writer): void
+    {
+        $helper = new FormatHelper(new FileSystemHelper());
+
+        $this->assertInstanceOf(Closure::class, $helper->validateWriterCallable($writer));
+    }
+
+    /**
+     * @return mixed[]
+     */
+    public function validateWriterCallableProvider(): array
+    {
+        $writerInstance = new ChromeWriter();
+
+        return [
+            'formatphp' => [
+                'writer' => new FormatPHPWriter(),
+            ],
+            'callable array' => [
+                'writer' => [$writerInstance, '__invoke'],
+            ],
+            'loaded closure' => [
+                'writer' => require __DIR__ . '/fixtures/writer-closure-01.php',
+            ],
+            'loaded anonymous class' => [
+                'writer' => require __DIR__ . '/fixtures/writer-closure-02.php',
+            ],
+            'closure' => [
+                'writer' => fn (DescriptorCollection $descriptors, WriterOptions $options): array => [],
+            ],
+        ];
+    }
 }

tests/fixtures/custom-reader.php

@@ -0,0 +1,8 @@
+<?php
+
+declare(strict_types=1);
+
+use FormatPHP\Format\Reader\FormatPHPReader;
+use FormatPHP\MessageCollection;
+
+return fn (array $data): MessageCollection => (new FormatPHPReader())($data);