Add getRaw…() methods for forwards compatibility

phpstan.neon.dist

@@ -31,3 +31,5 @@ parameters:
         -
             message: '#ResizeCoordinates::isEqualTo\(\) expects .*, stdClass given#'
             path: %currentWorkingDirectory%/tests/ResizeCoordinatesTest.php
+        -
+            message: '#Access to an undefined property XMLReader::#'

src/Picture.php

@@ -45,6 +45,8 @@ public function __construct(array $img, array $sources)
     public function getImg(string $rootDir = null, string $prefix = ''): array
     {
         if (null === $rootDir) {
+            trigger_deprecation('contao/image', '1.2', 'Passing NULL as $rootDir is deprecated and will no longer work in version 2.0. Use the getRawImg() method instead.');
+
             if ('' !== $prefix) {
                 throw new InvalidArgumentException(sprintf('Prefix must no be specified if rootDir is null, given "%s"', $prefix));
             }
@@ -55,12 +57,22 @@ public function getImg(string $rootDir = null, string $prefix = ''): array
         return $this->buildUrls($this->img, $rootDir, $prefix);
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function getRawImg(): array
+    {
+        return $this->img;
+    }
+
     /**
      * {@inheritdoc}
      */
     public function getSources(string $rootDir = null, string $prefix = ''): array
     {
         if (null === $rootDir) {
+            trigger_deprecation('contao/image', '1.2', 'Passing NULL as $rootDir is deprecated and will no longer work in version 2.0. Use the getRawSources() method instead.');
+
             if ('' !== $prefix) {
                 throw new InvalidArgumentException(sprintf('Prefix must no be specified if rootDir is null, given "%s"', $prefix));
             }
@@ -76,6 +88,14 @@ function ($source) use ($rootDir, $prefix) {
         );
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function getRawSources(): array
+    {
+        return $this->sources;
+    }
+
     /**
      * Converts image objects in an attributes array to URLs.
      *

src/PictureInterface.php

@@ -12,15 +12,23 @@
 
 namespace Contao\Image;
 
+/**
+ * @method array getRawImg()
+ * @method array getRawSources()
+ */
 interface PictureInterface
 {
     /**
      * Returns the image tag attributes.
+     *
+     * @param string $rootDir passing NULL is deprecated
      */
     public function getImg(string $rootDir = null, string $prefix = ''): array;
 
     /**
      * Returns the source tags attributes.
+     *
+     * @param string $rootDir passing NULL is deprecated
      */
     public function getSources(string $rootDir = null, string $prefix = ''): array;
 }

tests/PictureTest.php

@@ -18,15 +18,18 @@
 use Contao\Image\Picture;
 use Imagine\Image\ImagineInterface;
 use PHPUnit\Framework\TestCase;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 use Symfony\Component\Filesystem\Filesystem;
 
 class PictureTest extends TestCase
 {
+    use ExpectDeprecationTrait;
+
     public function testGetImg(): void
     {
         $picture = $this->createPicture(null, '/path/to/a/filename with special&<>"\'chars.jpeg');
 
-        $this->assertInstanceOf(ImageInterface::class, $picture->getImg()['src']);
+        $this->assertInstanceOf(ImageInterface::class, $picture->getRawImg()['src']);
 
         $this->assertSame(
             'path/to/a/filename%20with%20special%26%3C%3E%22%27chars.jpeg',
@@ -53,7 +56,7 @@ public function testGetImg(): void
             $picture->getImg('/path/to', 'https://example.com/images/')['src']
         );
 
-        $this->assertInstanceOf(ImageInterface::class, $picture->getImg()['srcset'][0][0]);
+        $this->assertInstanceOf(ImageInterface::class, $picture->getRawImg()['srcset'][0][0]);
 
         $this->assertSame(
             'path/to/a/filename%20with%20special%26%3C%3E%22%27chars.jpeg 1x',
@@ -80,8 +83,22 @@ public function testGetImg(): void
             $picture->getImg('/path/to', 'https://example.com/images/')['srcset']
         );
 
-        $this->assertSame('custom attribute', $picture->getImg()['data-custom']);
+        $this->assertSame('custom attribute', $picture->getRawImg()['data-custom']);
         $this->assertSame('custom attribute', $picture->getImg('/')['data-custom']);
+    }
+
+    /**
+     * @group legacy
+     */
+    public function testDeprecatedGetImg(): void
+    {
+        $picture = $this->createPicture(null, '/path/to/image.jpg');
+
+        $this->expectDeprecation('Passing NULL as $rootDir is deprecated%s');
+
+        $this->assertInstanceOf(ImageInterface::class, $picture->getImg()['src']);
+        $this->assertInstanceOf(ImageInterface::class, $picture->getImg()['srcset'][0][0]);
+        $this->assertSame('custom attribute', $picture->getImg()['data-custom']);
 
         $this->expectException(InvalidArgumentException::class);
 
@@ -92,7 +109,7 @@ public function testGetSources(): void
     {
         $picture = $this->createPicture(null, '/path/to/a/filename with special&<>"\'chars.jpeg');
 
-        $this->assertInstanceOf(ImageInterface::class, $picture->getSources()[0]['srcset'][0][0]);
+        $this->assertInstanceOf(ImageInterface::class, $picture->getRawSources()[0]['srcset'][0][0]);
 
         $this->assertSame(
             'path/to/a/filename%20with%20special%26%3C%3E%22%27chars.jpeg 1x',
@@ -119,8 +136,21 @@ public function testGetSources(): void
             $picture->getSources('/path/to', 'https://example.com/images/')[0]['srcset']
         );
 
-        $this->assertSame('custom attribute', $picture->getSources()[0]['data-custom']);
+        $this->assertSame('custom attribute', $picture->getRawSources()[0]['data-custom']);
         $this->assertSame('custom attribute', $picture->getSources('/')[0]['data-custom']);
+    }
+
+    /**
+     * @group legacy
+     */
+    public function testDeprecatedGetSources(): void
+    {
+        $picture = $this->createPicture(null, '/path/to/image.jpg');
+
+        $this->expectDeprecation('Passing NULL as $rootDir is deprecated%s');
+
+        $this->assertInstanceOf(ImageInterface::class, $picture->getSources()[0]['srcset'][0][0]);
+        $this->assertSame('custom attribute', $picture->getSources()[0]['data-custom']);
 
         $this->expectException(InvalidArgumentException::class);