Merge pull request #106 from gsteel/add-migration-guide

Initial Migration Guide for v3

docs/book/v3/file.md

@@ -9,50 +9,6 @@ performing file operations such as renaming.
 > *or* a `$_FILES` array as the supplied argument. When a `$_FILES` array is
 > passed in, the `tmp_name` is used for the file path.
 
-## Encrypt and Decrypt
-
-These filters allow encrypting and decrypting file contents, and are derived
-from the `Laminas\Filter\Encrypt` and `Laminas\Filter\Decrypt` filters. Only file reading and
-writing operations are performed by the filer; encryption and decryption operations
-are performed by the parent classes.
-
-Usage:
-
-```php
-use Laminas\Filter\File\Encrypt as EncryptFileFilter;
-use Laminas\Http\PhpEnvironment\Request;
-
-$request = new Request();
-$files   = $request->getFiles();
-// i.e. $files['my-upload']['tmp_name'] === '/tmp/php5Wx0aJ'
-
-$filter = new EncryptFileFilter([
-    'adapter' => 'BlockCipher',
-    'key' => '--our-super-secret-key--',
-]);
-$filter->filter($files['my-upload']);
-```
-
-In the above example, we pass options to our constructor in order to configure
-the filter. We could instead use use setter methods to inject these options:
-
-```php
-use Laminas\Filter\File\Encrypt as EncryptFileFilter;
-use Laminas\Http\PhpEnvironment\Request;
-
-$request = new Request();
-$files   = $request->getFiles();
-// i.e. $files['my-upload']['tmp_name'] === '/tmp/php5Wx0aJ'
-
-$filter = new EncryptFileFilter();
-$filter->setAdapter('BlockCipher');
-$filter->setKey('--our-super-secret-key--');
-$filter->filter($files['my-upload']);
-```
-
-Check the [Encrypt and Decrypt filter documentation](/laminas-filter/standard-filters/#encrypt-and-decrypt)
-for more information about options and adapters.
-
 ## Lowercase
 
 `Laminas\Filter\File\Lowercase` can be used to convert all file contents to

docs/book/v3/intro.md

@@ -53,54 +53,6 @@ echo $strtolower('I LOVE Laminas!'); // i love laminas!
 $laminaslove = $strtolower('I LOVE Laminas!');
 ```
 
-## Using the StaticFilter
-
-If it is inconvenient to load a given filter class and create an instance of the
-filter, you can use `StaticFilter` with its `execute()` method as an alternative
-invocation style. The first argument of this method is a data input value, that
-you would pass to the `filter()` method. The second argument is a string, which
-corresponds to the basename of the filter class, relative to the `Laminas\Filter`
-namespace. The `execute()` method automatically loads the class, creates an
-instance, and applies the `filter()` method to the data input.
-
-```php
-echo StaticFilter::execute('&', 'HtmlEntities');
-```
-
-You can also pass an array of constructor arguments, if they are needed for the
-filter class:
-
-```php
-echo StaticFilter::execute(
-    '"',
-    'HtmlEntities',
-    ['quotestyle' => ENT_QUOTES]
-);
-```
-
-The static usage can be convenient for invoking a filter ad hoc, but if you have
-the need to run a filter for multiple inputs, it’s more efficient to follow the
-first example above, creating an instance of the filter object and calling its
-`filter()` method.
-
-Also, the `FilterChain` class allows you to instantiate and run multiple filter
-and validator classes on demand to process sets of input data. See the
-[FilterChain](filter-chains.md) chapter for more details.
-
-You can set and receive the `FilterPluginManager` for the `StaticFilter` to
-amend the standard filter classes.
-
-```php
-$pluginManager = StaticFilter::getPluginManager()->setInvokableClass(
-    'myNewFilter',
-    'MyCustom\Filter\MyNewFilter'
-);
-
-StaticFilter::setPluginManager(new MyFilterPluginManager());
-```
-
-This is useful when adding custom filters to be used by the `StaticFilter`.
-
 ## Double filtering
 
 When using two filters in succession, you have to keep in mind that it is

docs/book/v3/migration/v2-to-v3.md

@@ -0,0 +1,49 @@
+# Migration from Version 2 to 3
+
+laminas-filter version 3 makes a number of changes that may affect your application.
+This document details those changes, and provides suggestions on how to update your application to work with version 3.
+
+## Removed Filters
+
+The following filters were deprecated in the 2.0.x series of releases and have now been removed:
+
+### Encryption and Decryption related filters
+
+These filters had become outdated. 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
+
+`Laminas\Filter\StaticFilter` has been removed without replacement. 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 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 Filters
+
+- `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)
+
+## Removed Features
+
+`Laminas\Filter\Compress` no longer supports the compression formats `Lzf`, `Rar` and `Snappy`.
+Support for these formats has been removed so the following classes are no longer available:
+
+- `Laminas\Filter\Compress\Lzf`
+- `Laminas\Filter\Compress\Rar`
+- `Laminas\Filter\Compress\Snappy`
+
+The following compression formats are still available: `Bz2`, `Gz`, `Tar` and `Zip`