Skip to content

Commit

Permalink
Merge pull request #154 from gsteel/v3/abstract-unicode-refactor
Browse files Browse the repository at this point in the history
Refactor Lower Case and Upper Case Filters
  • Loading branch information
gsteel authored Aug 13, 2024
2 parents a4988a1 + 8fa87df commit 1cac41d
Show file tree
Hide file tree
Showing 17 changed files with 288 additions and 522 deletions.
9 changes: 3 additions & 6 deletions docs/book/v3/file.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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.
49 changes: 19 additions & 30 deletions docs/book/v3/standard-filters.md
Original file line number Diff line number Diff line change
Expand Up @@ -1203,13 +1203,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

Expand All @@ -1220,41 +1220,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

Expand All @@ -1265,17 +1255,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
Expand Down
51 changes: 0 additions & 51 deletions psalm-baseline.xml
Original file line number Diff line number Diff line change
Expand Up @@ -233,14 +233,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>
Expand Down Expand Up @@ -393,14 +385,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>
Expand Down Expand Up @@ -584,18 +568,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>
Expand Down Expand Up @@ -637,12 +609,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>
Expand Down Expand Up @@ -707,14 +673,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>
Expand Down Expand Up @@ -822,9 +780,6 @@
</PossiblyUnusedMethod>
</file>
<file src="test/File/LowerCaseTest.php">
<MissingParamType>
<code><![CDATA[$input]]></code>
</MissingParamType>
<PossiblyUnusedMethod>
<code><![CDATA[returnUnfilteredDataProvider]]></code>
</PossiblyUnusedMethod>
Expand Down Expand Up @@ -857,9 +812,6 @@
</PossiblyUnusedMethod>
</file>
<file src="test/File/UpperCaseTest.php">
<MissingParamType>
<code><![CDATA[$input]]></code>
</MissingParamType>
<PossiblyUnusedMethod>
<code><![CDATA[returnUnfilteredDataProvider]]></code>
</PossiblyUnusedMethod>
Expand Down Expand Up @@ -980,9 +932,6 @@
</PossiblyUnusedMethod>
</file>
<file src="test/StringToLowerTest.php">
<InvalidArgument>
<code><![CDATA[$e->getMessage()]]></code>
</InvalidArgument>
<PossiblyUnusedMethod>
<code><![CDATA[returnUnfilteredDataProvider]]></code>
</PossiblyUnusedMethod>
Expand Down
60 changes: 0 additions & 60 deletions src/AbstractUnicode.php

This file was deleted.

45 changes: 45 additions & 0 deletions src/EncodingOption.php
Original file line number Diff line number Diff line change
@@ -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);
}
}
65 changes: 65 additions & 0 deletions src/File/FilterFileContents.php
Original file line number Diff line number Diff line change
@@ -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,
));
}
}
}
Loading

0 comments on commit 1cac41d

Please sign in to comment.