Migration
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
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 aszendfilterstringtolower
- 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 toLaminas\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.
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 byLaminas\Filter\AllowList
Laminas\Filter\Blacklist
has been replaced byLaminas\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.