Merge Release 2.64.2 into 2.65.x

docs/book/index.md

@@ -1 +1,3 @@
-../../README.md
+<!-- markdownlint-disable -->
+../../README.md
+<!-- markdownlint-enable -->

docs/book/v2/validators/date-comparison.md

@@ -113,4 +113,4 @@ $input = DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2020-01-01 10:45:00
 $validator->isValid($input); // true
 ```
 
-In the above example, the validated value is considered as `2020-01-01 10:45:00` in _any_ timezone, and it is between the lower bound of `2020-01-01 10:00:00` and the upper bound of `2020-01-01 12:00:00`
+In the above example, the validated value is considered as `2020-01-01 10:45:00` in *any* timezone, and it is between the lower bound of `2020-01-01 10:00:00` and the upper bound of `2020-01-01 12:00:00`

docs/book/v2/validators/file/crc32.md

@@ -5,6 +5,7 @@ contents matches the supplied crc32 hash(es). It is subclassed from the [Hash
 validator](hash.md) to provide a validator that only supports the `crc32`
 algorithm.
 
+<!-- markdownlint-disable-next-line heading-increment -->
 > ### Requires the hash extension
 >
 > This validator requires the PHP [Hash extension](http://php.net/hash) with the

docs/book/v2/validators/file/hash.md

@@ -3,6 +3,7 @@
 `Laminas\Validator\File\Hash` allows you to validate if a given file's hashed
 contents matches the supplied hash(es) and algorithm(s).
 
+<!-- markdownlint-disable-next-line heading-increment -->
 > ### Requires the hash extension
 >
 > This validator requires the PHP [Hash extension](http://php.net/hash). A list

docs/book/v2/validators/file/intro.md

@@ -23,6 +23,7 @@ uploaded files, such as file size validation and CRC checking.
 - [UploadFile](upload-file.md)
 - [WordCount](word-count.md)
 
+<!-- markdownlint-disable-next-line heading-increment -->
 > ### Validation argument
 >
 > All of the File validators' `isValid()` methods support both a file path

docs/book/v2/validators/file/md5.md

@@ -5,6 +5,7 @@ contents matches the supplied md5 hash(es). It is subclassed from the
 [Hash validator](hash.md) to provide a validator that supports only the MD5
 algorithm.
 
+<!-- markdownlint-disable-next-line heading-increment -->
 > ### Requires the hash extension
 >
 > This validator requires the PHP [Hash extension](http://php.net/hash) PHP with

docs/book/v2/validators/file/mime-type.md

@@ -6,6 +6,7 @@
 This validator is inversely related to the
 [ExcludeMimeType validator](exclude-mime-type.md)
 
+<!-- markdownlint-disable-next-line heading-increment -->
 > ### Compatibility
 >
 > This component will use the `FileInfo` extension if it is available. If it's

docs/book/v2/validators/file/sha1.md

@@ -5,6 +5,7 @@ contents matches the supplied sha1 hash(es). It is subclassed from the
 [Hash validator](hash.md) to provide a validator that only supports the `sha1`
 algorithm.
 
+<!-- markdownlint-disable-next-line heading-increment -->
 > ### Requires the hash extension
 >
 > This validator requires the PHP [Hash extension](http://php.net/hash) with the

docs/book/v2/validators/number-comparison.md

@@ -6,7 +6,7 @@
 - Greater than a min value
 - Less than a max value
 
-By default, comparisons are inclusive. 
+By default, comparisons are inclusive.
 
 CAUTION: **Only supports number validation**
 `Laminas\Validator\NumberComparison` supports only the validation of numbers.
@@ -72,5 +72,5 @@ $validator = new Laminas\Validator\NumberComparison(['max' => 5]);
 $validator->isValid(99); // false
 ```
 
-You *must* provide one of the `min` or the `max` _(or both)_ options or an exception will be thrown.
+You *must* provide one of the `min` or the `max` *(or both)* options or an exception will be thrown.
 It doesn't make sense to compare the input to nothing for this validator.

