Merge pull request #132 from gsteel/deprecate-uri-normalize

Deprecate the `UriNormalize` filter

docs/book/v2/migration/preparing-for-v3.md

@@ -0,0 +1,55 @@
+# Preparing for Version 3
+
+Version 3 will introduce a number of backwards incompatible changes. This document is intended to help you prepare for these changes.
+
+## Removed Features
+
+### Inheritance Changes
+
+Most filters will be closed to inheritance in v3 by employing the `final` keyword.
+To prepare for this change, search for classes in your codebase that extend from any of the concrete filters and either re-implement them completely, or consider refactoring them to use composition instead of inheritance.
+
+If you have extended an existing filter for a use-case that is not handled by this library, also consider sending a patch if you think that the library could benefit from your changes.
+
+### Compression Filter Adapter Removal
+
+The Lzf, Snappy and Rar compression adapters will be removed in version 3.0.
+If you are currently using any of these compression formats with laminas-filter, you will need to either use an alternative format such as Zip, Tar, Gz or Bz2, or, write a custom adapter to support your desired compression format.
+
+### Encryption & Decryption Filter Removal
+
+These filters have become outdated and will be removed in version 3.0 of this library. We recommend that you make use of a maintained encryption library and [write your own filters](../writing-filters.md) if you need to encrypt or decrypt content using the `FilterInterface` contract.
+
+- `Laminas\Filter\File\Decrypt`
+- `Laminas\Filter\File\Encrypt`
+- `Laminas\Filter\Decrypt`
+- `Laminas\Filter\Encrypt`
+
+### Static Filter Removal
+
+`Laminas\Filter\StaticFilter` will be removed without replacement in v3. Most filters are "new-able" so similar behaviour can be accomplished with:
+
+```php
+$filtered = (new \Laminas\Filter\HtmlEntities())('Nuts & Bolts');
+```
+
+For filters requiring more complex construction, we encourage you to make use of dependency injection and compose the filter itself, or via the `FilterPluginManager`, for example:
+
+```php
+$pluginManager = $container->get(\Laminas\Filter\FilterPluginManager::class);
+$filter = $pluginManager->get(\Laminas\Filter\HtmlEntities::class);
+$filtered = $filter->filter('A String');
+```
+
+### Whitelist & Blacklist Filter Removal
+
+The deprecated filters `Whitelist` & `Blacklist` will be removed in v3 for their more favourably named counterparts `AllowList` and `DenyList`
+
+- `Laminas\Filter\Whitelist` has been replaced by [`Laminas\Filter\AllowList`](../standard-filters.md#allowlist)
+- `Laminas\Filter\Blacklist` has been replaced by [`Laminas\Filter\DenyList`](../standard-filters.md#denylist)
+
+### UriNormalize Filter Removal
+
+The [UriNormalize](../standard-filters.md#urinormalize) filter will be removed in version 3, primarily because its functionality is provided by `laminas-uri` which is no longer maintained.
+
+There is not a direct replacement, but, if you were using the filter to normalize URL schemes, this functionality has been preserved in a new filter [ForceUriScheme](../standard-filters.md#forceurischeme).

docs/book/v2/standard-filters.md

@@ -1931,6 +1931,9 @@ as the result.
 
 ## UriNormalize
 
+CAUTION: **Deprecated**
+This filter is deprecated since version 2.36.0 and will be removed in version 3.0. The ability to force the scheme has been moved to the [ForceUriScheme filter](#forceurischeme).
+
 This filter sets the scheme on a URI if the scheme is missing.
 
 ### Supported Options

mkdocs.yml

@@ -12,6 +12,8 @@ nav:
         - 'String Inflection': v2/inflector.md
         - 'Static Filter': v2/static-filter.md
         - 'Writing Filters': v2/writing-filters.md
+      - Migration:
+        - 'Preparing for v3': v2/migration/preparing-for-v3.md
 site_name: laminas-filter
 site_description: "Programmatically filter and normalize data and files."
 repo_url: 'https://github.com/laminas/laminas-filter'

psalm-baseline.xml

@@ -1027,6 +1027,12 @@
       <code><![CDATA[File\Encrypt::class]]></code>
       <code><![CDATA[File\Encrypt::class]]></code>
       <code><![CDATA[File\Encrypt::class]]></code>
+      <code><![CDATA[UriNormalize::class]]></code>
+      <code><![CDATA[UriNormalize::class]]></code>
+      <code><![CDATA[UriNormalize::class]]></code>
+      <code><![CDATA[UriNormalize::class]]></code>
+      <code><![CDATA[UriNormalize::class]]></code>
+      <code><![CDATA[UriNormalize::class]]></code>
       <code><![CDATA[Whitelist::class]]></code>
     </DeprecatedClass>
     <DuplicateArrayKey>
@@ -1895,6 +1901,11 @@
     </PossiblyUnusedMethod>
   </file>
   <file src="test/UriNormalizeTest.php">
+    <DeprecatedClass>
+      <code><![CDATA[new UriNormalize()]]></code>
+      <code><![CDATA[new UriNormalize()]]></code>
+      <code><![CDATA[new UriNormalize(['enforcedScheme' => $scheme])]]></code>
+    </DeprecatedClass>
     <PossiblyUnusedMethod>
       <code><![CDATA[abnormalUriProvider]]></code>
       <code><![CDATA[enforcedSchemeTestcaseProvider]]></code>

src/UriNormalize.php

@@ -16,6 +16,9 @@
 use function str_contains;
 
 /**
+ * @deprecated This filter will be removed in version 3.0
+ *             The {@link ForceUriScheme} filter partially replicates functionality here.
+ *
  * @psalm-type Options = array{
  *     default_scheme?: string,
  *     enforced_scheme?: string,

test/UriNormalizeTest.php

@@ -9,6 +9,11 @@
 use PHPUnit\Framework\TestCase;
 use stdClass;
 
+/**
+ * @deprecated
+ *
+ * @todo Remove this test in v3.0
+ */
 class UriNormalizeTest extends TestCase
 {
     #[DataProvider('abnormalUriProvider')]