1
0

IImage.php 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
  5. * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
  6. * SPDX-License-Identifier: AGPL-3.0-only
  7. */
  8. namespace OCP;
  9. /**
  10. * Class for basic image manipulation
  11. * @since 8.1.0
  12. */
  13. interface IImage {
  14. /**
  15. * Determine whether the object contains an image resource.
  16. *
  17. * @since 8.1.0
  18. */
  19. public function valid(): bool;
  20. /**
  21. * Returns the MIME type of the image or null if no image is loaded.
  22. *
  23. * @since 8.1.0
  24. */
  25. public function mimeType(): ?string;
  26. /**
  27. * Returns the width of the image or -1 if no image is loaded.
  28. *
  29. * @since 8.1.0
  30. */
  31. public function width(): int;
  32. /**
  33. * Returns the height of the image or -1 if no image is loaded.
  34. *
  35. * @since 8.1.0
  36. */
  37. public function height(): int;
  38. /**
  39. * Returns the width when the image orientation is top-left.
  40. *
  41. * @since 8.1.0
  42. */
  43. public function widthTopLeft(): int;
  44. /**
  45. * Returns the height when the image orientation is top-left.
  46. *
  47. * @since 8.1.0
  48. */
  49. public function heightTopLeft(): int;
  50. /**
  51. * Outputs the image.
  52. *
  53. * @since 8.1.0
  54. */
  55. public function show(?string $mimeType = null): bool;
  56. /**
  57. * Saves the image.
  58. *
  59. * @param string $filePath
  60. * @param string $mimeType
  61. * @since 8.1.0
  62. */
  63. public function save(?string $filePath = null, ?string $mimeType = null): bool;
  64. /**
  65. * @return false|resource|\GdImage Returns the image resource if any
  66. * @since 8.1.0
  67. */
  68. public function resource();
  69. /**
  70. * @return string Returns the mimetype of the data. Returns null
  71. * if the data is not valid.
  72. * @since 13.0.0
  73. */
  74. public function dataMimeType(): ?string;
  75. /**
  76. * @return string Returns the raw image data.
  77. * @since 8.1.0
  78. */
  79. public function data(): ?string;
  80. /**
  81. * (I'm open for suggestions on better method name ;)
  82. * Get the orientation based on EXIF data.
  83. *
  84. * @return int The orientation or -1 if no EXIF data is available.
  85. * @since 8.1.0
  86. */
  87. public function getOrientation(): int;
  88. /**
  89. * (I'm open for suggestions on better method name ;)
  90. * Fixes orientation based on EXIF data.
  91. *
  92. * @since 8.1.0
  93. */
  94. public function fixOrientation(): bool;
  95. /**
  96. * Resizes the image preserving ratio.
  97. *
  98. * @param integer $maxSize The maximum size of either the width or height.
  99. * @since 8.1.0
  100. */
  101. public function resize(int $maxSize): bool;
  102. /**
  103. * @param int $width
  104. * @param int $height
  105. * @return bool
  106. * @since 8.1.0
  107. */
  108. public function preciseResize(int $width, int $height): bool;
  109. /**
  110. * Crops the image to the middle square. If the image is already square it just returns.
  111. *
  112. * @param int $size maximum size for the result (optional)
  113. * @return bool for success or failure
  114. * @since 8.1.0
  115. */
  116. public function centerCrop(int $size = 0): bool;
  117. /**
  118. * Crops the image from point $x$y with dimension $wx$h.
  119. *
  120. * @param int $x Horizontal position
  121. * @param int $y Vertical position
  122. * @param int $w Width
  123. * @param int $h Height
  124. * @return bool for success or failure
  125. * @since 8.1.0
  126. */
  127. public function crop(int $x, int $y, int $w, int $h): bool;
  128. /**
  129. * Resizes the image to fit within a boundary while preserving ratio.
  130. *
  131. * Warning: Images smaller than $maxWidth x $maxHeight will end up being scaled up
  132. *
  133. * @param int $maxWidth
  134. * @param int $maxHeight
  135. * @since 8.1.0
  136. */
  137. public function fitIn(int $maxWidth, int $maxHeight): bool;
  138. /**
  139. * Shrinks the image to fit within a boundary while preserving ratio.
  140. *
  141. * @param int $maxWidth
  142. * @param int $maxHeight
  143. * @since 8.1.0
  144. */
  145. public function scaleDownToFit(int $maxWidth, int $maxHeight): bool;
  146. /**
  147. * create a copy of this image
  148. *
  149. * @return IImage
  150. * @since 19.0.0
  151. */
  152. public function copy(): IImage;
  153. /**
  154. * create a new cropped copy of this image
  155. *
  156. * @param int $x Horizontal position
  157. * @param int $y Vertical position
  158. * @param int $w Width
  159. * @param int $h Height
  160. * @return IImage
  161. * @since 19.0.0
  162. */
  163. public function cropCopy(int $x, int $y, int $w, int $h): IImage;
  164. /**
  165. * create a new resized copy of this image
  166. *
  167. * @param int $width
  168. * @param int $height
  169. * @return IImage
  170. * @since 19.0.0
  171. */
  172. public function preciseResizeCopy(int $width, int $height): IImage;
  173. /**
  174. * Resizes the image preserving ratio, returning a new copy
  175. *
  176. * @param int $maxSize The maximum size of either the width or height.
  177. * @return IImage
  178. * @since 19.0.0
  179. */
  180. public function resizeCopy(int $maxSize): IImage;
  181. }