Add aspect ratio support to Image rule

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 - New #665: Add methods `addErrorWithFormatOnly()` and `addErrorWithoutPostProcessing()` to `Result` object (@vjik)
 - Enh #668: Clarify psalm types in `Result` (@vjik)
-- New #670, #680: Add `Image` validation rule (@vjik, @arogachev)
+- New #670, #677, #680: Add `Image` validation rule (@vjik, @arogachev)
 - New #678: Add `Date`, `DateTime` and `Time` validation rules (@vjik)
 
 ## 1.2.0 February 21, 2024

src/Rule/Image/Image.php

@@ -6,6 +6,7 @@
 
 use Attribute;
 use Closure;
+use InvalidArgumentException;
 use Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait;
 use Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait;
 use Yiisoft\Validator\Rule\Trait\WhenTrait;
@@ -36,6 +37,7 @@ final class Image implements RuleWithOptionsInterface, SkipOnErrorInterface, Whe
      * @param int|null $minHeight Expected minimum height of validated image file.
      * @param int|null $maxWidth Expected maximum width of validated image file.
      * @param int|null $maxHeight Expected maximum height of validated image file.
+     * @param ImageAspectRatio|null $aspectRatio Expected aspect ratio of validated image file.
      * @param string $notImageMessage A message used when the validated value is not valid image file.
      *
      * You may use the following placeholders in the message:
@@ -89,6 +91,20 @@ final class Image implements RuleWithOptionsInterface, SkipOnErrorInterface, Whe
      *
      * - `{attribute}`: the translated label of the attribute being validated.
      * - `{limit}`: expected maximum height of validated image file.
+     *
+     * @param string $invalidAspectRatioMessage A message used when aspect ratio of validated image file is different
+     * than {@see ImageAspectRatio::$width}:{@see ImageAspectRatio::$height} with correction based on
+     * {@see ImageAspectRatio::$margin}.
+     *
+     * You may use the following placeholders in the message:
+     *
+     * - `{attribute}`: the translated label of the attribute being validated.
+     * - `{aspectRatioWidth}`: expected width part for aspect ratio. For example, for `4:3` aspect ratio, it will be
+     * `4`.
+     * - `{aspectRatioHeight}`: expected height part for aspect ratio. For example, for `4:3` aspect ratio, it will be
+     *  `3`.
+     * - `{aspectRatioMargin}`: expected margin for aspect ratio in percents.
+     *
      * @param bool|callable|null $skipOnEmpty Whether to skip this rule if the value validated is empty.
      * See {@see SkipOnEmptyInterface}.
      * @param bool $skipOnError Whether to skip this rule if any of the previous rules gave an error.
@@ -105,17 +121,26 @@ public function __construct(
         private ?int $minHeight = null,
         private ?int $maxWidth = null,
         private ?int $maxHeight = null,
+        private ?ImageAspectRatio $aspectRatio = null,
         private string $notImageMessage = 'The value must be an image.',
-        private string $notExactWidthMessage = 'The width of image "{attribute}" must be exactly {exactly, number} {exactly, plural, one{pixel} other{pixels}}.',
-        private string $notExactHeightMessage = 'The height of image "{attribute}" must be exactly {exactly, number} {exactly, plural, one{pixel} other{pixels}}.',
-        private string $tooSmallWidthMessage = 'The width of image "{attribute}" cannot be smaller than {limit, number} {limit, plural, one{pixel} other{pixels}}.',
-        private string $tooSmallHeightMessage = 'The height of image "{attribute}" cannot be smaller than {limit, number} {limit, plural, one{pixel} other{pixels}}.',
-        private string $tooLargeWidthMessage = 'The width of image "{attribute}" cannot be larger than {limit, number} {limit, plural, one{pixel} other{pixels}}.',
-        private string $tooLargeHeightMessage = 'The height of image "{attribute}" cannot be larger than {limit, number} {limit, plural, one{pixel} other{pixels}}.',
+        private string $notExactWidthMessage = 'The width must be exactly {exactly, number} {exactly, plural, one{pixel} other{pixels}}.',
+        private string $notExactHeightMessage = 'The height must be exactly {exactly, number} {exactly, plural, one{pixel} other{pixels}}.',
+        private string $tooSmallWidthMessage = 'The width cannot be smaller than {limit, number} {limit, plural, one{pixel} other{pixels}}.',
+        private string $tooSmallHeightMessage = 'The height cannot be smaller than {limit, number} {limit, plural, one{pixel} other{pixels}}.',
+        private string $tooLargeWidthMessage = 'The width cannot be larger than {limit, number} {limit, plural, one{pixel} other{pixels}}.',
+        private string $tooLargeHeightMessage = 'The height cannot be larger than {limit, number} {limit, plural, one{pixel} other{pixels}}.',
+        private string $invalidAspectRatioMessage = 'The aspect ratio must be {aspectRatioWidth, number}:{aspectRatioHeight, number} with margin {aspectRatioMargin, number}%.',
         private mixed $skipOnEmpty = null,
         private bool $skipOnError = false,
         private Closure|null $when = null,
     ) {
+        if ($this->width !== null && ($this->minWidth !== null || $this->maxWidth !== null)) {
+            throw new InvalidArgumentException('Exact width and min / max width can\'t be specified together.');
+        }
+
+        if ($this->height !== null && ($this->minHeight !== null || $this->maxHeight !== null)) {
+            throw new InvalidArgumentException('Exact width and min / max height can\'t be specified together.');
+        }
     }
 
     public function getWidth(): ?int
@@ -148,6 +173,11 @@ public function getMaxHeight(): ?int
         return $this->maxHeight;
     }
 