psalm-baseline.xml

@@ -3377,6 +3377,7 @@
       <code><![CDATA[getHash]]></code>
       <code><![CDATA[getHash]]></code>
       <code><![CDATA[getHash]]></code>
+      <code><![CDATA[getOptions]]></code>
       <code><![CDATA[setHash]]></code>
     </DeprecatedMethod>
     <MixedArgument>
@@ -3393,6 +3394,7 @@
       <code><![CDATA[basicBehaviorDataProvider]]></code>
       <code><![CDATA[hashProvider]]></code>
       <code><![CDATA[invalidHashTypes]]></code>
+      <code><![CDATA[optionsOrderProvider]]></code>
     </PossiblyUnusedMethod>
   </file>
   <file src="test/File/ImageSizeTest.php">

src/File/Hash.php

@@ -69,6 +69,12 @@ public function __construct($options = null)
             $options['algorithm'] = func_get_arg(1);
         }
 
+        // The combination of parent and local logic requires us to have the "algorithm" key before the "hash" key
+        // in the array, or else the default algorithm will be used instead of the passed one.
+        if (isset($options['algorithm'])) {
+            $options = ['algorithm' => $options['algorithm']] + $options;
+        }
+
         parent::__construct($options);
     }
 

test/File/HashTest.php

@@ -4,6 +4,7 @@
 
 namespace LaminasTest\Validator\File;
 
+use Generator;
 use Laminas\Validator\Exception\InvalidArgumentException;
 use Laminas\Validator\File\Hash;
 use PHPUnit\Framework\Attributes\DataProvider;
@@ -15,6 +16,7 @@
 use function basename;
 use function current;
 use function is_array;
+use function key;
 use function sprintf;
 
 use const UPLOAD_ERR_NO_FILE;
@@ -313,4 +315,52 @@ public function testHashMustMatchWithTheAlgorithm(): void
 
         self::assertFalse($validator->isValid(__DIR__ . '/_files/crc32-int.pdf'));
     }
+
+    /**
+     * Provides options that should result in the same result irrespective of key order
+     *
+     * In order to act as a regression test for issue 398, this needs to include at least
+     * one couple of permutations that does not use the default algorithm (crc32).
+     *
+     * @return Generator<non-empty-string, array{
+     *     options: array<string, mixed>,
+     *     expectedHash: array<string, mixed>,
+     * }>
+     */
+    public static function optionsOrderProvider(): Generator
+    {
+        $algos  = ['crc32', 'md5', 'sha1'];
+        $hashes = [
+            'crc32' => ['6507f172bceb9ed0cc59246d41569c4d' => 'crc32'],
+            'md5'   => ['6507f172bceb9ed0cc59246d41569c4d' => 'md5'],
+            'sha1'  => ['6507f172bceb9ed0cc59246d41569c4d' => 'sha1'],
+        ];
+
+        foreach ($algos as $algo) {
+            $hash = key($hashes[$algo]);
+            yield $algo . ' algorithm first' => [
+                'options'      => [
+                    'algorithm' => $algo,
+                    'hash'      => $hash,
+                ],
+                'expectedHash' => $hashes[$algo],
+            ];
+            yield $algo . ' hash first'      => [
+                'options'      => [
+                    'hash'      => $hash,
+                    'algorithm' => $algo,
+                ],
+                'expectedHash' => $hashes[$algo],
+            ];
+        }
+    }
+
+    #[DataProvider('optionsOrderProvider')]
+    public function testOptionsKeyOrderIsIrrelevant(array $options, array $expectedHash): void
+    {
+        $validator     = new Hash($options);
+        $resultOptions = $validator->getOptions();
+        self::assertArrayHasKey('hash', $resultOptions);
+        self::assertSame($expectedHash, $resultOptions['hash']);
+    }
 }