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.

New Features

Service Manager v4 Support

Laminas Filter now supports Service Manager v4. This will restrict installation of laminas-filter in projects that have other dependencies still constrained to version 3 of service manager, such as version 2.x of laminas-inputfilter.

New Filters

• ToEnum
• ImmutableFilterChain
• CompressString and DecompressString
• CompressToArchive
• DecompressArchive

Signature and Behaviour Changes

FilterInterface

Laminas\Filter\FilterInterface now specifies __invoke() as well as filter() forcing all filters to also be invokable classes.

Implementation is straight forward, and in most cases, adding the following method should suffice:

final class MyFilter implements Laminas\Filter\FilterInterface {
    public function filter(mixed $value): mixed
    {
        // Filter things…
    }
    
    public function __invoke(mixed $value) : mixed
    {
        return $this->filter($value); 
    }
}

Change of Parameter and Return Type

Also note that the signature of both filter() and __invoke() has changed to include mixed as both parameter and return type, therefore, it will be necessary to add any missing parameter and return types to your custom filters.

Filter Plugin Manager

As the library now requires laminas/laminas-servicemanager version 4, the inheritance hierarchy has changed for the plugin manager, however it is also now final.

In addition to this, the default filter aliases have changed:

• All legacy Zend\Filter\FilterName have been removed including the lowercased v2 FQCNs such as zendfilterstringtolower
• All lowercase FQCN aliases (That were added for Service Manager v2) have been removed such as laminasfilterstringtolower

The impact of the removal of these aliases will not affect you if you use a FQCN to retrieve filters from the plugin manager. If you experience ServiceNotFoundException errors, audit your usage of filters and the strings you use to retrieve them from the plugin manager and replace any outdated values with either the FQCN of the filter or a known, configured alias.

Changes to Individual Filters

CamelCaseToDash

The following methods have been removed:

• setOptions
• getOptions
• isOptions
• setSeparator
• getSeparator

The constructor now only accepts an associative array of documented options.

The filter will now treat numbers as a word boundary. For example ThisHas4Words will filter to This-Has-4-Words

CamelCaseToSeparator

The following methods have been removed:

• setOptions
• getOptions
• isOptions
• setSeparator
• getSeparator

The constructor now only accepts an associative array of documented options.

The filter will now treat numbers as a word boundary. For example ThisHas4Words with the default separator will filter to This Has 4 Words

CamelCaseToUnderscore

The following methods have been removed:

• setOptions
• getOptions
• isOptions
• setSeparator
• getSeparator

The constructor now only accepts an associative array of documented options.

The filter will now treat numbers as a word boundary. For example ThisHas4Words will filter to This_Has_4_Words

DashToSeparator

The following methods have been removed:

• setOptions
• getOptions
• isOptions
• setSeparator
• getSeparator

The constructor now only accepts an associative array of documented options.

DateSelect

The following methods have been removed:

• setOptions
• getOptions
• setNullOnAllEmpty
• isNullOnAllEmpty
• setNullOnEmpty
• isNullOnEmpty

The constructor now only accepts an associative array of documented options.

RuntimeException are no longer thrown when the filter receives an array with the incorrect number of elements.

All invalid values passed to the filter, invalid calendar dates, will now return the original value. Validators should be used to ensure the input has been filtered as expected, and to enforce any additional constraints.

DateTimeSelect

The following methods have been removed:

• setOptions
• getOptions
• setNullOnAllEmpty
• isNullOnAllEmpty
• setNullOnEmpty
• isNullOnEmpty

The constructor now only accepts an associative array of documented options.

RuntimeException are no longer thrown when the filter receives an array with the incorrect number of elements.

All invalid values passed to the filter, invalid calendar dates or times, will now return the original value. Validators should be used to ensure the input has been filtered as expected, and to enforce any additional constraints.

DenyList

The following methods have been removed:

• setStrict
• getStrict
• setList
• getList

The constructor now only accepts an associative array of documented options.

Dir

This filter will not cast a given integer or float value to a string anymore. The return value changed from . to return the given integer or float value.

FilterChain

This filter requires a FilterPluginManager instance as a constructor dependency.

The following methods and constants have been removed:

