[FEATURE] Introduce image metadata

lib/Imagine/Image/AbstractImage.php

@@ -15,6 +15,11 @@
 
 abstract class AbstractImage implements ImageInterface
 {
+    /**
+     * @var Metadata\MetadataInterface
+     */
+    protected $metadata;
+
     /**
      * {@inheritdoc}
      */
@@ -73,4 +78,26 @@ public function thumbnail(BoxInterface $size, $mode = ImageInterface::THUMBNAIL_
 
         return $thumbnail;
     }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function metadata()
+    {
+        if ($this->metadata === null) {
+            $this->metadata = new Metadata\ExifMetadata($this);
+        }
+        return $this->metadata;
+    }
+
+    /**
+     * Assures the metadata instance will be cloned, too
+     */
+    function __clone()
+    {
+        if ($this->metadata !== null) {
+            $this->metadata = clone $this->metadata;
+        }
+    }
+
 }

lib/Imagine/Image/ImageInterface.php

@@ -166,4 +166,11 @@ public function usePalette(PaletteInterface $palette);
      * @throws RuntimeException
      */
     public function profile(ProfileInterface $profile);
+
+    /**
+     * Returns the Image's meta data
+     *
+     * @return Metadata\MetadataInterface
+     */
+    public function metadata();
 }

lib/Imagine/Image/Metadata/ExifMetadata.php

@@ -0,0 +1,64 @@
+<?php
+namespace Imagine\Image\Metadata;
+
+/*
+ * This file is part of the Imagine package.
+ *
+ * (c) Bulat Shakirzyanov <mallluhuct@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Imagine\Image\ImageInterface;
+
+/**
+ * Metadata driven by Exif information
+ */
+class ExifMetadata implements MetadataInterface
+{
+    /**
+     * @var ImageInterface
+     */
+    protected $image;
+
+    /**
+     * @var array
+     */
+    protected $exifData;
+
+    /**
+     * {@inheritdoc}
+     */
+    public function __construct(ImageInterface $image)
+    {
+        $this->image = $image;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getOrientation()
+    {
+        if ($this->exifData === null) {
+            $this->initialize();
+        }
+        if (isset($this->exifData['Orientation'])) {
+            return $this->exifData['Orientation'];
+        }
+        return null;
+    }
+
+    /**
+     * Prepares the EXIF data, used for lazy-loading.
+     * Should be called at first of any getter operation to make sure the exifData array is filled.
+     */
+    protected function initialize()
+    {
+        $exifData = exif_read_data('data://image/jpeg;base64,' . base64_encode($this->image->get('jpg')));
+        if ($exifData !== false) {
+            $this->exifData = $exifData;
+        }
+    }
+
+}

lib/Imagine/Image/Metadata/MetadataInterface.php

@@ -0,0 +1,45 @@
+<?php
+namespace Imagine\Image\Metadata;
+
+/*
+ * This file is part of the Imagine package.
+ *
+ * (c) Bulat Shakirzyanov <mallluhuct@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Imagine\Image\ImageInterface;
+
+/**
+ * An interface for Image Metadata
+ */
+interface MetadataInterface
+{
+    /**
+     * Constants representing how the orientation of the actual scene is mapped onto the presented image,
+     * inspired by Exif's Orientation tag
+     * @see http://sylvana.net/jpegcrop/exif_orientation.html
+     */
+    const ORIENTATION_NORMAL = 1;
+    const ORIENTATION_FLIPPED_HORIZONTALLY = 2;
+    const ORIENTATION_ROTATED_180 = 3;
+    const ORIENTATION_FLIPPED_VERTICALLY = 4;
+    const ORIENTATION_ROTATED_MINUS90_FLIPPED_VERTICALLY = 5;
+    const ORIENTATION_ROTATED_MINUS90 = 6;
+    const ORIENTATION_ROTATED_90_FLIPPED_VERTICALLY = 7;
+    const ORIENTATION_ROTATED_90 = 8;
+
+    /**
+     * @param ImageInterface $image
+     */
+    public function __construct(ImageInterface $image);
+
+    /**
+     * Returns an orientation integer inspired by Exif's Orientation tag
+     *
+     * @return integer
+     */
+    public function getOrientation();
+}

tests/Imagine/Test/Image/AbstractImageTest.php

@@ -562,6 +562,19 @@ public function testStripGBRImageHasGoodColors()
         $this->assertEquals('#d07560', (string) $color);
     }
 
+    public function testMetadataReturnsMetadataInstance()
+    {
+        $this->assertInstanceOf('Imagine\Image\Metadata\MetadataInterface', $this->getMonoLayeredImage()->metadata());
+    }
+
+    public function testCloningImageResultsInNewMetadataInstance()
+    {
+        $image = $this->getMonoLayeredImage();
+        $originalMetadata = $image->metadata();
+        $clone = clone $image;
+        $this->assertNotSame($originalMetadata, $clone->metadata(), 'The image\'s metadata is the same after cloning the image, but must be a new instance.');
+    }
+
     private function getMonoLayeredImage()
     {
         return $this->getImagine()->open('tests/Imagine/Fixtures/google.png');
@@ -587,6 +600,13 @@ protected function processInOut($file, $in, $out)
 
     }
 
+    /**
+     * @return \Imagine\Image\ImagineInterface
+     */
     abstract protected function getImagine();
+
+    /**
+     * @return boolean
+     */
     abstract protected function supportMultipleLayers();
 }

tests/Imagine/Test/Image/Metadata/ExifMetadataTest.php

@@ -0,0 +1,50 @@
+<?php
+namespace Imagine\Test\Image;
+
+/*
+ * This file is part of the Imagine package.
+ *
+ * (c) Bulat Shakirzyanov <mallluhuct@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Imagine\Image\Metadata\ExifMetadata;
+use Imagine\Image\Metadata\MetadataInterface;
+
+/**
+ */
+class ExifMetadataTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @test
+     */
+    public function getOrientationReturnsNullIfNoRotationIsGiven()
+    {
+        $metadata = new ExifMetadata($this->getImageMock('large.jpg'));
+        $this->assertNull($metadata->getOrientation());
+    }
+
+    /**
+     * @test
+     */
+    public function getOrientationReturnsCorrectRotationIfExifDataSaysSo()
+    {
+        $metadata = new ExifMetadata($this->getImageMock('exifOrientation/90.jpg'));
+        $this->assertSame(MetadataInterface::ORIENTATION_ROTATED_MINUS90, $metadata->getOrientation());
+    }
+
+    /**
+     * Gets an image mock for use with the ExifMetadata constructor
+     *
+     * @param string $fixtureImage
+     * @return \Imagine\Image\ImageInterface
+     */
+    protected function getImageMock($fixtureImage)
+    {
+        $mock = $this->getMock('Imagine\Image\ImageInterface');
+        $mock->expects($this->atLeastOnce())->method('get')->with('jpg')->will($this->returnValue(file_get_contents('tests/Imagine/Fixtures/' . $fixtureImage)));
+        return $mock;
+    }
+}