diff options
Diffstat (limited to 'lib/public/IImage.php')
| -rw-r--r-- | lib/public/IImage.php | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/lib/public/IImage.php b/lib/public/IImage.php new file mode 100644 index 00000000000..7ba08c889da --- /dev/null +++ b/lib/public/IImage.php @@ -0,0 +1,225 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only + */ +namespace OCP; + +use GdImage; + +/** + * Class for basic image manipulation + * @since 8.1.0 + */ +interface IImage { + /** + * Determine whether the object contains an image resource. + * + * @since 8.1.0 + */ + public function valid(): bool; + + /** + * Returns the MIME type of the image or null if no image is loaded. + * + * @since 8.1.0 + */ + public function mimeType(): ?string; + + /** + * Returns the width of the image or -1 if no image is loaded. + * + * @since 8.1.0 + */ + public function width(): int; + + /** + * Returns the height of the image or -1 if no image is loaded. + * + * @since 8.1.0 + */ + public function height(): int; + + /** + * Returns the width when the image orientation is top-left. + * + * @since 8.1.0 + */ + public function widthTopLeft(): int; + + /** + * Returns the height when the image orientation is top-left. + * + * @since 8.1.0 + */ + public function heightTopLeft(): int; + + /** + * Outputs the image. + * + * @since 8.1.0 + */ + public function show(?string $mimeType = null): bool; + + /** + * Saves the image. + * + * @param string $filePath + * @param string $mimeType + * @since 8.1.0 + */ + public function save(?string $filePath = null, ?string $mimeType = null): bool; + + /** + * @return false|resource|\GdImage Returns the image resource if any + * @since 8.1.0 + */ + public function resource(); + + /** + * @return string Returns the mimetype of the data. Returns null + * if the data is not valid. + * @since 13.0.0 + */ + public function dataMimeType(): ?string; + + /** + * @return string Returns the raw image data. + * @since 8.1.0 + */ + public function data(): ?string; + + /** + * (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. + * @since 8.1.0 + */ + public function getOrientation(): int; + + /** + * (I'm open for suggestions on better method name ;) + * Fixes orientation based on EXIF data. + * + * @since 8.1.0 + */ + public function fixOrientation(): bool; + + /** + * Resizes the image preserving ratio. + * + * @param integer $maxSize The maximum size of either the width or height. + * @since 8.1.0 + */ + public function resize(int $maxSize): bool; + + /** + * @param int $width + * @param int $height + * @return bool + * @since 8.1.0 + */ + public function preciseResize(int $width, int $height): bool; + + /** + * 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 + * @since 8.1.0 + */ + public function centerCrop(int $size = 0): bool; + + /** + * 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 + * @since 8.1.0 + */ + public function crop(int $x, int $y, int $w, int $h): bool; + + /** + * Resizes the image to fit within a boundary while preserving ratio. + * + * Warning: Images smaller than $maxWidth x $maxHeight will end up being scaled up + * + * @param int $maxWidth + * @param int $maxHeight + * @since 8.1.0 + */ + public function fitIn(int $maxWidth, int $maxHeight): bool; + + /** + * Shrinks the image to fit within a boundary while preserving ratio. + * + * @param int $maxWidth + * @param int $maxHeight + * @since 8.1.0 + */ + public function scaleDownToFit(int $maxWidth, int $maxHeight): bool; + + /** + * create a copy of this image + * + * @return IImage + * @since 19.0.0 + */ + public function copy(): IImage; + + /** + * create a new cropped copy of this image + * + * @param int $x Horizontal position + * @param int $y Vertical position + * @param int $w Width + * @param int $h Height + * @return IImage + * @since 19.0.0 + */ + public function cropCopy(int $x, int $y, int $w, int $h): IImage; + + /** + * create a new resized copy of this image + * + * @param int $width + * @param int $height + * @return IImage + * @since 19.0.0 + */ + public function preciseResizeCopy(int $width, int $height): IImage; + + /** + * Resizes the image preserving ratio, returning a new copy + * + * @param int $maxSize The maximum size of either the width or height. + * @return IImage + * @since 19.0.0 + */ + public function resizeCopy(int $maxSize): IImage; + + /** + * Loads an image from a string of data. + * + * @param string $str A string of image data as read from a file. + * + * @since 31.0.0 + */ + public function loadFromData(string $str): GdImage|false; + + /** + * Reads the EXIF data for an image. + * + * @param string $data EXIF data + * + * @since 31.0.0 + */ + public function readExif(string $data): void; +} |