• DEFAULT_PRIORITY constant (moved to Laminas\Filter\FilterChainInterface)
• setOptions()
• getPluginManager()
• setPluginManager()
• plugin()
• getFilters()

A new ImmutableFilterChain class has also been introduced, which functions similarly to FilterChain but is immutable by design and lacks the merge() method.

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.

Inflector

The following methods have been removed:

• getPluginManager
• setPluginManager
• setOptions
• setThrowTargetExceptionsOn
• isThrowTargetExceptionsOn
• setTargetReplacementIdentifier
• getTargetReplacementIdentifier
• setTarget
• getTarget
• setTargetReference
• setRules
• addRules
• getRules
• getRule
• clearRules
• setFilterRule
• addFilterRule
• setStaticRule
• setStaticRuleReference

The constructor now only accepts an associative array of documented options and requires a FilterPluginManager instance as its first argument.

The ability to pass in references to be used as the inflection target, or as a static rule is no longer possible.

It is now possible to use an object as the filter input.

MonthSelect

The following methods have been removed:

• setOptions
• getOptions
• setNullOnAllEmpty
• isNullOnAllEmpty
• setNullOnEmpty
• isNullOnEmpty

The constructor now only accepts an associative array of documented options.

RuntimeException are no longer thrown when the filter receives an array with the incorrect number of elements.

All invalid values passed to the filter, including out of range months and years, will now return the original value. Validators should be used to ensure the input has been filtered as expected, and to enforce any additional constraints.

PregReplace

The following methods have been removed:

• setPattern
• getPattern
• setReplacement
• getReplacement

The constructor now only accepts an associative array of documented options.

Additionally, $options['pattern'] must be provided at construction time or an exception is thrown.

Exceptions for invalid or empty patterns are now thrown during construct rather than when the filter is invoked.

RealPath

The following methods have been removed:

• setExists
• getExists

The constructor now only accepts an associative array of documented options.

