Add Image validation rule

.github/workflows/build.yml

@@ -26,7 +26,7 @@ jobs:
   phpunit:
     uses: yiisoft/actions/.github/workflows/phpunit.yml@master
     with:
-      extensions: intl
+      extensions: intl,fileinfo
       coverage: xdebug
       os: >-
         ['ubuntu-latest', 'windows-latest']

CHANGELOG.md

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

composer-require-checker.json

@@ -15,6 +15,7 @@
         "Reflection",
         "SPL",
         "standard",
+        "fileinfo",
         "intl"
     ],
     "scan-files": []

composer.json

@@ -30,11 +30,12 @@
         "php": "^8.0",
         "ext-mbstring": "*",
         "psr/container": "^1.0|^2.0",
+        "psr/http-message": "^1.0|^2.0",
         "yiisoft/arrays": "^2.1|^3.0",
-        "yiisoft/translator": "^2.1|^3.0",
         "yiisoft/friendly-exception": "^1.0",
         "yiisoft/network-utilities": "^1.0",
-        "yiisoft/strings": "^2.1"
+        "yiisoft/strings": "^2.1",
+        "yiisoft/translator": "^2.1|^3.0"
     },
     "require-dev": {
         "jetbrains/phpstorm-attributes": "^1.0",
@@ -52,6 +53,7 @@
     },
     "suggest": {
         "ext-intl": "Allows using IDN validation for emails",
+        "ext-fileinfo": "To use image rule",
         "yiisoft/di": "To create rule handlers via Yii DI"
     },
     "autoload": {

src/Rule/Image.php

@@ -0,0 +1,182 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Validator\Rule;
+
+use Attribute;
+use Closure;
+use Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait;
+use Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait;
+use Yiisoft\Validator\Rule\Trait\WhenTrait;
+use Yiisoft\Validator\RuleWithOptionsInterface;
+use Yiisoft\Validator\SkipOnEmptyInterface;
+use Yiisoft\Validator\SkipOnErrorInterface;
+use Yiisoft\Validator\WhenInterface;
+
+/**
+ * @see ImageHandler
+ *
+ * @psalm-import-type SkipOnEmptyValue from SkipOnEmptyInterface
+ * @psalm-import-type WhenType from WhenInterface
+ */
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
+final class Image implements RuleWithOptionsInterface, SkipOnErrorInterface, WhenInterface, SkipOnEmptyInterface
+{
+    use SkipOnEmptyTrait;
+    use SkipOnErrorTrait;
+    use WhenTrait;
+
+    /**
+     * @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.
+     * See {@see SkipOnErrorInterface}.
+     * @param Closure|null $when A callable to define a condition for applying the rule. See {@see WhenInterface}.
+     *
+     * @psalm-param SkipOnEmptyValue $skipOnEmpty
+     * @psalm-param WhenType $when
+     */
+    public function __construct(
+        private ?int $width = null,
+        private ?int $height = null,
+        private ?int $minWidth = null,
+        private ?int $minHeight = null,
+        private ?int $maxWidth = null,
+        private ?int $maxHeight = null,
+        private string $notImageMessage = 'The value must be an image.',
+        private string $notExactlyWidthMessage = 'The width of image "{attribute}" must be exactly {exactly, number} {exactly, plural, one{pixel} other{pixels}}.',
+        private string $notExactlyHeightMessage = '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 mixed $skipOnEmpty = null,
+        private bool $skipOnError = false,
+        private Closure|null $when = null,
+    ) {
+    }
+
+    public function getWidth(): ?int
+    {
+        return $this->width;
+    }
+
+    public function getHeight(): ?int
+    {
+        return $this->height;
+    }
+
+    public function getMinWidth(): ?int
+    {
+        return $this->minWidth;
+    }
+
+    public function getMinHeight(): ?int
+    {
+        return $this->minHeight;
+    }
+
+    public function getMaxWidth(): ?int
+    {
+        return $this->maxWidth;
+    }
+
+    public function getMaxHeight(): ?int
+    {
+        return $this->maxHeight;
+    }
+
+    public function getNotImageMessage(): string
+    {
+        return $this->notImageMessage;
+    }
+
+    public function getNotExactlyWidthMessage(): string
+    {
+        return $this->notExactlyWidthMessage;
+    }
+
+    public function getNotExactlyHeightMessage(): string
+    {
+        return $this->notExactlyHeightMessage;
+    }
+
+    public function getTooSmallWidthMessage(): string
+    {
+        return $this->tooSmallWidthMessage;
+    }
+
+    public function getTooSmallHeightMessage(): string
+    {
+        return $this->tooSmallHeightMessage;
+    }
+
+    public function getTooLargeWidthMessage(): string
+    {
+        return $this->tooLargeWidthMessage;
+    }
+
+    public function getTooLargeHeightMessage(): string
+    {
+        return $this->tooLargeHeightMessage;
+    }
+
+    public function getName(): string
+    {
+        return 'image';
+    }
+
+    public function getHandler(): string
+    {
+        return ImageHandler::class;
+    }
+
+    public function getOptions(): array
+    {
+        return [
+            'notExactlyWidthMessage' => [
+                'template' => $this->notExactlyWidthMessage,
+                'parameters' => [
+                    'exactly' => $this->width,
+                ],
+            ],
+            'notExactlyHeightMessage' => [
+                'template' => $this->notExactlyHeightMessage,
+                'parameters' => [
+                    'exactly' => $this->height,
+                ],
+            ],
+            'tooSmallWidthMessage' => [
+                'template' => $this->tooSmallWidthMessage,
+                'parameters' => [
+                    'limit' => $this->minWidth,
+                ],
+            ],
+            'tooSmallHeightMessage' => [
+                'template' => $this->tooSmallHeightMessage,
+                'parameters' => [
+                    'limit' => $this->minHeight,
+                ],
+            ],
+            'tooLargeWidthMessage' => [
+                'template' => $this->tooLargeWidthMessage,
+                'parameters' => [
+                    'limit' => $this->maxWidth,
+                ],
+            ],
+            'tooLargeHeightMessage' => [
+                'template' => $this->tooLargeHeightMessage,
+                'parameters' => [
+                    'limit' => $this->maxHeight,
+                ],
+            ],
+            'notImageMessage' => [
+                'template' => $this->notImageMessage,
+                'parameters' => [],
+            ],
+            'skipOnEmpty' => $this->getSkipOnEmptyOption(),
+            'skipOnError' => $this->skipOnError,
+        ];
+    }
+}

src/Rule/ImageHandler.php

@@ -0,0 +1,112 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Validator\Rule;
+
+use Psr\Http\Message\UploadedFileInterface;
+use Yiisoft\Validator\Exception\UnexpectedRuleException;
+use Yiisoft\Validator\Result;
+use Yiisoft\Validator\RuleHandlerInterface;
+use Yiisoft\Validator\ValidationContext;
+
+final class ImageHandler implements RuleHandlerInterface
+{
+    public function validate(mixed $value, object $rule, ValidationContext $context): Result
+    {
+        if (!$rule instanceof Image) {
+            throw new UnexpectedRuleException(Image::class, $rule);
+        }
+
+        $result = new Result();
+
+        $info = $this->getImageInfo($value);
+        if (empty($info)) {
+            $result->addError($rule->getNotImageMessage(), ['attribute' => $context->getTranslatedAttribute()]);
+            return $result;
+        }
+
+        [$width, $height] = $info;
+
+        if ($rule->getWidth() !== null && $width !== $rule->getWidth()) {
+            $result->addError($rule->getNotExactlyWidthMessage(), [
+                'attribute' => $context->getTranslatedAttribute(),
+                'exactly' => $rule->getWidth(),
+            ]);
+        }
+        if ($rule->getHeight() !== null && $height !== $rule->getHeight()) {
+            $result->addError($rule->getNotExactlyHeightMessage(), [
+                'attribute' => $context->getTranslatedAttribute(),
+                'exactly' => $rule->getHeight(),
+            ]);
+        }
+        if ($rule->getMinWidth() !== null && $width < $rule->getMinWidth()) {
+            $result->addError($rule->getTooSmallWidthMessage(), [
+                'attribute' => $context->getTranslatedAttribute(),
+                'limit' => $rule->getMinWidth(),
+            ]);
+        }
+        if ($rule->getMinHeight() !== null && $height < $rule->getMinHeight()) {
+            $result->addError($rule->getTooSmallHeightMessage(), [
+                'attribute' => $context->getTranslatedAttribute(),
+                'limit' => $rule->getMinHeight(),
+            ]);
+        }
+        if ($rule->getMaxWidth() !== null && $width > $rule->getMaxWidth()) {
+            $result->addError($rule->getTooLargeWidthMessage(), [
+                'attribute' => $context->getTranslatedAttribute(),
+                'limit' => $rule->getMaxWidth(),
+            ]);
+        }
+        if ($rule->getMaxHeight() !== null && $height > $rule->getMaxHeight()) {
+            $result->addError($rule->getTooLargeHeightMessage(), [
+                'attribute' => $context->getTranslatedAttribute(),
+                'limit' => $rule->getMaxHeight(),
+            ]);
+        }
+
+        return $result;
+    }
+
+    /**
+     * @psalm-return array{0:int,1:int}&array
+     */
+    private function getImageInfo(mixed $value): ?array
+    {
+        $filePath = $this->getFilePath($value);
+        if (empty($filePath)) {
+            return null;
+        }
+
+        if (!$this->isImageFile($filePath)) {
+            return null;
+        }
+
+        /**
+         * @psalm-var (array{0:int,1:int}&array)|null $info Need for PHP 8.0 only
+         */
+        $info = getimagesize($filePath);
+        return is_array($info) ? $info : null;
+    }
+
+    /**
+     * From PHP documentation: do not use `getimagesize()` to check that a given file is a valid image. Use
+     * a purpose-built solution such as the `Fileinfo` extension instead.
+     *
+     * @link https://www.php.net/manual/function.getimagesize.php
+     * @link https://www.php.net/manual/function.mime-content-type.php
+     */
+    private function isImageFile(string $filePath): bool
+    {
+        $mimeType = @mime_content_type($filePath);
+        return $mimeType !== false && str_starts_with($mimeType, 'image/');
+    }
+
+    private function getFilePath(mixed $value): ?string
+    {
+        if ($value instanceof UploadedFileInterface) {
+            $value = $value->getError() === UPLOAD_ERR_OK ? $value->getStream()->getMetadata('uri') : null;
+        }
+        return is_string($value) ? $value : null;
+    }
+}

tests/Rule/Base/RuleTestCase.php

@@ -15,7 +15,7 @@ abstract public function dataValidationPassed(): array;
     /**
      * @dataProvider dataValidationPassed
      */
-    public function testValidationPassed(mixed $data, ?array $rules = null): void
+    public function testValidationPassed(mixed $data, array|RuleInterface|null $rules = null): void
     {
         $result = (new Validator())->validate($data, $rules);
 

tests/Rule/CompareTest.php

@@ -543,7 +543,7 @@ public function hasAttribute(string $attribute): bool
      * @dataProvider dataValidationPassed
      * @dataProvider dataValidationPassedWithDifferentTypes
      */
-    public function testValidationPassed(mixed $data, ?array $rules = null): void
+    public function testValidationPassed(mixed $data, array|RuleInterface|null $rules = null): void
     {
         parent::testValidationPassed($data, $rules);
     }