Refactor Lower Case and Upper Case Filters

docs/book/v3/file.md

@@ -11,8 +11,7 @@ performing file operations such as renaming.
 
 ## Lowercase
 
-`Laminas\Filter\File\Lowercase` can be used to convert all file contents to
-lowercase.
+`Laminas\Filter\File\Lowercase` can be used to convert file contents to lowercase.
 
 ### Supported Options
 
@@ -314,8 +313,7 @@ foreach ($request->getUploadedFiles() as $uploadedFile) {
 
 ## Uppercase
 
-`Laminas\Filter\File\Uppercase` can be used to convert all file contents to
-uppercase.
+`Laminas\Filter\File\Uppercase` can be used to convert file contents to uppercase.
 
 ### Supported Options
 
@@ -337,5 +335,4 @@ $filter = new UpperCase();
 $filter->filter($files['my-upload']);
 ```
 
-See the documentation on the [`LowerCase`](#lowercase) filter, above, for more
-information.
+See the documentation on the [`LowerCase`](#lowercase) filter, above, for more information.

docs/book/v3/standard-filters.md

@@ -1221,13 +1221,13 @@ The above results in the string `MidCentral-PHP`.
 
 ## StringToLower
 
-This filter converts any input to lowercase.
+This filter converts string input to lowercase.
 
 ### Supported Options
 
 The following options are supported for `Laminas\Filter\StringToLower`:
 
-- `encoding`: This option can be used to set an encoding to use.
+- `encoding`: This option can be used to set the expected character encoding of the input.
 
 ### Basic Usage
 
@@ -1238,41 +1238,31 @@ print $filter->filter('SAMPLE');
 // returns "sample"
 ```
 
-### Handling alternate Encoding
+### Handling Alternate Encodings
 
-By default, `StringToLower` will only handle characters from the locale of your
-server; characters from other charsets will be ignored. If you have the mbstring
-extension, however, you can use the filter with other encodings.  Pass the
-desired encoding when initiating the `StringToLower` filter, or use the
-`setEncoding()` method to change it.
+By default, `StringToLower` will only handle characters from the locale of your server; characters from other charsets will be ignored.
+To correctly filter input in encodings other than the default detected encoding for your environment, pass the
+desired encoding when initiating the `StringToLower` filter.
 
 ```php
-// using UTF-8
-$filter = new Laminas\Filter\StringToLower('UTF-8');
-
-// or give an array which can be useful when using a configuration
-$filter = new Laminas\Filter\StringToLower(['encoding' => 'UTF-8']);
-
-// or do this afterwards
-$filter->setEncoding('ISO-8859-1');
+$filter = new Laminas\Filter\StringToLower([
+    'encoding' => 'UTF-8',
+]);
 ```
 
 > ### Setting invalid Encodings
 >
-> Be aware that you will get an exception when:
->
-> - you attempt to set an encoding and the mbstring extension is unavailable; or
-> - you attempt to set an encoding unsupported by the mbstring extension.
+> Be aware that you will get an exception when you provide an encoding that is not supported by the `mbstring` extension.
 
 ## StringToUpper
 
-This filter converts any input to UPPERCASE.
+This filter converts string input to UPPERCASE.
 
 ### Supported Options
 
 The following options are supported for `Laminas\Filter\StringToUpper`:
 
-- `encoding`: This option can be used to set the encoding to use.
+- `encoding`: This option can be used to set the expected character encoding of the input.
 
 ### Basic Usage
 
@@ -1283,17 +1273,16 @@ print $filter->filter('Sample');
 // returns "SAMPLE"
 ```
 
-### Different encoded Strings
+### Handling Alternate Encodings
 
-Like the `StringToLower` filter, this filter will only handle characters
-supported by your server locale, unless you have the mbstring extension enabled.
-Using different character sets works the same as with `StringToLower`.
+By default, `StringToUpper` will only handle characters from the locale of your server; characters from other charsets will be ignored.
+To correctly filter input in encodings other than the default detected encoding for your environment, pass the
+desired encoding when initiating the `StringToUpper` filter.
 
 ```php
-$filter = new Laminas\Filter\StringToUpper(['encoding' => 'UTF-8']);
-
-// or do this afterwards
-$filter->setEncoding('ISO-8859-1');
+$filter = new Laminas\Filter\StringToUpper([
+    'encoding' => 'UTF-8',
+]);
 ```
 
 ## StringTrim

psalm-baseline.xml

@@ -283,14 +283,6 @@
       <code><![CDATA[(bool) $strict]]></code>
     </RedundantCastGivenDocblockType>
   </file>
-  <file src="src/File/LowerCase.php">
-    <MixedAssignment>
-      <code><![CDATA[$value]]></code>
-    </MixedAssignment>
-    <PossiblyUndefinedVariable>
-      <code><![CDATA[$uploadData]]></code>
-    </PossiblyUndefinedVariable>
-  </file>
   <file src="src/File/Rename.php">
     <DocblockTypeContradiction>
       <code><![CDATA[is_array($options)]]></code>
@@ -443,14 +435,6 @@
       <code><![CDATA[(bool) $flag]]></code>
     </RedundantCastGivenDocblockType>
   </file>
-  <file src="src/File/UpperCase.php">
-    <MixedAssignment>
-      <code><![CDATA[$value]]></code>
-    </MixedAssignment>
-    <PossiblyUndefinedVariable>
-      <code><![CDATA[$uploadData]]></code>
-    </PossiblyUndefinedVariable>
-  </file>
   <file src="src/FilterChain.php">
     <MixedPropertyTypeCoercion>
       <code><![CDATA[new PriorityQueue()]]></code>
@@ -634,18 +618,6 @@
       <code><![CDATA[is_string($suffix)]]></code>
     </DocblockTypeContradiction>
   </file>
-  <file src="src/StringToLower.php">
-    <PossiblyInvalidArgument>
-      <code><![CDATA[$encodingOrOptions]]></code>
-      <code><![CDATA[$encodingOrOptions]]></code>
-    </PossiblyInvalidArgument>
-  </file>
-  <file src="src/StringToUpper.php">
-    <PossiblyInvalidArgument>
-      <code><![CDATA[$encodingOrOptions]]></code>
-      <code><![CDATA[$encodingOrOptions]]></code>
-    </PossiblyInvalidArgument>
-  </file>
   <file src="src/StringTrim.php">
     <PossiblyUndefinedArrayOffset>
       <code><![CDATA[$this->options['charlist']]]></code>
@@ -687,12 +659,6 @@
       <code><![CDATA[is_int($value)]]></code>
     </RedundantConditionGivenDocblockType>
   </file>
-  <file src="src/UpperCaseWords.php">
-    <PossiblyInvalidArgument>
-      <code><![CDATA[$encodingOrOptions]]></code>
-      <code><![CDATA[$encodingOrOptions]]></code>
-    </PossiblyInvalidArgument>
-  </file>
   <file src="src/Word/AbstractSeparator.php">
     <PossiblyInvalidArgument>
       <code><![CDATA[$separator]]></code>
@@ -757,14 +723,6 @@
       <code><![CDATA[is_array($value) ? array_map($lowerCaseFirst, $value) : $lowerCaseFirst($value)]]></code>
     </MixedReturnStatement>
   </file>
-  <file src="test/AbstractUnicodeTest.php">
-    <MissingTemplateParam>
-      <code><![CDATA[class extends AbstractUnicode {]]></code>
-    </MissingTemplateParam>
-    <PossiblyUnusedMethod>
-      <code><![CDATA[encodingProvider]]></code>
-    </PossiblyUnusedMethod>
-  </file>
   <file src="test/AllowListTest.php">
     <PossiblyUnusedMethod>
       <code><![CDATA[defaultTestProvider]]></code>
@@ -870,9 +828,6 @@
     </PossiblyUnusedMethod>
   </file>
   <file src="test/File/LowerCaseTest.php">
-    <MissingParamType>
-      <code><![CDATA[$input]]></code>
-    </MissingParamType>
     <PossiblyUnusedMethod>
       <code><![CDATA[returnUnfilteredDataProvider]]></code>
     </PossiblyUnusedMethod>
@@ -905,9 +860,6 @@
     </PossiblyUnusedMethod>
   </file>
   <file src="test/File/UpperCaseTest.php">
-    <MissingParamType>
-      <code><![CDATA[$input]]></code>
-    </MissingParamType>
     <PossiblyUnusedMethod>
       <code><![CDATA[returnUnfilteredDataProvider]]></code>
     </PossiblyUnusedMethod>
@@ -1028,9 +980,6 @@
     </PossiblyUnusedMethod>
   </file>
   <file src="test/StringToLowerTest.php">
-    <InvalidArgument>
-      <code><![CDATA[$e->getMessage()]]></code>
-    </InvalidArgument>
     <PossiblyUnusedMethod>
       <code><![CDATA[returnUnfilteredDataProvider]]></code>
     </PossiblyUnusedMethod>

src/EncodingOption.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Filter;
+
+use Laminas\Filter\Exception\InvalidArgumentException;
+
+use function array_map;
+use function in_array;
+use function mb_internal_encoding;
+use function mb_list_encodings;
+use function sprintf;
+use function strtolower;
+
+/** @internal */
+final class EncodingOption
+{
+    /**
+     * Asserts the given string is an encoding supported by ext-mbstring, returning the encoding when valid
+     */
+    public static function assert(string $encoding): string
+    {
+        $encoding  = strtolower($encoding);
+        $available = array_map('strtolower', mb_list_encodings());
+        if (! in_array($encoding, $available, true)) {
+            throw new InvalidArgumentException(sprintf(
+                "Encoding '%s' is not supported by the mbstring extension",
+                $encoding,
+            ));
+        }
+
+        return $encoding;
+    }
+
+    /**
+     * Asserts $encoding is a supported encoding with a fallback when encoding is unspecified
+     */
+    public static function assertWithDefault(string|null $encoding): string
+    {
+        $encoding = $encoding ?? mb_internal_encoding();
+
+        return self::assert($encoding);
+    }
+}

src/File/FilterFileContents.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Filter\File;
+
+use Laminas\Filter\Exception\InvalidArgumentException;
+use Laminas\Filter\Exception\RuntimeException;
+use Laminas\Filter\FilterInterface;
+
+use function file_exists;
+use function file_get_contents;
+use function file_put_contents;
+use function is_writable;
+use function sprintf;
+
+/** @internal */
+final class FilterFileContents
+{
+    /** @param FilterInterface<string> $filter */
+    public function __construct(private readonly FilterInterface $filter)
+    {
+    }
+
+    /**
+     * @throws InvalidArgumentException If no file exists.
+     * @throws RuntimeException If the file cannot be written to or read from.
+     */
+    public function __invoke(string $filePath): void
+    {
+        if (! file_exists($filePath)) {
+            throw new InvalidArgumentException(sprintf(
+                'File %s not found',
+                $filePath,
+            ));
+        }
+
+        if (! is_writable($filePath)) {
+            throw new RuntimeException(sprintf(
+                'File "%s" is not writable',
+                $filePath
+            ));
+        }
+
+        $content = file_get_contents($filePath);
+        if ($content === false) {
+            throw new RuntimeException(sprintf(
+                'The contents of "%s" could not be read',
+                $filePath,
+            ));
+        }
+
+        $result = file_put_contents(
+            $filePath,
+            $this->filter->filter($content),
+        );
+
+        if ($result === false) {
+            throw new RuntimeException(sprintf(
+                'The file "%s" could not be written to',
+                $filePath,
+            ));
+        }
+    }
+}