false is no longer returned when the path must exist and does not. Instead, the original value is returned. Filters are not intended to provide validation. So, to check if the path exists, ensure a validator (such as `Laminas\Validator\File\Exists') is also used.

Windows support has been dropped. Which in some cases may now need a custom filter to handle Windows specific issues.

Rename

The following methods have been removed:

• addFile
• getFile
• setFile
• getNewName

The constructor now only accepts an associative array of documented options.

The option for source has been renamed to match. The option for target has been split into target_directory and rename_to, to enable expressing intent between moving and renaming files.

RenameUpload

The following methods have been removed:

• setStreamFactory
• getStreamFactory
• setTarget
• getTarget
• setUploadFileFactory
• getUploadFileFactory
• setUseUploadName
• getUseUploadName
• setUseUploadExtension
• getUseUploadExtension
• setOverwrite
• getOverwrite
• setRandomize
• getRandomize

The constructor now only accepts an associative array of documented options.

This filter no longer returns values depending on input. Unfilterable values will be returned unchanged, but valid values will now be filtered to a string that represents the path that the uploaded file was moved to.

SeparatorToCamelCase

The constructor now only accepts an associative array of documented options.

SeparatorToDash

The constructor now only accepts an associative array of documented options.

SeparatorToSeparator

The following methods have been removed:

• setSearchSeparator
• getSearchSeparator
• setReplacementSeparator
• getReplacementSeparator

The constructor now only accepts an associative array of documented options.

StringPrefix

The following methods have been removed:

• setPrefix
• getPrefix

The constructor now only accepts an associative array of documented options.

An exception is no longer thrown for a missing prefix option, instead an empty string is used by default. This means that the filter will have the effect of simply casting scalar values to string when a prefix option is not provided.

The filter will now recursively process scalar array members. Previously, arrays would be returned unfiltered.

StringSuffix

The following methods have been removed:

• setSuffix
• getSuffix

The constructor now only accepts an associative array of documented options.

An exception is no longer thrown for a missing suffix option, instead an empty string is used by default. This means that the filter will have the effect of simply casting scalar values to string when a suffix option is not provided.

The filter will now recursively process scalar array members. Previously, arrays would be returned unfiltered.

StringTrim

The following methods have been removed:

• setCharList
• getCharList

The constructor now only accepts an associative array of documented options.

StripTags

The following methods have been removed:

• getTagsAllowed
• setTagsAllowed
• getAttributesAllowed
• setAttributesAllowed

The constructor now only accepts an associative array of documented options.

ToNull

The following methods have been removed:

• setType
• getType

The constructor now only accepts an associative array of documented options.

ToString

This filter now also casts array values to strings recursively.

Basic Usage

UnderscoreToSeparator

The constructor now only accepts an associative array of documented options.

Removed Filters

The following filters were deprecated in the 2.0.x series of releases and have now been removed:

Compress and Decompress

The Compress and Decompress filters have been removed and replaced with four more specialized filters:

• Laminas\Filter\CompressString - For string compression (supports bz2 and gz adapters)
• Laminas\Filter\DecompressString - For string decompression (supports bz2 and gz adapters)
• Laminas\Filter\CompressToArchive - For creating archive files (supports zip and tar adapters)
• Laminas\Filter\DecompressArchive - For extracting archive files (supports zip and tar adapters)

Other breaking changes:

• Archive adapters now implement ArchiveAdapterInterface and only handle archive files.
• String compression adapters now implement StringCompressionAdapterInterface and only handle string content.

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 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:

$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:

$pluginManager = $container->get(\Laminas\Filter\FilterPluginManager::class);
$filter = $pluginManager->get(\Laminas\Filter\HtmlEntities::class);
$filtered = $filter->filter('A String');

Uri Normalize

Laminas\Filter\UriNormalize has been removed. As noted in the v2 preparation guide, Laminas\Filter\ForceUriScheme might be a sufficient replacement depending on your use-case.

Whitelist & Blacklist Filters

• Laminas\Filter\Whitelist has been replaced by Laminas\Filter\AllowList
• Laminas\Filter\Blacklist has been replaced by Laminas\Filter\DenyList

Removed Features

Removal of AbstractFilter

AbstractFilter has been removed. If you have custom filters that extend from AbstractFilter, you will need to instead implement FilterInterface along with its filter and __invoke methods.

If your filter made use of the setOptions method, we strongly encourage you to add the options to your constructor, perform any necessary validation of these options in your constructor, and assign those values to class properties in any way that makes sense to your use-case.

We have written a short guide on refactoring your custom filters so that they no longer depend on AbstractFilter here.

Final by default

All the shipped filters now have the final keyword applied to the class. Individual filters were not designed for inheritance, so if you have filters that do extend from any of the shipped filters, you will likely have to re-consider your design.

Filters are, generally speaking, trivial to implement and for simple use-cases can be reduced to closures. Marking our filters as final prevents misuse of inheritance and reduces the backwards compatibility surface area that we need to maintain.

If you need to expand the capabilities of the shipped filters, consider using a filter chain to compose multiple filters, or implement a custom filter.

Removal of supported compression formats

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

Removal of the AbstractUnicode class

Various filters such as StringToLower and StringToUpper inherited from the abstract class AbstractUnicode whose purpose was to implement an encoding option. This class has been removed and the affected filters no longer inherit from anything. In order to provide consistent handling of the encoding option that has been re-implemented in these filters, a new class EncodingOption has been introduced which provides static methods to validate a given encoding option. This change is unlikely to affect you, unless you have inherited from this class. In which case, you will need to implement the provision of an encoding option for your custom filter and remove AbstractUnicode from your inheritance tree.

Removal of the FilterProviderInterface

This legacy interface is related to Laminas MVC Module Manager integration and was superseded by Laminas\ModuleManager\Feature\FilterProviderInterface. If your code still references Laminas\Filter\FilterProviderInterface, replace its usage with the interface shipped by Module Manager.

Removal of AbstractSeparator

A number of filters had an inheritance chain starting with Laminas\Filter\Word\AbstractSeparator which in turn extended from the now removed AbstractFilter. All filters that used this inheritance chain have been refactored to final standalone classes and AbstractSeparator has been removed.

If you have custom filters extending from AbstractSeparator, you will need to refactor your classes in a similar way. Typically, this will follow a similar pattern for classes extending from AbstractFilter, but you will also need to ensure that your custom filter accepts the separator value in its constructor, and, ensure that no code is attempting to mutate or access the options at runtime with the now unavailable setSeparator and getSeparator methods.