1
0

IImage.php 5.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * @copyright Copyright (c) 2016, ownCloud, Inc.
  5. *
  6. * @author Joas Schilling <coding@schilljs.com>
  7. * @author Morris Jobke <hey@morrisjobke.de>
  8. * @author Olivier Paroz <github@oparoz.com>
  9. * @author Robin Appelman <robin@icewind.nl>
  10. * @author Roeland Jago Douma <roeland@famdouma.nl>
  11. *
  12. * @license AGPL-3.0
  13. *
  14. * This code is free software: you can redistribute it and/or modify
  15. * it under the terms of the GNU Affero General Public License, version 3,
  16. * as published by the Free Software Foundation.
  17. *
  18. * This program is distributed in the hope that it will be useful,
  19. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  21. * GNU Affero General Public License for more details.
  22. *
  23. * You should have received a copy of the GNU Affero General Public License, version 3,
  24. * along with this program. If not, see <http://www.gnu.org/licenses/>
  25. *
  26. */
  27. namespace OCP;
  28. /**
  29. * Class for basic image manipulation
  30. * @since 8.1.0
  31. */
  32. interface IImage {
  33. /**
  34. * Determine whether the object contains an image resource.
  35. *
  36. * @since 8.1.0
  37. */
  38. public function valid(): bool;
  39. /**
  40. * Returns the MIME type of the image or null if no image is loaded.
  41. *
  42. * @since 8.1.0
  43. */
  44. public function mimeType(): ?string;
  45. /**
  46. * Returns the width of the image or -1 if no image is loaded.
  47. *
  48. * @since 8.1.0
  49. */
  50. public function width(): int;
  51. /**
  52. * Returns the height of the image or -1 if no image is loaded.
  53. *
  54. * @since 8.1.0
  55. */
  56. public function height(): int;
  57. /**
  58. * Returns the width when the image orientation is top-left.
  59. *
  60. * @since 8.1.0
  61. */
  62. public function widthTopLeft(): int;
  63. /**
  64. * Returns the height when the image orientation is top-left.
  65. *
  66. * @since 8.1.0
  67. */
  68. public function heightTopLeft(): int;
  69. /**
  70. * Outputs the image.
  71. *
  72. * @since 8.1.0
  73. */
  74. public function show(?string $mimeType = null): bool;
  75. /**
  76. * Saves the image.
  77. *
  78. * @param string $filePath
  79. * @param string $mimeType
  80. * @since 8.1.0
  81. */
  82. public function save(?string $filePath = null, ?string $mimeType = null): bool;
  83. /**
  84. * @return false|resource|\GdImage Returns the image resource if any
  85. * @since 8.1.0
  86. */
  87. public function resource();
  88. /**
  89. * @return string Returns the mimetype of the data. Returns null
  90. * if the data is not valid.
  91. * @since 13.0.0
  92. */
  93. public function dataMimeType(): ?string;
  94. /**
  95. * @return string Returns the raw image data.
  96. * @since 8.1.0
  97. */
  98. public function data(): ?string;
  99. /**
  100. * (I'm open for suggestions on better method name ;)
  101. * Get the orientation based on EXIF data.
  102. *
  103. * @return int The orientation or -1 if no EXIF data is available.
  104. * @since 8.1.0
  105. */
  106. public function getOrientation(): int;
  107. /**
  108. * (I'm open for suggestions on better method name ;)
  109. * Fixes orientation based on EXIF data.
  110. *
  111. * @since 8.1.0
  112. */
  113. public function fixOrientation(): bool;
  114. /**
  115. * Resizes the image preserving ratio.
  116. *
  117. * @param integer $maxSize The maximum size of either the width or height.
  118. * @since 8.1.0
  119. */
  120. public function resize(int $maxSize): bool;
  121. /**
  122. * @param int $width
  123. * @param int $height
  124. * @return bool
  125. * @since 8.1.0
  126. */
  127. public function preciseResize(int $width, int $height): bool;
  128. /**
  129. * Crops the image to the middle square. If the image is already square it just returns.
  130. *
  131. * @param int $size maximum size for the result (optional)
  132. * @return bool for success or failure
  133. * @since 8.1.0
  134. */
  135. public function centerCrop(int $size = 0): bool;
  136. /**
  137. * Crops the image from point $x$y with dimension $wx$h.
  138. *
  139. * @param int $x Horizontal position
  140. * @param int $y Vertical position
  141. * @param int $w Width
  142. * @param int $h Height
  143. * @return bool for success or failure
  144. * @since 8.1.0
  145. */
  146. public function crop(int $x, int $y, int $w, int $h): bool;
  147. /**
  148. * Resizes the image to fit within a boundary while preserving ratio.
  149. *
  150. * Warning: Images smaller than $maxWidth x $maxHeight will end up being scaled up
  151. *
  152. * @param int $maxWidth
  153. * @param int $maxHeight
  154. * @since 8.1.0
  155. */
  156. public function fitIn(int $maxWidth, int $maxHeight): bool;
  157. /**
  158. * Shrinks the image to fit within a boundary while preserving ratio.
  159. *
  160. * @param int $maxWidth
  161. * @param int $maxHeight
  162. * @since 8.1.0
  163. */
  164. public function scaleDownToFit(int $maxWidth, int $maxHeight): bool;
  165. /**
  166. * create a copy of this image
  167. *
  168. * @return IImage
  169. * @since 19.0.0
  170. */
  171. public function copy(): IImage;
  172. /**
  173. * create a new cropped copy of this image
  174. *
  175. * @param int $x Horizontal position
  176. * @param int $y Vertical position
  177. * @param int $w Width
  178. * @param int $h Height
  179. * @return IImage
  180. * @since 19.0.0
  181. */
  182. public function cropCopy(int $x, int $y, int $w, int $h): IImage;
  183. /**
  184. * create a new resized copy of this image
  185. *
  186. * @param int $width
  187. * @param int $height
  188. * @return IImage
  189. * @since 19.0.0
  190. */
  191. public function preciseResizeCopy(int $width, int $height): IImage;
  192. /**
  193. * Resizes the image preserving ratio, returning a new copy
  194. *
  195. * @param int $maxSize The maximum size of either the width or height.
  196. * @return IImage
  197. * @since 19.0.0
  198. */
  199. public function resizeCopy(int $maxSize): IImage;
  200. }