diff --git a/docs/book/v3/migration/v2-to-v3.md b/docs/book/v3/migration/v2-to-v3.md index 2e91465d..27d97ed6 100644 --- a/docs/book/v3/migration/v2-to-v3.md +++ b/docs/book/v3/migration/v2-to-v3.md @@ -152,6 +152,21 @@ The following methods have been removed: The constructor now only accepts an associative array of [documented options](../standard-filters.md#denylist). +#### `HtmlEntities` + +The following methods have been removed: + +- `getQuoteStyle` +- `setQuoteStyle` +- `getEncoding` +- `setEncoding` +- `getCharSet` +- `setCharSet` +- `getDoubleQuote` +- `setDoubleQuote` + +The constructor now only accepts an associative array of [documented options](../standard-filters.md#htmlentities). + #### `MonthSelect` The following methods have been removed: diff --git a/docs/book/v3/standard-filters.md b/docs/book/v3/standard-filters.md index 6948fbb2..2e08e040 100644 --- a/docs/book/v3/standard-filters.md +++ b/docs/book/v3/standard-filters.md @@ -635,24 +635,17 @@ entity equivalents when possible. The following options are supported for `Laminas\Filter\HtmlEntities`: - `quotestyle`: Equivalent to the PHP `htmlentities()` native function parameter - `quote_style`. This allows you to define what will be done with 'single' and + `flags`. This allows you to define what will be done with 'single' and "double" quotes. The following constants are accepted: `ENT_COMPAT`, `ENT_QUOTES`, and `ENT_NOQUOTES`, with the default being `ENT_COMPAT`. -- `charset`: Equivalent to the PHP `htmlentities()` native function parameter - `charset`. This defines the character set to be used in filtering. Unlike the +- `encoding`: Equivalent to the PHP `htmlentities()` native function parameter + `encoding`. This defines the character set to be used in filtering. Unlike the PHP native function, the default is 'UTF-8'. See the [PHP htmlentities manual](http://php.net/htmlentities) for a list of supported character sets. - - This option can also be set via the `$options` parameter as a Traversable - object or array. The option key will be accepted as either `charset` or - `encoding`. - `doublequote`: Equivalent to the PHP `htmlentities()` native function parameter `double_encode`. If set to `false`, existing HTML entities will not be encoded. The default is to convert everything (`true`). - This option must be set via the `$options` parameter or the - `setDoubleEncode()` method. - ### Basic Usage ```php @@ -696,43 +689,6 @@ print $filter->filter($input); The above example returns `A 'single' and "double"`. Notice that neither "double" or 'single' quotes are altered. -### Helper Methods - -To change or retrieve the `quotestyle` after instantiation, the two methods -`setQuoteStyle()` and `getQuoteStyle()` may be used respectively. -`setQuoteStyle()` accepts one parameter, `$quoteStyle`, which accepts one of the -constants `ENT_COMPAT`, `ENT_QUOTES`, or `ENT_NOQUOTES`. - -```php -$filter = new Laminas\Filter\HtmlEntities(); - -$filter->setQuoteStyle(ENT_QUOTES); -print $filter->getQuoteStyle(ENT_QUOTES); -``` - -To change or retrieve the `charset` after instantiation, the two methods -`setCharSet()` and `getCharSet()` may be used respectively. `setCharSet()` -accepts one parameter, `$charSet`. See the [PHP htmlentities manual -page](http://php.net/htmlentities) for a list of supported character sets. - -```php -$filter = new Laminas\Filter\HtmlEntities(); - -$filter->setQuoteStyle(ENT_QUOTES); -print $filter->getQuoteStyle(ENT_QUOTES); -``` - -To change or retrieve the `doublequote` option after instantiation, the two methods -`setDoubleQuote()` and `getDoubleQuote()` may be used respectively. `setDoubleQuote()` accepts one -boolean parameter, `$doubleQuote`. - -```php -$filter = new Laminas\Filter\HtmlEntities(); - -$filter->setQuoteStyle(ENT_QUOTES); -print $filter->getQuoteStyle(ENT_QUOTES); -``` - ## ToFloat `Laminas\Filter\ToFloat` allows you to transform a scalar value into a float. diff --git a/psalm-baseline.xml b/psalm-baseline.xml index e23a8698..8bb58d8d 100644 --- a/psalm-baseline.xml +++ b/psalm-baseline.xml @@ -179,45 +179,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -372,27 +333,6 @@ - - - - - - - - - - - - - - - - - - - - - diff --git a/src/HtmlEntities.php b/src/HtmlEntities.php index db764c74..cea2718c 100644 --- a/src/HtmlEntities.php +++ b/src/HtmlEntities.php @@ -4,15 +4,9 @@ namespace Laminas\Filter; -use Laminas\Stdlib\ArrayUtils; -use Traversable; - -use function array_shift; -use function func_get_args; use function function_exists; use function htmlentities; use function iconv; -use function is_array; use function is_scalar; use function strlen; @@ -20,181 +14,39 @@ /** * @psalm-type Options = array{ - * quote_style?: int, + * quotestyle?: int, * encoding?: string, - * double_quote?: bool, - * ... + * doublequote?: bool, * } - * @extends AbstractFilter + * @implements FilterInterface */ -final class HtmlEntities extends AbstractFilter +final class HtmlEntities implements FilterInterface { /** * Corresponds to the second htmlentities() argument - * - * @var int */ - protected $quoteStyle; + private readonly int $quoteStyle; /** * Corresponds to the third htmlentities() argument - * - * @var string */ - protected $encoding; + private readonly string $encoding; /** * Corresponds to the forth htmlentities() argument - * - * @var bool */ - protected $doubleQuote; + private readonly bool $doubleQuote; /** * Sets filter options * - * @param array|Traversable $options + * @param Options $options */ - public function __construct($options = []) + public function __construct(array $options = []) { - if ($options instanceof Traversable) { - $options = ArrayUtils::iteratorToArray($options); - } - if (! is_array($options)) { - $options = func_get_args(); - $temp['quotestyle'] = array_shift($options); - if (! empty($options)) { - $temp['charset'] = array_shift($options); - } - - $options = $temp; - } - - if (! isset($options['quotestyle'])) { - $options['quotestyle'] = ENT_QUOTES; - } - - if (! isset($options['encoding'])) { - $options['encoding'] = 'UTF-8'; - } - if (isset($options['charset'])) { - $options['encoding'] = $options['charset']; - } - - if (! isset($options['doublequote'])) { - $options['doublequote'] = true; - } - - $this->setQuoteStyle($options['quotestyle']); - $this->setEncoding($options['encoding']); - $this->setDoubleQuote($options['doublequote']); - } - - /** - * Returns the quoteStyle option - * - * @deprecated Since 2.40.0. This method will be removed in 3.0 without replacement - * - * @return int - */ - public function getQuoteStyle() - { - return $this->quoteStyle; - } - - /** - * Sets the quoteStyle option - * - * @deprecated Since 2.40.0. This method will be removed in 3.0. Set options during construction instead - * - * @param int $quoteStyle - * @return self Provides a fluent interface - */ - public function setQuoteStyle($quoteStyle) - { - $this->quoteStyle = $quoteStyle; - return $this; - } - - /** - * Get encoding - * - * @deprecated Since 2.40.0. This method will be removed in 3.0 without replacement - * - * @return string - */ - public function getEncoding() - { - return $this->encoding; - } - - /** - * Set encoding - * - * @deprecated Since 2.40.0. This method will be removed in 3.0. Set options during construction instead - * - * @param string $value - * @return self - */ - public function setEncoding($value) - { - $this->encoding = (string) $value; - return $this; - } - - /** - * Returns the charSet option - * - * @deprecated Since 2.40.0. This method will be removed in 3.0 without replacement - * - * Proxies to {@link getEncoding()} - * - * @return string - */ - public function getCharSet() - { - return $this->getEncoding(); - } - - /** - * Sets the charSet option - * - * @deprecated Since 2.40.0. This method will be removed in 3.0. Set options during construction instead - * - * Proxies to {@link setEncoding()} - * - * @param string $charSet - * @return self Provides a fluent interface - */ - public function setCharSet($charSet) - { - return $this->setEncoding($charSet); - } - - /** - * Returns the doubleQuote option - * - * @deprecated Since 2.40.0. This method will be removed in 3.0 without replacement - * - * @return bool - */ - public function getDoubleQuote() - { - return $this->doubleQuote; - } - - /** - * Sets the doubleQuote option - * - * @deprecated Since 2.40.0. This method will be removed in 3.0. Set options during construction instead - * - * @param bool $doubleQuote - * @return self Provides a fluent interface - */ - public function setDoubleQuote($doubleQuote) - { - $this->doubleQuote = (bool) $doubleQuote; - return $this; + $this->quoteStyle = $options['quotestyle'] ?? ENT_QUOTES; + $this->encoding = $options['encoding'] ?? 'UTF-8'; + $this->doubleQuote = $options['doublequote'] ?? true; } /** @@ -206,7 +58,6 @@ public function setDoubleQuote($doubleQuote) * If the value provided is non-scalar, the value will remain unfiltered * * @throws Exception\DomainException On encoding mismatches. - * @psalm-return ($value is scalar ? string : mixed) */ public function filter(mixed $value): mixed { @@ -215,18 +66,22 @@ public function filter(mixed $value): mixed } $value = (string) $value; - $filtered = htmlentities($value, $this->getQuoteStyle(), $this->getEncoding(), $this->getDoubleQuote()); + $filtered = htmlentities($value, $this->quoteStyle, $this->encoding, $this->doubleQuote); if (strlen($value) && ! strlen($filtered)) { if (! function_exists('iconv')) { throw new Exception\DomainException('Encoding mismatch has resulted in htmlentities errors'); } - $enc = $this->getEncoding(); - $value = iconv('', $this->getEncoding() . '//IGNORE', $value); - $filtered = htmlentities($value, $this->getQuoteStyle(), $enc, $this->getDoubleQuote()); + $value = iconv('', $this->encoding . '//IGNORE', $value); + $filtered = htmlentities($value, $this->quoteStyle, $this->encoding, $this->doubleQuote); if (! strlen($filtered)) { throw new Exception\DomainException('Encoding mismatch has resulted in htmlentities errors'); } } return $filtered; } + + public function __invoke(mixed $value): mixed + { + return $this->filter($value); + } } diff --git a/test/HtmlEntitiesTest.php b/test/HtmlEntitiesTest.php index 9ee28382..2776b715 100644 --- a/test/HtmlEntitiesTest.php +++ b/test/HtmlEntitiesTest.php @@ -4,7 +4,6 @@ namespace LaminasTest\Filter; -use ArrayObject; use Laminas\Filter\Exception\DomainException; use Laminas\Filter\HtmlEntities as HtmlEntitiesFilter; use PHPUnit\Framework\Attributes\DataProvider; @@ -21,16 +20,6 @@ class HtmlEntitiesTest extends TestCase { - private HtmlEntitiesFilter $filter; - - /** - * Creates a new Laminas\Filter\HtmlEntities object for each test method - */ - public function setUp(): void - { - $this->filter = new HtmlEntitiesFilter(); - } - /** * Ensures that the filter follows expected behavior */ @@ -44,93 +33,26 @@ public function testBasic(): void '"' => '"', '&' => '&', ]; - $filter = $this->filter; + $filter = new HtmlEntitiesFilter(); foreach ($valuesExpected as $input => $output) { self::assertSame($output, $filter($input)); } } - /** - * Ensures that getQuoteStyle() returns expected default value - */ - public function testGetQuoteStyle(): void - { - self::assertSame(ENT_QUOTES, $this->filter->getQuoteStyle()); - } - - /** - * Ensures that setQuoteStyle() follows expected behavior - */ - public function testSetQuoteStyle(): void - { - $this->filter->setQuoteStyle(ENT_QUOTES); - self::assertSame(ENT_QUOTES, $this->filter->getQuoteStyle()); - } - - /** - * Ensures that getCharSet() returns expected default value - */ - #[Group('Laminas-8715')] - public function testGetCharSet(): void - { - self::assertSame('UTF-8', $this->filter->getCharSet()); - } - - /** - * Ensures that setCharSet() follows expected behavior - */ - public function testSetCharSet(): void - { - $this->filter->setCharSet('UTF-8'); - self::assertSame('UTF-8', $this->filter->getCharSet()); - } - - /** - * Ensures that getDoubleQuote() returns expected default value - */ - public function testGetDoubleQuote(): void - { - self::assertSame(true, $this->filter->getDoubleQuote()); - } - - /** - * Ensures that setDoubleQuote() follows expected behavior - */ - public function testSetDoubleQuote(): void - { - $this->filter->setDoubleQuote(false); - self::assertSame(false, $this->filter->getDoubleQuote()); - } - /** * Ensure that fluent interfaces are supported */ #[Group('Laminas-3172')] public function testFluentInterface(): void { - $instance = $this->filter->setCharSet('UTF-8')->setQuoteStyle(ENT_QUOTES)->setDoubleQuote(false); + $instance = new HtmlEntitiesFilter([ + 'encoding' => 'UTF-8', + 'quotestyle' => ENT_QUOTES, + 'doublequote' => false, + ]); self::assertInstanceOf(HtmlEntitiesFilter::class, $instance); } - /** - * This test uses an ArrayObject in place of a Laminas\Config\Config instance; - * they two are interchangeable in this scenario, as HtmlEntitiesFilter is - * checking for arrays or Traversable instances. - */ - #[Group('Laminas-8995')] - public function testConfigObject(): void - { - $options = ['quotestyle' => 5, 'encoding' => 'ISO-8859-1']; - $config = new ArrayObject($options); - - $filter = new HtmlEntitiesFilter( - $config - ); - - self::assertSame('ISO-8859-1', $filter->getEncoding()); - self::assertSame(5, $filter->getQuoteStyle()); - } - /** * Ensures that when ENT_QUOTES is set, the filtered value has both 'single' and "double" quotes encoded */ @@ -140,8 +62,8 @@ public function testQuoteStyleQuotesEncodeBoth(): void $input = "A 'single' and " . '"double"'; $result = 'A 'single' and "double"'; - $this->filter->setQuoteStyle(ENT_QUOTES); - self::assertSame($result, $this->filter->filter($input)); + $filter = new HtmlEntitiesFilter(['quotestyle' => ENT_QUOTES]); + self::assertSame($result, $filter->filter($input)); } /** @@ -153,8 +75,8 @@ public function testQuoteStyleQuotesEncodeDouble(): void $input = "A 'single' and " . '"double"'; $result = "A 'single' and "double""; - $this->filter->setQuoteStyle(ENT_COMPAT); - self::assertSame($result, $this->filter->filter($input)); + $filter = new HtmlEntitiesFilter(['quotestyle' => ENT_COMPAT]); + self::assertSame($result, $filter->filter($input)); } /** @@ -166,32 +88,37 @@ public function testQuoteStyleQuotesEncodeNone(): void $input = "A 'single' and " . '"double"'; $result = "A 'single' and " . '"double"'; - $this->filter->setQuoteStyle(ENT_NOQUOTES); - self::assertSame($result, $this->filter->filter($input)); + $filter = new HtmlEntitiesFilter(['quotestyle' => ENT_NOQUOTES]); + self::assertSame($result, $filter->filter($input)); } #[Group('Laminas-11344')] public function testCorrectsForEncodingMismatch(): void { + $filter = new HtmlEntitiesFilter(); $string = file_get_contents(__DIR__ . '/_files/latin-1-text.txt'); - $result = $this->filter->filter($string); + self::assertNotFalse($string); + $result = $filter->filter($string); self::assertGreaterThan(0, strlen($result)); } #[Group('Laminas-11344')] public function testStripsUnknownCharactersWhenEncodingMismatchDetected(): void { + $filter = new HtmlEntitiesFilter(); $string = file_get_contents(__DIR__ . '/_files/latin-1-text.txt'); - $result = $this->filter->filter($string); + self::assertNotFalse($string); + $result = $filter->filter($string); self::assertStringContainsString('""', $result); } #[Group('Laminas-11344')] public function testRaisesExceptionIfEncodingMismatchDetectedAndFinalStringIsEmpty(): void { + $filter = new HtmlEntitiesFilter(); $string = file_get_contents(__DIR__ . '/_files/latin-1-dash-only.txt'); $this->expectException(DomainException::class); - $this->filter->filter($string); + $filter->filter($string); } /** @return list */ @@ -212,6 +139,7 @@ public static function returnUnfilteredDataProvider(): array #[DataProvider('returnUnfilteredDataProvider')] public function testReturnUnfiltered(mixed $input): void { - self::assertSame($input, $this->filter->filter($input)); + $filter = new HtmlEntitiesFilter(); + self::assertSame($input, $filter->filter($input)); } }