+    public function getAspectRatio(): ?ImageAspectRatio
+    {
+        return $this->aspectRatio;
+    }
+
     public function getNotImageMessage(): string
     {
         return $this->notImageMessage;
@@ -183,6 +213,11 @@ public function getTooLargeHeightMessage(): string
         return $this->tooLargeHeightMessage;
     }
 
+    public function getInvalidAspectRatioMessage(): string
+    {
+        return $this->invalidAspectRatioMessage;
+    }
+
     public function getName(): string
     {
         return 'image';
@@ -202,6 +237,9 @@ public function getOptions(): array
             'minHeight' => $this->minHeight,
             'maxWidth' => $this->maxWidth,
             'maxHeight' => $this->maxHeight,
+            'aspectRatioWidth' => $this->getAspectRatio()?->getWidth(),
+            'aspectRatioHeight' => $this->getAspectRatio()?->getHeight(),
+            'aspectRatioMargin' => $this->getAspectRatio()?->getMargin(),
             'notExactWidthMessage' => [
                 'template' => $this->notExactWidthMessage,
                 'parameters' => [
@@ -242,6 +280,14 @@ public function getOptions(): array
                 'template' => $this->notImageMessage,
                 'parameters' => [],
             ],
+            'invalidAspectRatioMessage' => [
+                'template' => $this->invalidAspectRatioMessage,
+                'parameters' => [
+                    'aspectRatioWidth' => $this->getAspectRatio()?->getWidth(),
+                    'aspectRatioHeight' => $this->getAspectRatio()?->getHeight(),
+                    'aspectRatioMargin' => $this->getAspectRatio()?->getMargin(),
+                ],
+            ],
             'skipOnEmpty' => $this->getSkipOnEmptyOption(),
             'skipOnError' => $this->skipOnError,
         ];

src/Rule/Image/ImageAspectRatio.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Validator\Rule\Image;
+
+/**
+ * {@link https://en.wikipedia.org/wiki/Aspect_ratio_(image)}
+ */
+final class ImageAspectRatio
+{
+    /**
+     * @param int $width Expected width part for aspect ratio. For example, for `4:3` aspect ratio, it will be `4`.
+     * @param int $height Expected height part for aspect ratio. For example, for `4:3` aspect ratio, it will be `3`.
+     * @param float $margin Expected margin for aspect ratio in percents. For example, with value `1` and `4:3` aspect
+     * ratio:
+     *
+     * - If the validated image has height of 600 pixels, the allowed width range is 794 - 806 pixels.
+     * - If the validated image has width of 800 pixels, the allowed height range is 596 - 604 pixels.
+     *
+     * Defaults to `0` meaning no margin is allowed. For example, image with size 800 x 600 pixels and aspect ratio
+     * expected to be `4:3` will meet this requirement.
+     */
+    public function __construct(
+        private int $width,
+        private int $height,
+        private float $margin = 0,
+    ) {
+    }
+
+    public function getWidth(): int
+    {
+        return $this->width;
+    }
+
+    public function getHeight(): int
+    {
+        return $this->height;
+    }
+
+    public function getMargin(): float
+    {
+        return $this->margin;
+    }
+}

src/Rule/Image/ImageHandler.php

@@ -91,6 +91,8 @@
             ]);
         }
 
+        $this->validateAspectRatio($width, $height, $rule, $context, $result);
+
         return $result;
     }
 
@@ -101,7 +103,8 @@
             || $rule->getMinHeight() !== null
             || $rule->getMinWidth() !== null
             || $rule->getMaxHeight() !== null
-            || $rule->getMaxWidth() !== null;
+            || $rule->getMaxWidth() !== null
+            || $rule->getAspectRatio() !== null;
     }
 
     private function getImageFilePath(mixed $value): ?string
@@ -138,4 +141,35 @@
         }
         return is_string($value) ? $value : null;
     }
+
+    private function validateAspectRatio(
+        int $validatedWidth,
+        int $validatedHeight,
+        Image $rule,
+        ValidationContext $context,
+        Result $result,
+    ): void {
+        if ($rule->getAspectRatio() === null) {
+            return;
+        }
+
+        $validatedAspectRatio = $validatedWidth / $validatedHeight;
+        $expectedAspectRatio = $rule->getAspectRatio()->getWidth() / $rule->getAspectRatio()->getHeight();
+        $absoluteMargin = $rule->getAspectRatio()->getMargin() / 100;
+
+        if (
+            ($validatedAspectRatio < $expectedAspectRatio - $absoluteMargin) ||
+            ($validatedAspectRatio > $expectedAspectRatio + $absoluteMargin)
+        ) {
+            $result->addError(
+                $rule->getInvalidAspectRatioMessage(),
+                [
+                    'attribute' => $context->getTranslatedAttribute(),
+                    'aspectRatioWidth' => $rule->getAspectRatio()->getWidth(),
+                    'aspectRatioHeight' => $rule->getAspectRatio()->getHeight(),
+                    'aspectRatioMargin' => $rule->getAspectRatio()->getMargin(),
+                ],
+            );
+        }
+    }
 }

src/RuleHandlerResolver/SimpleRuleHandlerContainer.php

@@ -41,8 +41,9 @@ final class SimpleRuleHandlerContainer implements RuleHandlerResolverInterface
      */
     public function __construct(
         /**
-         * @var array<string, RuleHandlerInterface> A storage of rule handlers' instances - a mapping where keys are
-         * strings (the rule handlers' class names by default) and values are corresponding rule handlers' instances.
+         * @var RuleHandlerInterface[] A storage of rule handlers' instances - a mapping where keys are strings (the
+         * rule handlers' class names by default) and values are corresponding rule handlers' instances.
+         * @psalm-var array<string, RuleHandlerInterface>
          */
         private array $instances = [],
     ) {