Merge pull request #2113 from MGatner/image-convert

Add Image->convert()

Author: lonnieezell

system/Images/Handlers/BaseHandler.php

@@ -286,6 +286,22 @@ public function crop(int $width = null, int $height = null, int $x = null, int $
 
 	//--------------------------------------------------------------------
 
+	/**
+	 * Changes the stored image type to indicate the new file format to use when saving.
+	 * Does not touch the actual resource.
+	 *
+	 * @param integer|null $imageType A PHP imageType constant, e.g. https://www.php.net/manual/en/function.image-type-to-mime-type.php
+	 *
+	 * @return $this
+	 */
+	public function convert(int $imageType)
+	{
+		$this->image->imageType = $imageType;
+		return $this;
+	}
+
+	//--------------------------------------------------------------------
+
 	/**
 	 * Rotates the image on the current canvas.
 	 *

system/Images/ImageHandlerInterface.php

@@ -74,6 +74,18 @@ public function crop(int $width = null, int $height = null, int $x = null, int $
 
 	//--------------------------------------------------------------------
 
+	/**
+	 * Changes the stored image type to indicate the new file format to use when saving.
+	 * Does not touch the actual resource.
+	 *
+	 * @param integer|null $imageType A PHP imagetype constant, e.g. https://www.php.net/manual/en/function.image-type-to-mime-type.php
+	 *
+	 * @return $this
+	 */
+	public function convert(int $imageType);
+
+	//--------------------------------------------------------------------
+
 	/**
 	 * Rotates the image on the current canvas.
 	 *

tests/system/Images/GDHandlerTest.php

@@ -332,4 +332,13 @@ public function testImageSave()
 		}
 	}
 
+	public function testImageConvert()
+	{
+		$this->handler->withFile($this->origin . 'ci-logo.jpeg');
+		$this->handler->getResource(); // make sure resource is loaded
+		$this->handler->convert(IMAGETYPE_PNG);
+		$this->handler->save($this->start . 'work/ci-logo.png');
+		$this->assertEquals(exif_imagetype($this->start . 'work/ci-logo.png'), IMAGETYPE_PNG);
+	}
+
 }

user_guide_src/source/libraries/images.rst

@@ -92,9 +92,10 @@ starting at the top left corner. The result would be saved as the thumbnail.
 Processing Methods
 ==================
 
-There are six available processing methods:
+There are seven available processing methods:
 
 -  $image->crop()
+-  $image->convert()
 -  $image->fit()
 -  $image->flatten()
 -  $image->flip()
@@ -155,6 +156,23 @@ offset values::
 		->crop(50, 50, $xOffset, $yOffset)
 		->save('path/to/new/image.jpg');
 
+Converting Images
+-----------------
+
+The ``convert()`` method changes the library's internal indicator for the desired file format. This doesn't touch the actual image resource, but indicates to ``save()`` what format to use::
+
+	convert(int $imageType)
+
+- **$imageType** is one of PHP's image type constants (see for example https://www.php.net/manual/en/function.image-type-to-mime-type.php)::
+
+	Services::image()
+		->withFile('/path/to/image/mypic.jpg')
+		->convert(IMAGETYPE_PNG)
+		->save('path/to/new/image.png');
+
+.. note:: ImageMagick already saves files in the type
+	indicated by their extension, ignoring **$imageType**
+
 Fitting Images
 --------------