Fix #591: Add File validator

Author: samdark

.github/workflows/bc.yml

@@ -31,3 +31,4 @@ jobs:
         ['ubuntu-latest']
       php: >-
         ['8.1']
+      install-development-dependencies: true

CHANGELOG.md

@@ -5,6 +5,7 @@
 - Enh #787: Explicitly import classes, functions, and constants in "use" section (@mspirkov)
 - Bug #793: Fix translations, broken link in contributing guide, incorrect imports and grammar in documentation (@evilkarter)
 - Chg #795: Update Polish translations (@rbrzezinski)
+- New #591: Add `File` validator (@samdark)
 - New #798: Add `SplFileInfo` value support to `Image` validator (@samdark)
 - Bug #798: Fix `Image` validator when unable to read from stream (@samdark)
 

docs/guide/en/README.md

@@ -14,6 +14,7 @@
   - [Compare](built-in-rules-compare.md)
   - [Composite](built-in-rules-composite.md)
   - [Each](built-in-rules-each.md)
+  - [File](built-in-rules-file.md)
   - [Nested](built-in-rules-nested.md)
   - [Required](built-in-rules-required.md)
   - [StopOnError](built-in-rules-stop-on-error.md)

docs/guide/en/built-in-rules-file.md

@@ -0,0 +1,91 @@
+# File
+
+`File` checks that a value is a file and can validate its extension, MIME type, and size.
+
+Supported values:
+
+- string file paths;
+- `SplFileInfo` instances;
+- [PSR-7] `UploadedFileInterface` instances.
+
+Use `Each` for multiple files:
+
+```php
+use Yiisoft\Validator\Rule\Each;
+use Yiisoft\Validator\Rule\File;
+
+$rules = [
+    'attachments' => new Each(new File(extensions: ['pdf', 'txt'])),
+];
+```
+
+For example, with a PSR-7 request:
+
+```php
+use Yiisoft\Validator\Rule\Each;
+use Yiisoft\Validator\Rule\File;
+use Yiisoft\Validator\Validator;
+
+$uploadedFiles = $request->getUploadedFiles()['attachments'] ?? [];
+
+$result = (new Validator())->validate(
+    ['attachments' => $uploadedFiles],
+    ['attachments' => new Each(new File(maxSize: 5_000_000))],
+);
+```
+
+If your application works with native PHP `$_FILES` data directly, convert it to supported values such as PSR-7 uploaded
+file objects before passing it to the validator.
+
+## Uploaded Files
+
+`File` handles PSR-7 upload error codes. `UPLOAD_ERR_NO_FILE` is treated as a missing value, so optional upload fields
+can use `skipOnEmpty`:
+
+```php
+use Yiisoft\Validator\Rule\File;
+
+$rule = new File(skipOnEmpty: true);
+```
+
+Other upload error codes fail validation with `uploadFailedMessage`.
+
+The rule does not prove that arbitrary string paths or `SplFileInfo` values came from PHP's HTTP upload mechanism. Do
+not pass user-submitted paths directly. Use PSR-7 uploaded file objects from a trusted request implementation, or perform
+[upload provenance checks] before validating filesystem paths.
+
+## MIME Types
+
+For filesystem-backed files, MIME type validation uses PHP's file information facilities through
+`mime_content_type()`. If the MIME type can't be determined, MIME validation fails.
+
+For pathless PSR-7 uploads backed only by an in-memory stream, `File` doesn't trust client-provided media type by
+default. If your application has already decided that the client metadata is acceptable for this field, enable it
+explicitly:
+
+```php
+use Yiisoft\Validator\Rule\File;
+
+$rule = new File(
+    mimeTypes: ['text/plain'],
+    trustClientMediaType: true,
+);
+```
+
+This option should be used with care because the client can send any media type value.
+
+## Size
+
+For filesystem-backed uploads, size checks use the actual file size on disk. For pathless streams, size checks use the
+PSR-7 upload size when available. If a size constraint is configured and the size can't be determined, validation fails.
+
+`size` is mutually exclusive with `minSize` and `maxSize`. When both `minSize` and `maxSize` are set, `minSize` must be
+less than or equal to `maxSize`.
+
+## Request Body Streams
+
+`File` doesn't validate generic request body streams such as data read from `php://input` for PUT requests. Convert such
+input to a supported value first, or write a custom rule that validates your stream format and storage flow.
+
+[PSR-7]: https://www.php-fig.org/psr/psr-7/
+[upload provenance checks]: https://www.php.net/manual/en/features.file-upload.post-method.php

