From 9e0d9cb53f6a46fe52f5e145fbcba604178ba8f7 Mon Sep 17 00:00:00 2001 From: Oliver Vogel Date: Sun, 26 Nov 2023 11:39:58 +0100 Subject: [PATCH] Add docblocks --- src/Analyzers/AbstractAnalyzer.php | 5 + src/Collection.php | 8 +- src/Drivers/AbstractDriver.php | 13 ++ src/Encoders/AbstractEncoder.php | 5 + src/Interfaces/AnalyzerInterface.php | 6 + src/Interfaces/CollectionInterface.php | 63 ++++++++- src/Interfaces/ColorProcessorInterface.php | 13 ++ src/Interfaces/CoreInterface.php | 39 ++++++ src/Interfaces/DriverInterface.php | 34 +++++ src/Interfaces/ImageInterface.php | 141 +++++++++++++++++++++ src/Modifiers/AbstractModifier.php | 5 + 11 files changed, 323 insertions(+), 9 deletions(-) diff --git a/src/Analyzers/AbstractAnalyzer.php b/src/Analyzers/AbstractAnalyzer.php index d633c429..74509e9b 100644 --- a/src/Analyzers/AbstractAnalyzer.php +++ b/src/Analyzers/AbstractAnalyzer.php @@ -7,6 +7,11 @@ use Intervention\Image\Interfaces\ImageInterface; abstract class AbstractAnalyzer implements AnalyzerInterface { + /** + * {@inheritdoc} + * + * @see AnalyzerInterface::analyze() + */ public function analyze(ImageInterface $image): mixed { return $image->analyze($this); diff --git a/src/Collection.php b/src/Collection.php index bb8eac32..94b75185 100644 --- a/src/Collection.php +++ b/src/Collection.php @@ -74,7 +74,7 @@ class Collection implements CollectionInterface, IteratorAggregate, Countable * * @return mixed */ - public function first() + public function first(): mixed { if ($item = reset($this->items)) { return $item; @@ -88,7 +88,7 @@ class Collection implements CollectionInterface, IteratorAggregate, Countable * * @return mixed */ - public function last() + public function last(): mixed { if ($item = end($this->items)) { return $item; @@ -103,7 +103,7 @@ class Collection implements CollectionInterface, IteratorAggregate, Countable * @param integer $key * @return mixed */ - public function getAtPosition(int $key = 0, $default = null) + public function getAtPosition(int $key = 0, $default = null): mixed { if ($this->count() == 0) { return $default; @@ -117,7 +117,7 @@ class Collection implements CollectionInterface, IteratorAggregate, Countable return $positions[$key]; } - public function get(int|string $query, $default = null) + public function get(int|string $query, $default = null): mixed { if ($this->count() == 0) { return $default; diff --git a/src/Drivers/AbstractDriver.php b/src/Drivers/AbstractDriver.php index 8117f81a..d21252a2 100644 --- a/src/Drivers/AbstractDriver.php +++ b/src/Drivers/AbstractDriver.php @@ -11,6 +11,13 @@ use ReflectionClass; abstract class AbstractDriver implements DriverInterface { + /** + * Return a specialized version for the current driver of the given object + * + * @param object $input + * @return object + * @throws NotSupportedException + */ public function resolve(object $input): object { if ($this->isExternal($input)) { @@ -30,6 +37,12 @@ abstract class AbstractDriver implements DriverInterface return new $specialized($input, $this); } + /** + * Determine if given object is external custom modifier, analyzer or encoder + * + * @param object $input + * @return bool + */ private function isExternal(object $input): bool { if ($input instanceof AbstractModifier) { diff --git a/src/Encoders/AbstractEncoder.php b/src/Encoders/AbstractEncoder.php index 757fc3ba..418e07ac 100644 --- a/src/Encoders/AbstractEncoder.php +++ b/src/Encoders/AbstractEncoder.php @@ -8,6 +8,11 @@ use Intervention\Image\Interfaces\ImageInterface; abstract class AbstractEncoder implements EncoderInterface { + /** + * {@inheritdoc} + * + * @see EncoderInterface::encode() + */ public function encode(ImageInterface $image): EncodedImage { return $image->encode($this); diff --git a/src/Interfaces/AnalyzerInterface.php b/src/Interfaces/AnalyzerInterface.php index 3466afef..4842827c 100644 --- a/src/Interfaces/AnalyzerInterface.php +++ b/src/Interfaces/AnalyzerInterface.php @@ -4,5 +4,11 @@ namespace Intervention\Image\Interfaces; interface AnalyzerInterface { + /** + * Analyze given image and return the retrieved data + * + * @param ImageInterface $image + * @return mixed + */ public function analyze(ImageInterface $image): mixed; } diff --git a/src/Interfaces/CollectionInterface.php b/src/Interfaces/CollectionInterface.php index 7db3b239..e67b3b58 100644 --- a/src/Interfaces/CollectionInterface.php +++ b/src/Interfaces/CollectionInterface.php @@ -6,12 +6,65 @@ use Traversable; interface CollectionInterface extends Traversable { + /** + * Determine if the collection has item at given key + * + * @param int|string $key + * @return bool + */ public function has(int|string $key): bool; + + /** + * Add item to collection + * + * @param mixed $item + * @return CollectionInterface + */ public function push($item): CollectionInterface; - public function get(int|string $key, $default = null); - public function getAtPosition(int $key = 0, $default = null); - public function first(); - public function last(); + + /** + * Return item for given key or return default is key does not exist + * + * @param int|string $key + * @param mixed $default + * @return mixed + */ + public function get(int|string $key, $default = null): mixed; + + /** + * Return item at given numeric position starting at 0 + * + * @param int $key + * @param mixed $default + * @return mixed + */ + public function getAtPosition(int $key = 0, $default = null): mixed; + + /** + * Return first item in collection + * + * @return mixed + */ + public function first(): mixed; + + /** + * Return last item in collection + * + * @return mixed + */ + public function last(): mixed; + + /** + * Return item count of collection + * + * @return int + */ public function count(): int; - // public function empty(): CollectionInterface; + + /** + * Empty collection + * + * @return CollectionInterface + */ + public function empty(): CollectionInterface; } diff --git a/src/Interfaces/ColorProcessorInterface.php b/src/Interfaces/ColorProcessorInterface.php index 81ace6b5..cfe57bb4 100644 --- a/src/Interfaces/ColorProcessorInterface.php +++ b/src/Interfaces/ColorProcessorInterface.php @@ -4,6 +4,19 @@ namespace Intervention\Image\Interfaces; interface ColorProcessorInterface { + /** + * Turn given color in the driver's color implementation + * + * @param ColorInterface $color + * @return mixed + */ public function colorToNative(ColorInterface $color); + + /** + * Turn the given driver's definition of a color into a color object + * + * @param mixed $native + * @return ColorInterface + */ public function nativeToColor(mixed $native): ColorInterface; } diff --git a/src/Interfaces/CoreInterface.php b/src/Interfaces/CoreInterface.php index a5ee2950..459a4324 100644 --- a/src/Interfaces/CoreInterface.php +++ b/src/Interfaces/CoreInterface.php @@ -6,10 +6,49 @@ use Traversable; interface CoreInterface extends Traversable { + /** + * return driver's representation of the image core. + * + * @return mixed + */ public function native(): mixed; + + /** + * Set driver's representation of the image core. + * + * @param mixed $native + * @return CoreInterface + */ public function setNative(mixed $native): CoreInterface; + + /** + * Count number of frames of animated image core + * + * @return int + */ public function count(): int; + + /** + * Return frame of given position in an animated image + * + * @param int $position + * @return FrameInterface + */ public function frame(int $position): FrameInterface; + + /** + * Return number of repetitions of an animated image + * + * @return int + */ public function loops(): int; + + /** + * Set the number of repetitions for an animation. Where a + * value of 0 means infinite repetition. + * + * @param int $loops + * @return CoreInterface + */ public function setLoops(int $loops): CoreInterface; } diff --git a/src/Interfaces/DriverInterface.php b/src/Interfaces/DriverInterface.php index cb628b5c..aa08890c 100644 --- a/src/Interfaces/DriverInterface.php +++ b/src/Interfaces/DriverInterface.php @@ -4,9 +4,43 @@ namespace Intervention\Image\Interfaces; interface DriverInterface { + /** + * Return drivers unique id + * + * @return string + */ public function id(): string; + + /** + * Resolve given object into a specialized version for the current driver + * + * @param object $input + * @return object + */ public function resolve(object $input): object; + + /** + * Create new image instance with the current driver in given dimensions + * + * @param int $width + * @param int $height + * @return ImageInterface + */ public function createImage(int $width, int $height): ImageInterface; + + /** + * Handle given input by decoding it to ImageInterface or ColorInterface + * + * @param mixed $input + * @return ImageInterface|ColorInterface + */ public function handleInput(mixed $input): ImageInterface|ColorInterface; + + /** + * Return color processor for the given colorspace + * + * @param ColorspaceInterface $colorspace + * @return ColorProcessorInterface + */ public function colorProcessor(ColorspaceInterface $colorspace): ColorProcessorInterface; } diff --git a/src/Interfaces/ImageInterface.php b/src/Interfaces/ImageInterface.php index 914fd2a4..5978c480 100644 --- a/src/Interfaces/ImageInterface.php +++ b/src/Interfaces/ImageInterface.php @@ -8,25 +8,166 @@ use IteratorAggregate; interface ImageInterface extends IteratorAggregate, Countable { + /** + * Return driver of current image + * + * @return DriverInterface + */ public function driver(): DriverInterface; + + /** + * Return core of current image + * + * @return CoreInterface + */ public function core(): CoreInterface; + + /** + * Return width of current image + * + * @return int + */ public function width(): int; + + /** + * Return height of current image + * + * @return int + */ public function height(): int; + + /** + * Return size of current image + * + * @return SizeInterface + */ public function size(): SizeInterface; + + /** + * Encode image with given encoder + * + * @param EncoderInterface $encoder + * @return EncodedImage + */ public function encode(EncoderInterface $encoder): EncodedImage; + + /** + * Apply given modifier to current image + * + * @param ModifierInterface $modifier + * @return ImageInterface + */ public function modify(ModifierInterface $modifier): ImageInterface; + + /** + * Analyzer current image with given analyzer + * + * @param AnalyzerInterface $analyzer + * @return mixed + */ public function analyze(AnalyzerInterface $analyzer): mixed; + + /** + * Determine if current image is animated + * + * @return bool + */ public function isAnimated(): bool; + + /** + * Return loop count of animated image + * + * @return int + */ public function loops(): int; + + /** + * Return exif data of current image + * + * @return mixed + */ public function exif(?string $query = null): mixed; + + /** + * Return image resolution/density + * + * @return ResolutionInterface + */ public function resolution(): ResolutionInterface; + + /** + * Get the colorspace of the image + * + * @return ColorspaceInterface + */ public function colorspace(): ColorspaceInterface; + + /** + * Return color of pixel at given position on given frame position + * + * @param int $x + * @param int $y + * @param int $frame_key + * @return ColorInterface + */ public function pickColor(int $x, int $y, int $frame_key = 0): ColorInterface; + + /** + * Return all colors of pixel at given position for all frames of image + * + * @param int $x + * @param int $y + * @return CollectionInterface + */ public function pickColors(int $x, int $y): CollectionInterface; + + /** + * Retrieve ICC color profile of image + * + * @return ProfileInterface + */ public function profile(): ProfileInterface; + + /** + * Sharpen the current image with given strength + * + * @param int $amount + * @return ImageInterface + */ public function sharpen(int $amount = 10): ImageInterface; + + /** + * Turn image into a greyscale version + * + * @return ImageInterface + */ public function greyscale(): ImageInterface; + + /** + * Apply pixelation filter effect on current image + * + * @param int $size + * @return ImageInterface + */ public function pixelate(int $size): ImageInterface; + + /** + * Rotate current image by given angle + * + * @param float $angle + * @param string $background + * @return ImageInterface + */ public function rotate(float $angle, mixed $background = 'ffffff'): ImageInterface; + + /** + * Draw text on image + * + * @param string $text + * @param int $x + * @param int $y + * @param callable|FontInterface $font + * @return ImageInterface + */ public function text(string $text, int $x, int $y, callable|FontInterface $font): ImageInterface; } diff --git a/src/Modifiers/AbstractModifier.php b/src/Modifiers/AbstractModifier.php index 3a57bab5..80a1aa02 100644 --- a/src/Modifiers/AbstractModifier.php +++ b/src/Modifiers/AbstractModifier.php @@ -7,6 +7,11 @@ use Intervention\Image\Interfaces\ModifierInterface; abstract class AbstractModifier implements ModifierInterface { + /** + * {@inheritdoc} + * + * @see ModifierInterface::apply() + */ public function apply(ImageInterface $image): ImageInterface { return $image->modify($this);