From 8ed27d2ce0477f40a27cdc335361b0d5654a7e09 Mon Sep 17 00:00:00 2001
From: Joas Schilling <nickvergessen@owncloud.com>
Date: Fri, 13 Mar 2015 10:10:11 +0100
Subject: [PATCH] Create an interface for OC_Image and OCP\Image for the public
 API

---
 core/avatar/avatarcontroller.php |   2 +-
 lib/private/avatar.php           |   6 +-
 lib/private/image.php            |   7 +-
 lib/private/preview.php          |  12 +-
 lib/private/preview/movie.php    |   2 +-
 lib/private/preview/mp3.php      |   3 +-
 lib/private/preview/provider.php |   4 +-
 lib/private/previewmanager.php   |   2 +-
 lib/public/iavatar.php           |   4 +-
 lib/public/iimage.php            | 193 +++++++++++++++++++++++++++++++
 lib/public/ipreview.php          |   2 +-
 lib/public/preview/iprovider.php |   4 +-
 tests/lib/image.php              |   4 +
 13 files changed, 220 insertions(+), 25 deletions(-)
 create mode 100644 lib/public/iimage.php

diff --git a/core/avatar/avatarcontroller.php b/core/avatar/avatarcontroller.php
index f63e02b7761..b63c8ad53b5 100644
--- a/core/avatar/avatarcontroller.php
+++ b/core/avatar/avatarcontroller.php
@@ -95,7 +95,7 @@ class AvatarController extends Controller {
 		$avatar = $this->avatarManager->getAvatar($userId);
 		$image = $avatar->get($size);
 
-		if ($image instanceof \OC_Image) {
+		if ($image instanceof \OCP\IImage) {
 			$resp = new DataDisplayResponse($image->data(),
 				Http::STATUS_OK,
 				['Content-Type' => $image->mimeType()]);
diff --git a/lib/private/avatar.php b/lib/private/avatar.php
index 23b3c82771a..da9c84d84a4 100644
--- a/lib/private/avatar.php
+++ b/lib/private/avatar.php
@@ -29,7 +29,7 @@ class Avatar implements \OCP\IAvatar {
 	/**
 	 * get the users avatar
 	 * @param int $size size in px of the avatar, avatars are square, defaults to 64
-	 * @return boolean|\OC_Image containing the avatar or false if there's no image
+	 * @return boolean|\OCP\IImage containing the avatar or false if there's no image
 	*/
 	public function get ($size = 64) {
 		if ($this->view->file_exists('avatar.jpg')) {
@@ -57,14 +57,14 @@ class Avatar implements \OCP\IAvatar {
 
 	/**
 	 * sets the users avatar
-	 * @param \OC_Image|resource|string $data OC_Image, imagedata or path to set a new avatar
+	 * @param \OCP\IImage|resource|string $data An image object, imagedata or path to set a new avatar
 	 * @throws \Exception if the provided file is not a jpg or png image
 	 * @throws \Exception if the provided image is not valid
 	 * @throws \OC\NotSquareException if the image is not square
 	 * @return void
 	*/
 	public function set ($data) {
-		if($data instanceOf OC_Image) {
+		if($data instanceOf \OCP\IImage) {
 			$img = $data;
 			$data = $img->data();
 		} else {
diff --git a/lib/private/image.php b/lib/private/image.php
index 2484aeecc63..c8509c61286 100644
--- a/lib/private/image.php
+++ b/lib/private/image.php
@@ -15,7 +15,7 @@
 /**
  * Class for basic image manipulation
  */
-class OC_Image {
+class OC_Image implements \OCP\IImage {
 	protected $resource = false; // tmp resource.
 	protected $imageType = IMAGETYPE_PNG; // Default to png if file type isn't evident.
 	protected $mimeType = "image/png"; // Default to png
@@ -285,7 +285,7 @@ class OC_Image {
 	/**
 	 * @return null|string Returns the raw image data.
 	 */
-	function data() {
+	public function data() {
 		if (!$this->valid()) {
 			return null;
 		}
@@ -949,6 +949,9 @@ class OC_Image {
 		return true;
 	}
 
+	/**
+	 * Destroys the current image and resets the object
+	 */
 	public function destroy() {
 		if ($this->valid()) {
 			imagedestroy($this->resource);
diff --git a/lib/private/preview.php b/lib/private/preview.php
index cb3554fa1e9..f69b0d6c971 100644
--- a/lib/private/preview.php
+++ b/lib/private/preview.php
@@ -46,7 +46,7 @@ class Preview {
 	/**
 	 * preview images object
 	 *
-	 * @var \OC_Image
+	 * @var \OCP\IImage
 	 */
 	private $preview;
 
@@ -465,7 +465,7 @@ class Preview {
 
 	/**
 	 * return a preview of a file
-	 * @return \OC_Image
+	 * @return \OCP\IImage
 	 */
 	public function getPreview() {
 		if (!is_null($this->preview) && $this->preview->valid()) {
@@ -518,7 +518,7 @@ class Preview {
 					/** @var $provider Provider */
 					$preview = $provider->getThumbnail($file, $maxX, $maxY, $scalingUp, $this->fileView);
 
-					if (!($preview instanceof \OC_Image)) {
+					if (!($preview instanceof \OCP\IImage)) {
 						continue;
 					}
 
@@ -564,7 +564,7 @@ class Preview {
 		if (is_null($this->preview)) {
 			$this->getPreview();
 		}
-		if ($this->preview instanceof \OC_Image) {
+		if ($this->preview instanceof \OCP\IImage) {
 			$this->preview->show($mimeType);
 		}
 	}
@@ -580,8 +580,8 @@ class Preview {
 		$scalingUp = $this->getScalingUp();
 		$maxScaleFactor = $this->getMaxScaleFactor();
 
-		if (!($image instanceof \OC_Image)) {
-			\OC_Log::write('core', '$this->preview is not an instance of OC_Image', \OC_Log::DEBUG);
+		if (!($image instanceof \OCP\IImage)) {
+			\OC_Log::write('core', '$this->preview is not an instance of \OCP\IImage', \OC_Log::DEBUG);
 			return;
 		}
 
diff --git a/lib/private/preview/movie.php b/lib/private/preview/movie.php
index 06353ddebb7..85151f5dbaa 100644
--- a/lib/private/preview/movie.php
+++ b/lib/private/preview/movie.php
@@ -61,7 +61,7 @@ class Movie extends Provider {
 	 * @param int $maxY
 	 * @param string $absPath
 	 * @param int $second
-	 * @return bool|\OC_Image
+	 * @return bool|\OCP\IImage
 	 */
 	private function generateThumbNail($maxX, $maxY, $absPath, $second) {
 		$tmpPath = \OC_Helper::tmpFile();
diff --git a/lib/private/preview/mp3.php b/lib/private/preview/mp3.php
index f1a50d99e13..19360f4f036 100644
--- a/lib/private/preview/mp3.php
+++ b/lib/private/preview/mp3.php
@@ -39,8 +39,7 @@ class MP3 extends Provider {
 	/**
 	 * Generates a default image when the file has no cover
 	 *
-	 * @return false|\OC_Image	False if the default image is missing or invalid,
-	 *							otherwise the image is returned as \OC_Image
+	 * @return bool|\OCP\IImage false if the default image is missing or invalid
 	 */
 	private function getNoCoverThumbnail() {
 		$icon = \OC::$SERVERROOT . '/core/img/filetypes/audio.png';
diff --git a/lib/private/preview/provider.php b/lib/private/preview/provider.php
index 3cce8c2ab85..1d6fac13965 100644
--- a/lib/private/preview/provider.php
+++ b/lib/private/preview/provider.php
@@ -37,9 +37,7 @@ abstract class Provider implements IProvider {
 	 * @param int $maxY The maximum Y size of the thumbnail. It can be smaller depending on the shape of the image
 	 * @param bool $scalingup Disable/Enable upscaling of previews
 	 * @param \OC\Files\View $fileview fileview object of user folder
-	 * @return mixed
-	 * 		false if no preview was generated
-	 *		OC_Image object of the preview
+	 * @return bool|\OCP\IImage false if no preview was generated
 	 */
 	abstract public function getThumbnail($path, $maxX, $maxY, $scalingup, $fileview);
 }
diff --git a/lib/private/previewmanager.php b/lib/private/previewmanager.php
index 0d3ec40c06b..0a0c47df28f 100644
--- a/lib/private/previewmanager.php
+++ b/lib/private/previewmanager.php
@@ -96,7 +96,7 @@ class PreviewManager implements IPreview {
 	 * @param int $maxX The maximum X size of the thumbnail. It can be smaller depending on the shape of the image
 	 * @param int $maxY The maximum Y size of the thumbnail. It can be smaller depending on the shape of the image
 	 * @param boolean $scaleUp Scale smaller images up to the thumbnail size or not. Might look ugly
-	 * @return \OCP\Image
+	 * @return \OCP\IImage
 	 */
 	public function createPreview($file, $maxX = 100, $maxY = 75, $scaleUp = false) {
 		$preview = new \OC\Preview('', '/', $file, $maxX, $maxY, $scaleUp);
diff --git a/lib/public/iavatar.php b/lib/public/iavatar.php
index 8f432c23fb8..984fe1075b4 100644
--- a/lib/public/iavatar.php
+++ b/lib/public/iavatar.php
@@ -16,7 +16,7 @@ interface IAvatar {
 	/**
 	 * get the users avatar
 	 * @param int $size size in px of the avatar, avatars are square, defaults to 64
-	 * @return boolean|\OC_Image containing the avatar or false if there's no image
+	 * @return boolean|\OCP\IImage containing the avatar or false if there's no image
 	 */
 	function get($size = 64);
 
@@ -29,7 +29,7 @@ interface IAvatar {
 
 	/**
 	 * sets the users avatar
-	 * @param \OC_Image|resource|string $data OC_Image, imagedata or path to set a new avatar
+	 * @param \OCP\IImage|resource|string $data An image object, imagedata or path to set a new avatar
 	 * @throws \Exception if the provided file is not a jpg or png image
 	 * @throws \Exception if the provided image is not valid
 	 * @throws \OC\NotSquareException if the image is not square
diff --git a/lib/public/iimage.php b/lib/public/iimage.php
new file mode 100644
index 00000000000..6ba7a501eb8
--- /dev/null
+++ b/lib/public/iimage.php
@@ -0,0 +1,193 @@
+<?php
+/**
+ * ownCloud
+ *
+ * @author Joas Schilling
+ * @copyright 2015 Joas Schilling nickvergessen@owncloud.com
+ *
+ * This file is licensed under the Affero General Public License version 3 or
+ * later.
+ * See the COPYING-README file.
+ */
+namespace OCP;
+
+
+/**
+ * Class for basic image manipulation
+ */
+interface IImage {
+
+	/**
+	 * Determine whether the object contains an image resource.
+	 *
+	 * @return bool
+	 */
+	public function valid();
+
+	/**
+	 * Returns the MIME type of the image or an empty string if no image is loaded.
+	 *
+	 * @return string
+	 */
+	public function mimeType();
+
+	/**
+	 * Returns the width of the image or -1 if no image is loaded.
+	 *
+	 * @return int
+	 */
+	public function width();
+
+	/**
+	 * Returns the height of the image or -1 if no image is loaded.
+	 *
+	 * @return int
+	 */
+	public function height();
+
+	/**
+	 * Returns the width when the image orientation is top-left.
+	 *
+	 * @return int
+	 */
+	public function widthTopLeft();
+
+	/**
+	 * Returns the height when the image orientation is top-left.
+	 *
+	 * @return int
+	 */
+	public function heightTopLeft();
+
+	/**
+	 * Outputs the image.
+	 *
+	 * @param string $mimeType
+	 * @return bool
+	 */
+	public function show($mimeType = null);
+
+	/**
+	 * Saves the image.
+	 *
+	 * @param string $filePath
+	 * @param string $mimeType
+	 * @return bool
+	 */
+	public function save($filePath = null, $mimeType = null);
+
+	/**
+	 * @return resource Returns the image resource in any.
+	 */
+	public function resource();
+
+	/**
+	 * @return string Returns the raw image data.
+	 */
+	public function data();
+
+	/**
+	 * (I'm open for suggestions on better method name ;)
+	 * Get the orientation based on EXIF data.
+	 *
+	 * @return int The orientation or -1 if no EXIF data is available.
+	 */
+	public function getOrientation();
+
+	/**
+	 * (I'm open for suggestions on better method name ;)
+	 * Fixes orientation based on EXIF data.
+	 *
+	 * @return bool.
+	 */
+	public function fixOrientation();
+
+	/**
+	 * Loads an image from a local file, a base64 encoded string or a resource created by an imagecreate* function.
+	 *
+	 * @param resource|string $imageRef The path to a local file, a base64 encoded string or a resource created by an imagecreate* function or a file resource (file handle    ).
+	 * @return resource|false An image resource or false on error
+	 */
+	public function load($imageRef);
+
+	/**
+	 * Loads an image from an open file handle.
+	 * It is the responsibility of the caller to position the pointer at the correct place and to close the handle again.
+	 *
+	 * @param resource $handle
+	 * @return resource|false An image resource or false on error
+	 */
+	public function loadFromFileHandle($handle);
+
+	/**
+	 * Loads an image from a local file.
+	 *
+	 * @param bool|string $imagePath The path to a local file.
+	 * @return bool|resource An image resource or false on error
+	 */
+	public function loadFromFile($imagePath = false);
+
+	/**
+	 * Loads an image from a string of data.
+	 *
+	 * @param string $str A string of image data as read from a file.
+	 * @return bool|resource An image resource or false on error
+	 */
+	public function loadFromData($str);
+
+	/**
+	 * Loads an image from a base64 encoded string.
+	 *
+	 * @param string $str A string base64 encoded string of image data.
+	 * @return bool|resource An image resource or false on error
+	 */
+	public function loadFromBase64($str);
+
+	/**
+	 * Resizes the image preserving ratio.
+	 *
+	 * @param integer $maxSize The maximum size of either the width or height.
+	 * @return bool
+	 */
+	public function resize($maxSize);
+
+	/**
+	 * @param int $width
+	 * @param int $height
+	 * @return bool
+	 */
+	public function preciseResize($width, $height);
+
+	/**
+	 * Crops the image to the middle square. If the image is already square it just returns.
+	 *
+	 * @param int $size maximum size for the result (optional)
+	 * @return bool for success or failure
+	 */
+	public function centerCrop($size = 0);
+
+	/**
+	 * Crops the image from point $x$y with dimension $wx$h.
+	 *
+	 * @param int $x Horizontal position
+	 * @param int $y Vertical position
+	 * @param int $w Width
+	 * @param int $h Height
+	 * @return bool for success or failure
+	 */
+	public function crop($x, $y, $w, $h);
+
+	/**
+	 * Resizes the image to fit within a boundary while preserving ratio.
+	 *
+	 * @param integer $maxWidth
+	 * @param integer $maxHeight
+	 * @return bool
+	 */
+	public function fitIn($maxWidth, $maxHeight);
+
+	/**
+	 * Destroys the current image and resets the object
+	 */
+	public function destroy();
+}
diff --git a/lib/public/ipreview.php b/lib/public/ipreview.php
index c1bc4cb680c..202b0d03948 100644
--- a/lib/public/ipreview.php
+++ b/lib/public/ipreview.php
@@ -67,7 +67,7 @@ interface IPreview {
 	 * @param int $maxX The maximum X size of the thumbnail. It can be smaller depending on the shape of the image
 	 * @param int $maxY The maximum Y size of the thumbnail. It can be smaller depending on the shape of the image
 	 * @param boolean $scaleUp Scale smaller images up to the thumbnail size or not. Might look ugly
-	 * @return \OCP\Image
+	 * @return \OCP\IImage
 	 */
 	public function createPreview($file, $maxX = 100, $maxY = 75, $scaleUp = false);
 
diff --git a/lib/public/preview/iprovider.php b/lib/public/preview/iprovider.php
index 74e5cca05d9..4318ecd37ac 100644
--- a/lib/public/preview/iprovider.php
+++ b/lib/public/preview/iprovider.php
@@ -33,9 +33,7 @@ interface IProvider {
 	 * @param int $maxY The maximum Y size of the thumbnail. It can be smaller depending on the shape of the image
 	 * @param bool $scalingup Disable/Enable upscaling of previews
 	 * @param \OC\Files\View $fileview fileview object of user folder
-	 * @return mixed
-	 *        false if no preview was generated
-	 *        OC_Image object of the preview
+	 * @return bool|\OCP\IImage false if no preview was generated
 	 */
 	public function getThumbnail($path, $maxX, $maxY, $scalingup, $fileview);
 }
diff --git a/tests/lib/image.php b/tests/lib/image.php
index 0ee517100ad..a22e210947b 100644
--- a/tests/lib/image.php
+++ b/tests/lib/image.php
@@ -31,20 +31,24 @@ class Test_Image extends \Test\TestCase {
 	public function testConstructDestruct() {
 		$img = new \OC_Image(OC::$SERVERROOT.'/tests/data/testimage.png');
 		$this->assertInstanceOf('\OC_Image', $img);
+		$this->assertInstanceOf('\OCP\IImage', $img);
 		unset($img);
 
 		$imgcreate = imagecreatefromjpeg(OC::$SERVERROOT.'/tests/data/testimage.jpg');
 		$img = new \OC_Image($imgcreate);
 		$this->assertInstanceOf('\OC_Image', $img);
+		$this->assertInstanceOf('\OCP\IImage', $img);
 		unset($img);
 
 		$base64 = base64_encode(file_get_contents(OC::$SERVERROOT.'/tests/data/testimage.gif'));
 		$img = new \OC_Image($base64);
 		$this->assertInstanceOf('\OC_Image', $img);
+		$this->assertInstanceOf('\OCP\IImage', $img);
 		unset($img);
 
 		$img = new \OC_Image(null);
 		$this->assertInstanceOf('\OC_Image', $img);
+		$this->assertInstanceOf('\OCP\IImage', $img);
 		unset($img);
 	}
 
-- 
2.39.5