docs/guide/en/built-in-rules.md

@@ -57,6 +57,7 @@ Here is a list of all available built-in rules, divided by category.
 
 ### File rules
 
+- [File](../../../src/Rule/File.php)
 - [Image](../../../src/Rule/Image/Image.php)
 
 ### Date rules
@@ -86,6 +87,7 @@ Some rules also have guides in addition to PHPDoc:
 - [Compare](built-in-rules-compare.md)
 - [Composite](built-in-rules-composite.md)
 - [Each](built-in-rules-each.md)
+- [File](built-in-rules-file.md)
 - [Nested](built-in-rules-nested.md)
 - [Required](built-in-rules-required.md)
 - [StopOnError](built-in-rules-stop-on-error.md)

messages/de/yii-validator.php

@@ -182,6 +182,8 @@
      * @see \Yiisoft\Validator\Rule\Date\DateTime
      * @see \Yiisoft\Validator\Rule\Date\Time
      */
+    '{Property} must be no early than {limit}.' => '{Property} darf nicht früher als {limit} sein.',
+    '{Property} must be no late than {limit}.' => '{Property} darf nicht später als {limit} sein.',
     '{Property} must be no earlier than {limit}.' => '{Property} darf nicht früher als {limit} sein.',
     '{Property} must be no later than {limit}.' => '{Property} darf nicht später als {limit} sein.',
 

messages/pt-BR/yii-validator.php

@@ -159,6 +159,8 @@
      * @see \Yiisoft\Validator\Rule\Date\DateTime
      * @see \Yiisoft\Validator\Rule\Date\Time
      */
+    '{Property} must be no early than {limit}.' => '{Property} não deve ser anterior a {limit}.',
+    '{Property} must be no late than {limit}.' => '{Property} não deve ser posterior a {limit}.',
     '{Property} must be no earlier than {limit}.' => '{Property} não deve ser anterior a {limit}.',
     '{Property} must be no later than {limit}.' => '{Property} não deve ser posterior a {limit}.',
 

messages/ru/yii-validator.php

@@ -167,6 +167,8 @@
      * @see \Yiisoft\Validator\Rule\Date\DateTime
      * @see \Yiisoft\Validator\Rule\Date\Time
      */
+    '{Property} must be no early than {limit}.' => '{Property} должно быть не ранее {limit}.',
+    '{Property} must be no late than {limit}.' => '{Property} должно быть не позднее {limit}.',
     '{Property} must be no earlier than {limit}.' => '{Property} должно быть не ранее {limit}.',
     '{Property} must be no later than {limit}.' => '{Property} должно быть не позднее {limit}.',
 

messages/uz/yii-validator.php

@@ -159,6 +159,8 @@
      * @see \Yiisoft\Validator\Rule\Date\DateTime
      * @see \Yiisoft\Validator\Rule\Date\Time
      */
+    '{Property} must be no early than {limit}.' => '{Property} {limit} dan oldin boʻlmasligi kerak.',
+    '{Property} must be no late than {limit}.' => '{Property} {limit} dan keyin boʻlmasligi kerak.',
     '{Property} must be no earlier than {limit}.' => '{Property} {limit} dan oldin boʻlmasligi kerak.',
     '{Property} must be no later than {limit}.' => '{Property} {limit} dan keyin boʻlmasligi kerak.',
 

src/Rule/Date/DateHandler.php

@@ -22,8 +22,8 @@ public function __construct(
         ?string $messageFormat = null,
         ?int $messageDateType = IntlDateFormatter::SHORT,
         string $incorrectInputMessage = '{Property} must be a date.',
-        string $tooEarlyMessage = '{Property} must be no earlier than {limit}.',
-        string $tooLateMessage = '{Property} must be no later than {limit}.',
+        string $tooEarlyMessage = '{Property} must be no early than {limit}.',
+        string $tooLateMessage = '{Property} must be no late than {limit}.',
     ) {
         parent::__construct(
             $dateType,