diff --git a/docs/book/v2/file.md b/docs/book/v2/file.md
index 03c517b3..0aadf7b2 100644
--- a/docs/book/v2/file.md
+++ b/docs/book/v2/file.md
@@ -1,20 +1,16 @@
# File Filters
-laminas-filter also comes with a set of classes for filtering file contents, and
-performing file operations such as renaming.
+laminas-filter also comes with a set of classes for filtering file contents, and performing file operations such as renaming.
> ## $_FILES
>
-> All file filter `filter()` implementations support either a file path string
-> *or* a `$_FILES` array as the supplied argument. When a `$_FILES` array is
-> passed in, the `tmp_name` is used for the file path.
+> All file filter `filter()` implementations support either a file path string *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.
+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:
@@ -33,8 +29,8 @@ $filter = new EncryptFileFilter([
$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:
+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;
@@ -55,8 +51,7 @@ for more information about options and adapters.
## Lowercase
-`Laminas\Filter\File\Lowercase` can be used to convert all file contents to
-lowercase.
+`Laminas\Filter\File\Lowercase` can be used to convert all file contents to lowercase.
### Supported Options
@@ -78,13 +73,10 @@ $filter = new LowerCase();
$filter->filter($files['my-upload']);
```
-This example converts the contents of an uploaded file to lowercase. After this
-process, you can use the [Rename](#rename) or [RenameUpload](#renameupload)
-filter to replace this file with your original file, or read directly from file.
-But, don't forget, if you upload a file and send your `$_FILES` array to a
-filter method, the `LowerCase` filter will only change the temporary file
-(`tmp_name` index of array), not the original file. Let's check following
-example:
+This example converts the contents of an uploaded file to lowercase.
+After this process, you can use the [Rename](#rename) or [RenameUpload](#renameupload) filter to replace this file with your original file, or read directly from file.
+But, don't forget, if you upload a file and send your `$_FILES` array to a filter method, the `LowerCase` filter will only change the temporary file (`tmp_name` index of array), not the original file.
+Let's check following example:
```php
use Laminas\Filter\File\LowerCase;
@@ -104,12 +96,9 @@ $renameFilter = new Rename([
$filename = $renameFilter->filter($file['tmp_name']);
```
-With this example, the final, stored file on the server will have the lowercased
-content.
+With this example, the final, stored file on the server will have the lowercased content.
-If you want to use a specific encoding when converting file content, you should
-specify the encoding when instantiating the `LowerCase` filter, or use the
-`setEncoding` method to change it.
+If you want to use a specific encoding when converting file content, you should specify the encoding when instantiating the `LowerCase` filter, or use the `setEncoding` method to change it.
```php
use Laminas\Filter\File\LowerCase;
@@ -136,21 +125,16 @@ for more information about encoding and its exceptions.
The following set of options are supported:
-- `target` (string; default: `*`): Target filename or directory; the new name
- of the source file.
-- `source` (string; default: `*`): Source filename or directory which will be
- renamed. Used to match the filtered file with an options set.
+- `target` (string; default: `*`): Target filename or directory; the new name of the source file.
+- `source` (string; default: `*`): Source filename or directory which will be renamed.
+Used to match the filtered file with an options set.
- `overwrite` (boolean; default: `false`): Shall existing files be overwritten?
- If the file is unable to be moved into the target path, a
- `Laminas\Filter\Exception\RuntimeException` will be thrown.
-- `randomize` (boolean; default: `false`): Shall target files have a random
- postfix attached? The random postfix will generated with `uniqid('_')` after
- the file name and before the extension. For example, `file.txt` might be
- randomized to `file_4b3403665fea6.txt`.
+- If the file is unable to be moved into the target path, a `Laminas\Filter\Exception\RuntimeException` will be thrown.
+- `randomize` (boolean; default: `false`): Shall target files have a random postfix attached? The random postfix will generated with `uniqid('_')` after the file name and before the extension.
+For example, `file.txt` might be randomized to `file_4b3403665fea6.txt`.
-An array of option sets is also supported, where a single `Rename` filter
-instance can filter several files using different options. The options used for
-the filtered file will be matched from the `source` option in the options set.
+An array of option sets is also supported, where a single `Rename` filter instance can filter several files using different options.
+The options used for the filtered file will be matched from the `source` option in the options set.
### Usage Examples
@@ -224,40 +208,28 @@ The following set of options are supported:
- `target` (string; default: `*`): Target directory or full filename path.
- `overwrite` (boolean; default: `false`): Shall existing files be overwritten?
- If the file is unable to be moved into the target path, a
- `Laminas\Filter\Exception\RuntimeException` will be thrown.
-- `randomize` (boolean; default: `false`): Shall target files have a random
- postfix attached? The random postfix will generated with `uniqid('_')` after
- the file name and before the extension. For example, `file.txt` might be
- randomized to `file_4b3403665fea6.txt`.
-- `use_upload_name` (boolean; default: `false`): When true, this filter will
- use `$_FILES['name']` as the target filename. Otherwise, the default `target`
- rules and the `$_FILES['tmp_name']` will be used.
-- `use_upload_extension` (boolean; default: `false`): When true, the uploaded
- file will maintains its original extension if not specified. For example, if
- the uploaded file is `file.txt` and the target is `mynewfile`, the upload
- will be renamed to `mynewfile.txt`.
+If the file is unable to be moved into the target path, a `Laminas\Filter\Exception\RuntimeException` will be thrown.
+- `randomize` (boolean; default: `false`): Shall target files have a random postfix attached? The random postfix will generated with `uniqid('_')` after the file name and before the extension.
+For example, `file.txt` might be randomized to `file_4b3403665fea6.txt`.
+- `use_upload_name` (boolean; default: `false`): When true, this filter will use `$_FILES['name']` as the target filename.
+Otherwise, the default `target` rules and the `$_FILES['tmp_name']` will be used.
+- `use_upload_extension` (boolean; default: `false`): When true, the uploaded file will maintains its original extension if not specified.
+For example, if the uploaded file is `file.txt` and the target is `mynewfile`, the upload will be renamed to `mynewfile.txt`.
- `stream_factory` (`Psr\Http\Message\StreamFactoryInterface`; default: `null`):
- Required when passing a [PSR-7 UploadedFileInterface](https://www.php-fig.org/psr/psr-7/#36-psrhttpmessageuploadedfileinterface)
- to the filter; used to create a new stream representing the renamed file.
- (Since 2.9.0)
-- `upload_file_factory` (`Psr\Http\Message\UploadedFileFactoryInterface`; default:
- `null`): Required when passing a [PSR-7 UploadedFileInterface](https://www.php-fig.org/psr/psr-7/#36-psrhttpmessageuploadedfileinterface)
- to the filter; used to create a new uploaded file representation of the
- renamed file. (Since 2.9.0)
+Required when passing a [PSR-7 UploadedFileInterface](https://www.php-fig.org/psr/psr-7/#36-psrhttpmessageuploadedfileinterface) to the filter; used to create a new stream representing the renamed file.
+(Since 2.9.0)
+- `upload_file_factory` (`Psr\Http\Message\UploadedFileFactoryInterface`; default: `null`): Required when passing a [PSR-7 UploadedFileInterface](https://www.php-fig.org/psr/psr-7/#36-psrhttpmessageuploadedfileinterface) to the filter; used to create a new uploaded file representation of the renamed file.
+(Since 2.9.0)
> ### Using the upload Name is unsafe
>
-> Be **very** careful when using the `use_upload_name` option. For instance,
-> extremely bad things could happen if you were to allow uploaded `.php` files
-> (or other CGI files) to be moved into the `DocumentRoot`.
+> Be **very** careful when using the `use_upload_name` option.
+> For instance, extremely bad things could happen if you were to allow uploaded `.php` files (or other CGI files) to be moved into the `DocumentRoot`.
>
-> It is generally a better idea to supply an internal filename to avoid
-> security risks.
+> It is generally a better idea to supply an internal filename to avoid security risks.
`RenameUpload` does not support an array of options like the`Rename` filter.
-When filtering HTML5 file uploads with the `multiple` attribute set, all files
-will be filtered with the same option settings.
+When filtering HTML5 file uploads with the `multiple` attribute set, all files will be filtered with the same option settings.
### Usage Examples
@@ -343,23 +315,16 @@ foreach ($request->getUploadedFiles() as $uploadedFile) {
> ### PSR-7 Support
>
-> PSR-7/PSR-17 support has only been available since 2.9.0, and requires a valid
-> [psr/http-factory-implementation](https://packagist.org/providers/psr/http-factory-implementation)
-> in your application, as it relies on the stream and uploaded file factories in
-> order to produce the final `UploadedFileInterface` artifact representing the
-> filtered file.
+> PSR-7/PSR-17 support has only been available since 2.9.0, and requires a valid [psr/http-factory-implementation](https://packagist.org/providers/psr/http-factory-implementation) in your application, as it relies on the stream and uploaded file factories in order to produce the final `UploadedFileInterface` artifact representing the filtered file.
>
-> PSR-17 itself requires PHP 7, so your application will need to be running on
-> PHP 7 in order to use this feature.
+> PSR-17 itself requires PHP 7, so your application will need to be running on PHP 7 in order to use this feature.
>
-> [laminas/laminas-diactoros 2.0](https://docs.laminas.dev/laminas-diactoros/)
-> provides a PSR-17 implementation, but requires PHP 7.1. If you are still on
-> PHP 7.0, either upgrade, or find a compatible psr/http-factory-implementation.
+> [laminas/laminas-diactoros 2.0](https://docs.laminas.dev/laminas-diactoros/) provides a PSR-17 implementation, but requires PHP 7.1.
+> If you are still on PHP 7.0, either upgrade, or find a compatible psr/http-factory-implementation.
## Uppercase
-`Laminas\Filter\File\Uppercase` can be used to convert all file contents to
-uppercase.
+`Laminas\Filter\File\Uppercase` can be used to convert all file contents to uppercase.
### Supported Options
@@ -381,5 +346,4 @@ $filter = new UpperCase();
$filter->filter($files['my-upload']);
```
-See the documentation on the [`LowerCase`](#lowercase) filter, above, for more
-information.
+See the documentation on the [`LowerCase`](#lowercase) filter, above, for more information.
diff --git a/docs/book/v2/filter-chains.md b/docs/book/v2/filter-chains.md
index 7d9cef8e..68f883af 100644
--- a/docs/book/v2/filter-chains.md
+++ b/docs/book/v2/filter-chains.md
@@ -1,12 +1,10 @@
# Filter Chains
Often, multiple filters should be applied to some value in a particular order.
-For example, a login form accepts a username that should be lowercase and
-contain only alphabetic characters.
+For example, a login form accepts a username that should be lowercase and contain only alphabetic characters.
-`Laminas\Filter\FilterChain` provides a simple method by which filters may be
-chained together. The following code illustrates how to chain together two
-filters for the submitted username and fulfill the above requirements:
+`Laminas\Filter\FilterChain` provides a simple method by which filters may be chained together.
+The following code illustrates how to chain together two filters for the submitted username and fulfill the above requirements:
```php
// Create a filter chain and add filters to the chain
@@ -19,21 +17,18 @@ $filterChain
$username = $filterChain->filter($_POST['username']);
```
-Filters are run in the order they are added to the filter chain. In the above
-example, the username is first removed of any non-alphabetic characters, and
-then any uppercase characters are converted to lowercase.
+Filters are run in the order they are added to the filter chain.
+In the above example, the username is first removed of any non-alphabetic characters, and then any uppercase characters are converted to lowercase.
-Any object that implements `Laminas\Filter\FilterInterface` may be used in a
-filter chain.
+Any object that implements `Laminas\Filter\FilterInterface` may be used in a filter chain.
## Setting Filter Chain Order
-For each filter added to the `FilterChain`, you can set a priority to define
-the chain order. Higher values indicate higher priority (execute first), while
-lower and/or negative values indicate lower priority (execute last). The default value is `1000`.
+For each filter added to the `FilterChain`, you can set a priority to define the chain order.
+Higher values indicate higher priority (execute first), while lower and/or negative values indicate lower priority (execute last).
+The default value is `1000`.
-In the following example, any uppercase characters are converted to lowercase
-before any non-alphabetic characters are removed.
+In the following example, any uppercase characters are converted to lowercase before any non-alphabetic characters are removed.
```php
// Create a filter chain and add filters to the chain
@@ -45,13 +40,13 @@ $filterChain
## Using the Plugin Manager
-A `FilterPluginManager` is attached to every `FilterChain` instance. Every filter
-that is used in a `FilterChain` must be known to the `FilterPluginManager`.
+A `FilterPluginManager` is attached to every `FilterChain` instance.
+Every filter that is used in a `FilterChain` must be known to the `FilterPluginManager`.
-To add a filter to the `FilterChain`, use the `attachByName()` method. The
-first parameter is the name of the filter within the `FilterPluginManager`. The
-second parameter takes any options for creating the filter instance. The third
-parameter is the priority.
+To add a filter to the `FilterChain`, use the `attachByName()` method.
+The first parameter is the name of the filter within the `FilterPluginManager`.
+The second parameter takes any options for creating the filter instance.
+The third parameter is the priority.
```php
// Create a filter chain and add filters to the chain
diff --git a/docs/book/v2/inflector.md b/docs/book/v2/inflector.md
index 320ca2e5..1154ff7b 100644
--- a/docs/book/v2/inflector.md
+++ b/docs/book/v2/inflector.md
@@ -1,15 +1,11 @@
# String Inflection
-`Laminas\Filter\Inflector` is a general purpose tool for rules-based inflection of
-strings to a given target.
+`Laminas\Filter\Inflector` is a general purpose tool for rules-based inflection of strings to a given target.
-As an example, you may find you need to transform MixedCase or camelCasedWords
-into a path; for readability, OS policies, or other reasons, you also need to
-lower case this; and finally, you want to separate the words using a dash
-(`-`). An inflector can do this for you.
+As an example, you may find you need to transform MixedCase or camelCasedWords into a path; for readability, OS policies, or other reasons, you also need to lower case this; and finally, you want to separate the words using a dash (`-`).
+An inflector can do this for you.
-`Laminas\Filter\Inflector` implements `Laminas\Filter\FilterInterface`; you perform
-inflection by calling `filter()` on the object instance.
+`Laminas\Filter\Inflector` implements `Laminas\Filter\FilterInterface`; you perform inflection by calling `filter()` on the object instance.
## Transforming MixedCase and CamelCaseText to another Format
@@ -31,18 +27,17 @@ $filtered = $inflector->filter(['page' => $string]);
## Operation
-An inflector requires a **target** and one or more **rules**. A target is
-basically a string that defines placeholders for variables you wish to
-substitute. These are specified by prefixing with a `:`: `:script`.
+An inflector requires a **target** and one or more **rules**.
+A target is basically a string that defines placeholders for variables you wish to substitute.
+These are specified by prefixing with a `:`: `:script`.
-When calling `filter()`, you then pass in an array of key and value pairs
-corresponding to the variables in the target.
+When calling `filter()`, you then pass in an array of key and value pairs corresponding to the variables in the target.
Each variable in the target can have zero or more rules associated with them.
-Rules may be either **static** or refer to a laminas-filter class. Static rules
-will replace with the text provided. Otherwise, a class matching the rule
-provided will be used to inflect the text. Classes are typically specified
-using a short name indicating the filter name stripped of any common prefix.
+Rules may be either **static** or refer to a laminas-filter class.
+Static rules will replace with the text provided.
+Otherwise, a class matching the rule provided will be used to inflect the text.
+Classes are typically specified using a short name indicating the filter name stripped of any common prefix.
As an example, you can use any laminas-filter concrete implementations; however,
instead of referring to them as `Laminas\I18n\Filter\Alpha` or
@@ -50,20 +45,16 @@ instead of referring to them as `Laminas\I18n\Filter\Alpha` or
### Using Custom Filters
-`Laminas\Filter\Inflector` uses `Laminas\Filter\FilterPluginManager` to manage
-loading filters to use with inflection. By default, filters registered with
-`Laminas\Filter\FilterPluginManager` are available. To access filters with that
-prefix but which occur deeper in the hierarchy, such as the various `Word`
-filters, simply strip off the `Laminas\Filter` prefix:
+`Laminas\Filter\Inflector` uses `Laminas\Filter\FilterPluginManager` to manage loading filters to use with inflection.
+By default, filters registered with `Laminas\Filter\FilterPluginManager` are available.
+To access filters with that prefix but which occur deeper in the hierarchy, such as the various `Word` filters, simply strip off the `Laminas\Filter` prefix:
```php
// use Laminas\Filter\Word\CamelCaseToDash as a rule
$inflector->addRules(['script' => 'Word\CamelCaseToDash']);
```
-To use custom filters, you have two choices: reference them by fully qualified
-class name (e.g., `My\Custom\Filter\Mungify`), or manipulate the composed
-`FilterPluginManager` instance.
+To use custom filters, you have two choices: reference them by fully qualified class name (e.g., `My\Custom\Filter\Mungify`), or manipulate the composed `FilterPluginManager` instance.
```php
$filters = $inflector->getPluginManager();
@@ -73,9 +64,8 @@ $filters->addInvokableClass('mungify', 'My\Custom\Filter\Mungify');
### Setting the Inflector Target
The inflector target is a string with some placeholders for variables.
-Placeholders take the form of an identifier, a colon (`:`) by default, followed
-by a variable name: `:script`, `:path`, etc. The `filter()` method looks for
-the identifier followed by the variable name being replaced.
+Placeholders take the form of an identifier, a colon (`:`) by default, followed by a variable name: `:script`, `:path`, etc.
+The `filter()` method looks for the identifier followed by the variable name being replaced.
You can change the identifier using the `setTargetReplacementIdentifier()`
method, or passing it as the fourth argument to the constructor:
@@ -88,17 +78,16 @@ $inflector = new Laminas\Filter\Inflector('#foo/#bar.#sfx', array(), null, '#');
$inflector->setTargetReplacementIdentifier('#');
```
-Typically, you will set the target via the constructor. However, you may want
-to re-set the target later. `setTarget()` can be used for this purpose:
+Typically, you will set the target via the constructor.
+However, you may want to re-set the target later.
+`setTarget()` can be used for this purpose:
```php
$inflector->setTarget('layouts/:script.phtml');
```
-Additionally, you may wish to have a class member for your class that you can
-use to keep the inflector target updated — without needing to directly update
-the target each time (thus saving on method calls). `setTargetReference()`
-allows you to do this:
+Additionally, you may wish to have a class member for your class that you can use to keep the inflector target updated — without needing to directly update the target each time (thus saving on method calls).
+`setTargetReference()` allows you to do this:
```php
class Foo
@@ -138,21 +127,15 @@ As mentioned in the introduction, there are two types of rules: static and filte
> ### Order is important
>
-> It is important to note that regardless of the method in which you add rules
-> to the inflector, either one-by-one, or all-at-once; the order is very
-> important. More specific names, or names that might contain other rule names,
-> must be added before least specific names. For example, assuming the two rule
-> names `moduleDir` and `module`, the `moduleDir` rule should appear before
-> module since `module` is contained within `moduleDir`. If `module` were added
-> before `moduleDir`, `module` will match part of `moduleDir` and process it
-> leaving `Dir` inside of the target uninflected.
+> It is important to note that regardless of the method in which you add rules to the inflector, either one-by-one, or all-at-once; the order is very important.
+> More specific names, or names that might contain other rule names, must be added before least specific names.
+> For example, assuming the two rule names `moduleDir` and `module`, the `moduleDir` rule should appear before module since `module` is contained within `moduleDir`.
+> If `module` were added before `moduleDir`, `module` will match part of `moduleDir` and process it leaving `Dir` inside of the target uninflected.
### Static Rules
-Static rules do simple string substitution; use them when you have a segment in
-the target that will typically be static, but which you want to allow the
-developer to modify. Use the `setStaticRule()` method to set or modify the
-rule:
+Static rules do simple string substitution; use them when you have a segment in the target that will typically be static, but which you want to allow the developer to modify.
+Use the `setStaticRule()` method to set or modify the rule:
```php
$inflector = new Laminas\Filter\Inflector(':script.:suffix');
@@ -162,11 +145,8 @@ $inflector->setStaticRule('suffix', 'phtml');
$inflector->setStaticRule('suffix', 'php');
```
-Much like the target itself, you can also bind a static rule to a reference,
-allowing you to update a single variable instead of require a method call; this
-is often useful when your class uses an inflector internally, and you don't
-want your users to need to fetch the inflector in order to update it. The
-`setStaticRuleReference()` method is used to accomplish this:
+Much like the target itself, you can also bind a static rule to a reference, allowing you to update a single variable instead of require a method call; this is often useful when your class uses an inflector internally, and you don't want your users to need to fetch the inflector in order to update it.
+The`setStaticRuleReference()` method is used to accomplish this:
```php
class Foo
@@ -202,23 +182,19 @@ class Foo
### Filter-Based Inflector Rules
-`Laminas\Filter` filters may be used as inflector rules as well. Just like static
-rules, these are bound to a target variable; unlike static rules, you may
-define multiple filters to use when inflecting. These filters are processed in
-order, so be careful to register them in an order that makes sense for the data
-you receive.
+`Laminas\Filter` filters may be used as inflector rules as well.
+Just like static rules, these are bound to a target variable; unlike static rules, you may define multiple filters to use when inflecting.
+These filters are processed in order, so be careful to register them in an order that makes sense for the data you receive.
-Rules may be added using `setFilterRule()` (which overwrites any previous rules
-for that variable) or `addFilterRule()` (which appends the new rule to any
-existing rule for that variable). Filters are specified in one of the following
-ways:
+Rules may be added using `setFilterRule()` (which overwrites any previous rules for that variable) or `addFilterRule()` (which appends the new rule to any existing rule for that variable).
+Filters are specified in one of the following ways:
-- **String**. The string may be a filter class name, or a class name segment
- minus any prefix set in the inflector's plugin loader (by default, minus the
- '`Laminas\Filter`' prefix).
-- **Filter object**. Any object instance implementing
- `Laminas\Filter\FilterInterface` may be passed as a filter.
-- **Array**. An array of one or more strings or filter objects as defined above.
+- **String**.
+The string may be a filter class name, or a class name segment minus any prefix set in the inflector's plugin loader (by default, minus the '`Laminas\Filter`' prefix).
+- **Filter object**.
+Any object instance implementing `Laminas\Filter\FilterInterface` may be passed as a filter.
+- **Array**.
+An array of one or more strings or filter objects as defined above.
```php
$inflector = new Laminas\Filter\Inflector(':script.:suffix');
@@ -238,14 +214,11 @@ $inflector->setFilterRule('script', [
## Setting many Rules at once
-Typically, it's easier to set many rules at once than to configure a single
-variable and its inflection rules one at a time. `Laminas\Filter\Inflector`'s
-`addRules()` and `setRules()` methods allow this.
+Typically, it's easier to set many rules at once than to configure a single variable and its inflection rules one at a time.
+`Laminas\Filter\Inflector`'s `addRules()` and `setRules()` methods allow this.
-Each method takes an array of variable and rule pairs, where the rule may be
-whatever the type of rule accepts (string, filter object, or array). Variable
-names accept a special notation to allow setting static rules and filter rules,
-according to the following notation:
+Each method takes an array of variable and rule pairs, where the rule may be whatever the type of rule accepts (string, filter object, or array).
+Variable names accept a special notation to allow setting static rules and filter rules, according to the following notation:
- **`:` prefix**: filter rules.
- **No prefix**: static rule.
@@ -266,42 +239,27 @@ $inflector->addRules([
## Utility Methods
-`Laminas\Filter\Inflector` has a number of utility methods for retrieving and
-setting the plugin loader, manipulating and retrieving rules, and controlling
-if and when exceptions are thrown.
-
-- `setPluginManager()` can be used when you have configured your own
- `Laminas\Filter\FilterPluginManager` instance and wish to use it with
- `Laminas\Filter\Inflector`; `getPluginManager()` retrieves the currently set
- one.
-- `setThrowTargetExceptionsOn()` can be used to control whether or not
- `filter()` throws an exception when a given replacement identifier passed to
- it is not found in the target. By default, no exceptions are thrown.
- `isThrowTargetExceptionsOn()` will tell you what the current value is.
-- `getRules($spec = null)` can be used to retrieve all registered rules for all
- variables, or just the rules for a single variable.
-- `getRule($spec, $index)` fetches a single rule for a given variable; this can
- be useful for fetching a specific filter rule for a variable that has a
- filter chain. `$index` must be passed.
+`Laminas\Filter\Inflector` has a number of utility methods for retrieving and setting the plugin loader, manipulating and retrieving rules, and controlling if and when exceptions are thrown.
+
+- `setPluginManager()` can be used when you have configured your own `Laminas\Filter\FilterPluginManager` instance and wish to use it with `Laminas\Filter\Inflector`; `getPluginManager()` retrieves the currently set one.
+- `setThrowTargetExceptionsOn()` can be used to control whether or not `filter()` throws an exception when a given replacement identifier passed to it is not found in the target.
+By default, no exceptions are thrown.
+`isThrowTargetExceptionsOn()` will tell you what the current value is.
+- `getRules($spec = null)` can be used to retrieve all registered rules for all variables, or just the rules for a single variable.
+- `getRule($spec, $index)` fetches a single rule for a given variable; this can be useful for fetching a specific filter rule for a variable that has a filter chain.
+`$index` must be passed.
- `clearRules()` will clear all currently registered rules.
## Using a Traversable or an Array
-You can use a `Traversable` or an array to set rules and other object state in
-your inflectors, by passing either type to either the constructor or the
-`setOptions()` method. The following settings may be specified:
+You can use a `Traversable` or an array to set rules and other object state in your inflectors, by passing either type to either the constructor or the `setOptions()` method.
+The following settings may be specified:
- `target` specifies the inflection target.
-- `pluginManager` specifies the `Laminas\Filter\FilterPluginManager` instance or
- extension to use for obtaining plugins; alternately, you may specify a class
- name of a class that extends the `FilterPluginManager`.
-- `throwTargetExceptionsOn` should be a boolean indicating whether or not to
- throw exceptions when a replacement identifier is still present after
- inflection.
-- `targetReplacementIdentifier` specifies the character to use when identifying
- replacement variables in the target string.
-- `rules` specifies an array of inflection rules; it should consist of keys
- that specify either values or arrays of values, consistent with `addRules()`.
+- `pluginManager` specifies the `Laminas\Filter\FilterPluginManager` instance or extension to use for obtaining plugins; alternately, you may specify a class name of a class that extends the `FilterPluginManager`.
+- `throwTargetExceptionsOn` should be a boolean indicating whether or not to throw exceptions when a replacement identifier is still present after inflection.
+- `targetReplacementIdentifier` specifies the character to use when identifying replacement variables in the target string.
+- `rules` specifies an array of inflection rules; it should consist of keys that specify either values or arrays of values, consistent with `addRules()`.
As examples:
diff --git a/docs/book/v2/intro.md b/docs/book/v2/intro.md
index f10ac0ba..3faf6665 100644
--- a/docs/book/v2/intro.md
+++ b/docs/book/v2/intro.md
@@ -1,31 +1,22 @@
# Introduction
-laminas-filter provides a set of commonly needed data filters. It also provides a
-simple filter chaining mechanism by which multiple filters may be applied to a
-single datum in a user-defined order.
+laminas-filter provides a set of commonly needed data filters.
+It also provides a simple filter chaining mechanism by which multiple filters may be applied to a single datum in a user-defined order.
## What is a filter?
-In the physical world, a filter is typically used for removing unwanted portions
-of input, and the desired portion of the input passes through as filter output
-(e.g., coffee). In such scenarios, a filter is an operator that produces a
-subset of the input. This type of filtering is useful for web applications:
-removing illegal input, trimming unnecessary white space, etc.
-
-This basic definition of a filter may be extended to include generalized
-transformations upon input. A common transformation applied in web applications
-is the escaping of HTML entities. For example, if a form field is automatically
-populated with untrusted input (e.g., from a web browser), this value should
-either be free of HTML entities or contain only escaped HTML entities, in order
-to prevent undesired behavior and security vulnerabilities. To meet this
-requirement, HTML entities that appear in the input must either be removed or
-escaped. Of course, which approach is more appropriate depends on the situation.
-A filter that removes the HTML entities operates within the scope of the first
-definition of filter - an operator that produces a subset of the input. A filter
-that escapes the HTML entities, however, transforms the input (e.g., `&` is
-transformed to `&`). Supporting such use cases for web developers is
-important, and “to filter”, in the context of using laminas-filter, means to
-perform some transformations upon input data.
+In the physical world, a filter is typically used for removing unwanted portions of input, and the desired portion of the input passes through as filter output (e.g., coffee).
+In such scenarios, a filter is an operator that produces a subset of the input.
+This type of filtering is useful for web applications: removing illegal input, trimming unnecessary white space, etc.
+
+This basic definition of a filter may be extended to include generalized transformations upon input.
+A common transformation applied in web applications is the escaping of HTML entities.
+For example, if a form field is automatically populated with untrusted input (e.g., from a web browser), this value should either be free of HTML entities or contain only escaped HTML entities, in order to prevent undesired behavior and security vulnerabilities.
+To meet this requirement, HTML entities that appear in the input must either be removed or escaped.
+Of course, which approach is more appropriate depends on the situation.
+A filter that removes the HTML entities operates within the scope of the first definition of filter - an operator that produces a subset of the input.
+A filter that escapes the HTML entities, however, transforms the input (e.g., `&` is transformed to `&`).
+Supporting such use cases for web developers is important, and “to filter”, in the context of using laminas-filter, means to perform some transformations upon input data.
## Basic usage of filters
@@ -33,8 +24,7 @@ Having this filter definition established provides the foundation for
`Laminas\Filter\FilterInterface`, which requires a single method named `filter()`
to be implemented by a filter class.
-Following is a basic example of using a filter upon two input data, the
-ampersand (`&`) and double quote (`"`) characters:
+Following is a basic example of using a filter upon two input data, the ampersand (`&`) and double quote (`"`) characters:
```php
$htmlEntities = new Laminas\Filter\HtmlEntities();
@@ -43,8 +33,7 @@ echo $htmlEntities->filter('&'); // &
echo $htmlEntities->filter('"'); // "
```
-Also, if a filter inherits from `Laminas\Filter\AbstractFilter` (as do all of the
-out-of-the-box filters), you can also use them as invokables:
+Also, if a filter inherits from `Laminas\Filter\AbstractFilter` (as do all of the out-of-the-box filters), you can also use them as invokables:
```php
$strtolower = new Laminas\Filter\StringToLower;
@@ -58,20 +47,16 @@ $laminaslove = $strtolower('I LOVE Laminas!');
CAUTION: **Deprecated**
This filter is deprecated since version 2.15.0 and [will be removed](migration/preparing-for-v3.md#static-filter-removal) in version 3.0.
-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.
+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:
+You can also pass an array of constructor arguments, if they are needed for the filter class:
```php
echo StaticFilter::execute(
@@ -81,17 +66,12 @@ echo StaticFilter::execute(
);
```
-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.
+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.
+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.
+You can set and receive the `FilterPluginManager` for the `StaticFilter` to amend the standard filter classes.
```php
$pluginManager = StaticFilter::getPluginManager()->setInvokableClass(
@@ -106,9 +86,8 @@ 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
-often not possible to get the original output by using the opposite filter. Take
-the following example:
+When using two filters in succession, you have to keep in mind that it is often not possible to get the original output by using the opposite filter.
+Take the following example:
```php
$original = 'my_original_content';
@@ -122,21 +101,18 @@ $filter2 = new Laminas\Filter\Word\CamelCaseToUnderscore();
$filtered = $filter2->filter($filtered)
```
-The above code example could lead to the impression that you will get the
-original output after the second filter has been applied. But thinking logically
-this is not the case. After applying the first filter, `my_original_content` will
-be changed to `MyOriginalContent`. But after applying the second filter, the result
-is `My_Original_Content`.
+The above code example could lead to the impression that you will get the original output after the second filter has been applied.
+But thinking logically this is not the case.
+After applying the first filter, `my_original_content` will be changed to `MyOriginalContent`.
+But after applying the second filter, the result is `My_Original_Content`.
-As you can see it is not always possible to get the original output by using a
-filter which seems to be the opposite. It depends on the filter and also on the
-given input.
+As you can see it is not always possible to get the original output by using a filter which seems to be the opposite.
+It depends on the filter and also on the given input.
## Providing filters via modules
If you wish to indicate that your laminas-mvc module provides filters, have your
-`Module` class implement `Laminas\Filter\FilterProviderInterface`, which defines
-the method:
+`Module` class implement `Laminas\Filter\FilterProviderInterface`, which defines the method:
```php
/**
@@ -148,10 +124,6 @@ public function getFilterConfig();
The method should return an array of configuration following the
[laminas-servicemanager configuration format](https://docs.laminas.dev/laminas-servicemanager/configuring-the-service-manager/).
-If you are not using laminas-mvc, but are using a dependency injection container
-(e.g., if you are using Mezzio), you can also provide filters using the
-top-level `filters` configuration key; the value of that key should be
-laminas-servicemanager configuration, as linked above.
+If you are not using laminas-mvc, but are using a dependency injection container (e.g., if you are using Mezzio), you can also provide filters using the top-level `filters` configuration key; the value of that key should be laminas-servicemanager configuration, as linked above.
-(laminas-mvc users may also provide configuration in the same way, and omit
-implementation of the `FilterProviderInterface`.)
+(laminas-mvc users may also provide configuration in the same way, and omit implementation of the `FilterProviderInterface`.)
diff --git a/docs/book/v2/migration/preparing-for-v3.md b/docs/book/v2/migration/preparing-for-v3.md
index 35904086..931d4c91 100644
--- a/docs/book/v2/migration/preparing-for-v3.md
+++ b/docs/book/v2/migration/preparing-for-v3.md
@@ -1,6 +1,7 @@
# 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.
+Version 3 will introduce a number of backwards incompatible changes.
+This document is intended to help you prepare for these changes.
## Removed Features
@@ -55,7 +56,8 @@ If you are currently using any of these compression formats with laminas-filter,
### 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.
+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`
@@ -64,7 +66,8 @@ These filters have become outdated and will be removed in version 3.0 of this li
### 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:
+`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');
diff --git a/docs/book/v2/standard-filters.md b/docs/book/v2/standard-filters.md
index 7fc5e2b1..d79c0d1a 100644
--- a/docs/book/v2/standard-filters.md
+++ b/docs/book/v2/standard-filters.md
@@ -8,9 +8,8 @@ TIP: **New Feature**
Available since version 2.12.0
Previously known as `Whitelist`.
-This filter will return `null` if the value being filtered is not present the
-filter's allowed list of values. If the value is present, it will return that
-value.
+This filter will return `null` if the value being filtered is not present the filter's allowed list of values.
+If the value is present, it will return that value.
For the opposite functionality see the [DenyList](#denylist) filter.
@@ -33,12 +32,10 @@ echo $allowList->filter('not-allowed'); // => null
## Alnum
-The `Alnum` filter can be used to return only alphabetic characters and digits
-in the unicode "letter" and "number" categories, respectively. All other
-characters are suppressed.
+The `Alnum` filter can be used to return only alphabetic characters and digits in the unicode "letter" and "number" categories, respectively.
+All other characters are suppressed.
-This filter is part of the laminas-i18n package; you will need to include that
-package in your application to use it.
+This filter is part of the laminas-i18n package; you will need to include that package in your application to use it.
### Supported Options
@@ -49,14 +46,13 @@ Alnum([ boolean $allowWhiteSpace [, string $locale ]])
```
- `$allowWhiteSpace`: If set to true, then whitespace characters are allowed.
- Otherwise they are suppressed. Default is `false` (whitespace is not allowed).
- Methods for getting/setting the `allowWhiteSpace` option are also available:
- `getAllowWhiteSpace()` and `setAllowWhiteSpace()`.
+Otherwise they are suppressed.
+Default is `false` (whitespace is not allowed).
+Methods for getting/setting the `allowWhiteSpace` option are also available: `getAllowWhiteSpace()` and `setAllowWhiteSpace()`.
-- `$locale`: The locale string used in identifying the characters to filter
- (locale name, e.g. `en_US`). If unset, it will use the default locale
- (`Locale::getDefault()`). Methods for getting/setting the locale are also
- available: `getLocale()` and `setLocale()`.
+- `$locale`: The locale string used in identifying the characters to filter (locale name, e.g.`en_US`).
+If unset, it will use the default locale (`Locale::getDefault()`).
+Methods for getting/setting the locale are also available: `getLocale()` and `setLocale()`.
### Basic Usage
@@ -75,17 +71,15 @@ echo $filter->filter('This is (my) content: 123');
> ### Supported Languages
>
> `Alnum` works on almost all languages, except: Chinese, Japanese and Korean.
-> Within these languages, the english alphabet is used instead of the characters
-> from these languages. The language itself is detected using the `Locale`
-> class.
+> Within these languages, the english alphabet is used instead of the characters from these languages.
+> The language itself is detected using the `Locale` class.
## Alpha
-The `Alpha` filter can be used to return only alphabetic characters in the unicode "letter"
-category. All other characters are suppressed.
+The `Alpha` filter can be used to return only alphabetic characters in the unicode "letter" category.
+All other characters are suppressed.
-This filter is part of the laminas-i18n package; you will need to include that
-package in your application to use it.
+This filter is part of the laminas-i18n package; you will need to include that package in your application to use it.
### Supported Options
@@ -96,14 +90,13 @@ Alpha([ boolean $allowWhiteSpace [, string $locale ]])
```
- `$allowWhiteSpace`: If set to true then whitespace characters are allowed.
- Otherwise they are suppressed. Default is `false` (whitespace is not allowed).
- Methods for getting/setting the allowWhiteSpace option are also available:
- `getAllowWhiteSpace()` and `setAllowWhiteSpace()`.
+Otherwise they are suppressed.
+Default is `false` (whitespace is not allowed).
+Methods for getting/setting the allowWhiteSpace option are also available: `getAllowWhiteSpace()` and `setAllowWhiteSpace()`.
-- `$locale`: The locale string used in identifying the characters to filter
- (locale name, e.g. `en_US`). If unset, it will use the default locale
- (`Locale::getDefault()`). Methods for getting/setting the locale are also
- available: `getLocale()` and `setLocale()`.
+- `$locale`: The locale string used in identifying the characters to filter (locale name, e.g. `en_US`).
+If unset, it will use the default locale (`Locale::getDefault()`).
+Methods for getting/setting the locale are also available: `getLocale()` and `setLocale()`.
### Basic Usage
@@ -122,14 +115,12 @@ echo $filter->filter('This is (my) content: 123');
> ### Supported Languages
>
> `Alpha` works on almost all languages, except: Chinese, Japanese and Korean.
-> Within these languages, the english alphabet is used instead of the characters
-> from these languages. The language itself is detected using the `Locale`
-> class.
+> Within these languages, the english alphabet is used instead of the characters from these languages.
+> The language itself is detected using the `Locale` class.
## BaseName
-`Laminas\Filter\BaseName` allows you to filter a string which contains the path to
-a file, and it will return the base name of this file.
+`Laminas\Filter\BaseName` allows you to filter a string which contains the path to a file, and it will return the base name of this file.
### Supported Options
@@ -161,23 +152,22 @@ Use the [DenyList filter](#denylist) instead.
## Boolean
-This filter changes a given input to be a `BOOLEAN` value. This is often useful when working with
-databases or when processing form values.
+This filter changes a given input to be a `BOOLEAN` value.
+This is often useful when working with databases or when processing form values.
### Supported Options
The following options are supported for `Laminas\Filter\Boolean`:
-- `casting`: When this option is set to `TRUE`, then any given input will be
- cast to boolean. This option defaults to `TRUE`.
+- `casting`: When this option is set to `TRUE`, then any given input will be cast to boolean.
+This option defaults to `TRUE`.
- `translations`: This option sets the translations which will be used to detect localized input.
-- `type`: The `type` option sets the boolean type which should be used. Read
- the following for details.
+- `type`: The `type` option sets the boolean type which should be used.
+Read the following for details.
### Default Behavior
-By default, this filter works by casting the input to a `BOOLEAN` value; in other words, it operates
-in a similar fashion to calling `(boolean) $value`.
+By default, this filter works by casting the input to a `BOOLEAN` value; in other words, it operates in a similar fashion to calling `(boolean) $value`.
```php
$filter = new Laminas\Filter\Boolean();
@@ -186,13 +176,12 @@ $result = $filter->filter($value);
// returns false
```
-This means that without providing any configuration, `Laminas\Filter\Boolean` accepts all input types
-and returns a `BOOLEAN` just as you would get by type casting to `BOOLEAN`.
+This means that without providing any configuration, `Laminas\Filter\Boolean` accepts all input types and returns a `BOOLEAN` just as you would get by type casting to `BOOLEAN`.
### Changing the Default Behavior
-Sometimes, casting with `(boolean)` will not suffice. `Laminas\Filter\Boolean`
-allows you to configure specific types to convert, as well as which to omit.
+Sometimes, casting with `(boolean)` will not suffice.
+`Laminas\Filter\Boolean` allows you to configure specific types to convert, as well as which to omit.
The following types can be handled (in this precedence order):
@@ -208,14 +197,16 @@ The following types can be handled (in this precedence order):
There are 2 additional special types:
-- `all`: Converts all above types to `BOOLEAN`. The same as setting all above types.
-- `php`: Converts all above types to `BOOLEAN` except `localized` or `false`. The same as setting all above types except `localized` or `false`.
+- `all`: Converts all above types to `BOOLEAN`.
+The same as setting all above types.
+- `php`: Converts all above types to `BOOLEAN` except `localized` or `false`.
+The same as setting all above types except `localized` or `false`.
All other given values will return `TRUE` by default.
-There are several ways to select which of the above types are filtered. You can
-give one or multiple types and add them, you can give an array, you can use
-constants, or you can give a textual string. See the following examples:
+There are several ways to select which of the above types are filtered.
+You can give one or multiple types and add them, you can give an array, you can use constants, or you can give a textual string.
+See the following examples:
```php
// converts 0 to false
@@ -252,8 +243,8 @@ As mentioned previously, `Laminas\Filter\Boolean` can also recognise localized "
This means that you can ask your customer in a form for "yes" or "no" within his native language and
`Laminas\Filter\Boolean` will convert the response to the appropriate boolean value.
-To set the translation and the corresponding value, you can use the `translations` option or the
-method `setTranslations`. The translations must be set for any values you wish to map to boolean values.
+To set the translation and the corresponding value, you can use the `translations` option or the method `setTranslations`.
+The translations must be set for any values you wish to map to boolean values.
```php
$filter = new Laminas\Filter\Boolean([
@@ -275,24 +266,22 @@ $result = $filter->filter('yes');
### Disable Casting
-Sometimes it is necessary to recognise only `TRUE` or `FALSE` and return all
-other values without changes. `Laminas\Filter\Boolean` allows you to do this by
-setting the `casting` option to `FALSE`.
-
-In this case `Laminas\Filter\Boolean` will work as described in the following
-table, which shows which values return `TRUE` or `FALSE`. All other given values
-are returned without change when `casting` is set to `FALSE`
-
-Type Constant | Type String | True | False
----- | ---- | ---- | -----
-`Laminas\Filter\Boolean::TYPE_BOOLEAN` | `boolean` | `TRUE` | `FALSE`
-`Laminas\Filter\Boolean::TYPE_EMPTY_ARRAY` | `array` | | `[]`
-`Laminas\Filter\Boolean::TYPE_FALSE_STRING` | `false` | `'true'` (case insensitive) | `'false'` (case insensitive)
-`Laminas\Filter\Boolean::TYPE_FLOAT` | `float` | `1.0` | `0.0`
-`Laminas\Filter\Boolean::TYPE_INTEGER` | `integer` | `1` | `0`
-`Laminas\Filter\Boolean::TYPE_NULL` | `null` | | `NULL`
-`Laminas\Filter\Boolean::TYPE_STRING` | `string` | | `''`
-`Laminas\Filter\Boolean::TYPE_ZERO_STRING` | `zero` | `'1'` | `'0'`
+Sometimes it is necessary to recognise only `TRUE` or `FALSE` and return all other values without changes.
+`Laminas\Filter\Boolean` allows you to do this by setting the `casting` option to `FALSE`.
+
+In this case `Laminas\Filter\Boolean` will work as described in the following table, which shows which values return `TRUE` or `FALSE`.
+All other given values are returned without change when `casting` is set to `FALSE`
+
+| Type Constant | Type String | True | False |
+|---------------------------------------------|-------------|-----------------------------|------------------------------|
+| `Laminas\Filter\Boolean::TYPE_BOOLEAN` | `boolean` | `TRUE` | `FALSE` |
+| `Laminas\Filter\Boolean::TYPE_EMPTY_ARRAY` | `array` | | `[]` |
+| `Laminas\Filter\Boolean::TYPE_FALSE_STRING` | `false` | `'true'` (case insensitive) | `'false'` (case insensitive) |
+| `Laminas\Filter\Boolean::TYPE_FLOAT` | `float` | `1.0` | `0.0` |
+| `Laminas\Filter\Boolean::TYPE_INTEGER` | `integer` | `1` | `0` |
+| `Laminas\Filter\Boolean::TYPE_NULL` | `null` | | `NULL` |
+| `Laminas\Filter\Boolean::TYPE_STRING` | `string` | | `''` |
+| `Laminas\Filter\Boolean::TYPE_ZERO_STRING` | `zero` | `'1'` | `'0'` |
The following example shows the behavior when changing the `casting` option:
@@ -314,9 +303,8 @@ $result = $filter->filter(2);
## Callback
-This filter allows you to use own methods in conjunction with `Laminas\Filter`. You
-don't have to create a new filter when you already have a method which does the
-job.
+This filter allows you to use own methods in conjunction with `Laminas\Filter`.
+You don't have to create a new filter when you already have a method which does the job.
### Supported Options
@@ -328,8 +316,8 @@ The following options are supported for `Laminas\Filter\Callback`:
### Basic Usage
-The usage of this filter is quite simple. In this example, we want to create a
-filter which reverses a string:
+The usage of this filter is quite simple.
+In this example, we want to create a filter which reverses a string:
```php
$filter = new Laminas\Filter\Callback('strrev');
@@ -338,9 +326,8 @@ print $filter->filter('Hello!');
// returns "!olleH"
```
-As you can see it's really simple to use a callback to define custom filters. It
-is also possible to use a method, which is defined within a class, by giving an
-array as the callback:
+As you can see it's really simple to use a callback to define custom filters.
+It is also possible to use a method, which is defined within a class, by giving an array as the callback:
```php
class MyClass
@@ -366,19 +353,16 @@ $filter = new Laminas\Filter\Callback(MyClass::class);
print $filter->filter('Hello!');
```
-To get the actual set callback use `getCallback()` and to set another callback
-use `setCallback()`.
+To get the actual set callback use `getCallback()` and to set another callback use `setCallback()`.
> ### Possible Exceptions
>
-> You should note that defining a callback method which can not be called will
-> raise an exception.
+> You should note that defining a callback method which can not be called will raise an exception.
### Default Parameters within a Callback
-It is also possible to define default parameters, which are given to the called
-method as an array when the filter is executed. This array will be concatenated
-with the value which will be filtered.
+It is also possible to define default parameters, which are given to the called method as an array when the filter is executed.
+This array will be concatenated with the value which will be filtered.
```php
$filter = new Laminas\Filter\Callback([
@@ -402,9 +386,10 @@ These two filters are capable of compressing and decompressing strings, files, a
The following options are supported for `Laminas\Filter\Compress` and `Laminas\Filter\Decompress`:
-- `adapter`: The compression adapter which should be used. It defaults to `Gz`.
+- `adapter`: The compression adapter which should be used.
+It defaults to `Gz`.
- `options`: Additional options which are given to the adapter at initiation.
- Each adapter supports its own options.
+Each adapter supports its own options.
### Supported Compression Adapters
@@ -417,23 +402,20 @@ The following compression formats are supported by their own adapter:
- **Lzf**
- **Rar**
-Each compression format has different capabilities as described below. All
-compression filters may be used in approximately the same ways, and differ
-primarily in the options available and the type of compression they offer (both
-algorithmically as well as string vs. file vs. directory)
+Each compression format has different capabilities as described below.
+All compression filters may be used in approximately the same ways, and differ primarily in the options available and the type of compression they offer (both algorithmically as well as string vs. file vs. directory)
### Generic Handling
-To create a compression filter, you need to select the compression format you want to use. The
-following example takes the **Bz2** adapter. Details for all other adapters are described after
-this section.
+To create a compression filter, you need to select the compression format you want to use.
+The following example takes the **Bz2** adapter.
+Details for all other adapters are described after this section.
The two filters are basically identical, in that they utilize the same backends.
`Laminas\Filter\Compress` should be used when you wish to compress items, and `Laminas\Filter\Decompress`
should be used when you wish to decompress items.
-For instance, if we want to compress a string, we have to initialize `Laminas\Filter\Compress` and
-indicate the desired adapter:
+For instance, if we want to compress a string, we have to initialize `Laminas\Filter\Compress` and indicate the desired adapter:
```php
$filter = new Laminas\Filter\Compress('Bz2');
@@ -441,10 +423,8 @@ $filter = new Laminas\Filter\Compress('Bz2');
To use a different adapter, you simply specify it to the constructor.
-You may also provide an array of options or a `Traversable` object. If you do,
-provide minimally the key "adapter", and then either the key "options" or
-"adapterOptions", both of which should be an array of options to provide to the
-adapter on instantiation.
+You may also provide an array of options or a `Traversable` object.
+If you do, provide minimally the key "adapter", and then either the key "options" or "adapterOptions", both of which should be an array of options to provide to the adapter on instantiation.
```php
$filter = new Laminas\Filter\Compress([
@@ -466,8 +446,8 @@ filter instead:
$filter = new Laminas\Filter\Decompress('Bz2');
```
-To get the compressed string, we have to give the original string. The filtered value is the
-compressed version of the original string.
+To get the compressed string, we have to give the original string.
+The filtered value is the compressed version of the original string.
```php
$filter = new Laminas\Filter\Compress('Bz2');
@@ -475,8 +455,7 @@ $compressed = $filter->filter('Uncompressed string');
// Returns the compressed string
```
-Decompression works in reverse, accepting the compressed string, and returning
-the original:
+Decompression works in reverse, accepting the compressed string, and returning the original:
```php
$filter = new Laminas\Filter\Decompress('Bz2');
@@ -486,14 +465,14 @@ $compressed = $filter->filter('Compressed string');
> ### Note on String Compression
>
-> Not all adapters support string compression. Compression formats like **Rar**
-> can only handle files and directories. For details, consult the section for
-> the adapter you wish to use.
+> Not all adapters support string compression.
+> Compression formats like **Rar** can only handle files and directories.
+> For details, consult the section for the adapter you wish to use.
### Creating an Archive
-Creating an archive file works almost the same as compressing a string. However, in this case we
-need an additional parameter which holds the name of the archive we want to create.
+Creating an archive file works almost the same as compressing a string.
+However, in this case we need an additional parameter which holds the name of the archive we want to create.
```php
$filter = new Laminas\Filter\Compress([
@@ -506,8 +485,7 @@ $compressed = $filter->filter('Uncompressed string');
// Returns true on success, and creates the archive file
```
-In the above example, the uncompressed string is compressed, and is then written
-into the given archive file.
+In the above example, the uncompressed string is compressed, and is then written into the given archive file.
> ### Existing Archives will be overwritten
>
@@ -527,9 +505,8 @@ $compressed = $filter->filter('C:\temp\compressme.txt');
// Returns true on success and creates the archive file
```
-You may also specify a directory instead of a filename. In this case the whole
-directory with all its files and subdirectories will be compressed into the
-archive:
+You may also specify a directory instead of a filename.
+In this case the whole directory with all its files and subdirectories will be compressed into the archive:
```php
$filter = new Laminas\Filter\Compress([
@@ -551,8 +528,8 @@ $compressed = $filter->filter('C:\temp\somedir');
### Decompressing an Archive
-Decompressing an archive file works almost like compressing it. You must specify either the
-`archive` parameter, or give the filename of the archive when you decompress the file.
+Decompressing an archive file works almost like compressing it.
+You must specify either the `archive` parameter, or give the filename of the archive when you decompress the file.
```php
$filter = new Laminas\Filter\Decompress('Bz2');
@@ -560,8 +537,8 @@ $decompressed = $filter->filter('filename.bz2');
// Returns true on success and decompresses the archive file
```
-Some adapters support decompressing the archive into another subdirectory. In
-this case you can set the `target` parameter:
+Some adapters support decompressing the archive into another subdirectory.
+In this case you can set the `target` parameter:
```php
$filter = new Laminas\Filter\Decompress([
@@ -593,12 +570,12 @@ This adapter makes use of PHP's Bz2 extension.
To customize compression, this adapter supports the following options:
- `archive`: This parameter sets the archive file which should be used or created.
-- `blocksize`: This parameter sets the blocksize to use. It can be from '0' to
- '9'. The default value is '4'.
+- `blocksize`: This parameter sets the blocksize to use.
+It can be from '0' to '9'.
+The default value is '4'.
-All options can be set at instantiation or by using a related method; for example, the related
-methods for 'blocksize' are `getBlocksize()` and `setBlocksize()`. You can also use the
-`setOptions()` method, which accepts an array of all options.
+All options can be set at instantiation or by using a related method; for example, the related methods for 'blocksize' are `getBlocksize()` and `setBlocksize()`.
+You can also use the `setOptions()` method, which accepts an array of all options.
### Gz Adapter
@@ -613,14 +590,16 @@ This adapter makes use of PHP's Zlib extension.
To customize the compression this adapter supports the following options:
- `archive`: This parameter sets the archive file which should be used or created.
-- `level`: This compression level to use. It can be from '0' to '9'. The default
- value is '9'.
-- `mode`: There are two supported modes. `compress` and `deflate`. The default
- value is `compress`.
+- `level`: This compression level to use.
+It can be from '0' to '9'.
+The default value is '9'.
+- `mode`: There are two supported modes.
+`compress` and `deflate`.
+The default value is `compress`.
-All options can be set at initiation or by using a related method. For example, the related methods
-for `level` are `getLevel()` and `setLevel()`. You can also use the `setOptions()` method which
-accepts an array of all options.
+All options can be set at initiation or by using a related method.
+For example, the related methods for `level` are `getLevel()` and `setLevel()`.
+You can also use the `setOptions()` method which accepts an array of all options.
### Lzf Adapter
@@ -659,10 +638,8 @@ This adapter makes use of PHP's Rar extension.
> ### Rar Compression not supported
>
-> Due to restrictions with the Rar compression format, there is no compression
-> available for free. When you want to compress files into a new Rar archive,
-> you must provide a callback to the adapter that can invoke a Rar compression
-> program.
+> Due to restrictions with the Rar compression format, there is no compression available for free.
+> When you want to compress files into a new Rar archive, you must provide a callback to the adapter that can invoke a Rar compression program.
To customize compression, this adapter supports the following options:
@@ -671,9 +648,9 @@ To customize compression, this adapter supports the following options:
- `password`: The password which has to be used for decompression.
- `target`: The target where the decompressed files will be written to.
-All options can be set at instantiation or by using a related method. For example, the related
-methods for `target` are `getTarget()` and `setTarget()`. You can also use the `setOptions()` method
-which accepts an array of all options.
+All options can be set at instantiation or by using a related method.
+For example, the related methods for `target` are `getTarget()` and `setTarget()`.
+You can also use the `setOptions()` method which accepts an array of all options.
### Tar Adapter
@@ -691,21 +668,19 @@ This adapter makes use of PEAR's `Archive_Tar` component.
To customize compression, this adapter supports the following options:
- `archive`: This parameter sets the archive file which should be used or created.
-- `mode`: A mode to use for compression. Supported are either `NULL`, which
- means no compression at all; `Gz`, which makes use of PHP's Zlib extension;
- and `Bz2`, which makes use of PHP's Bz2 extension. The default value is `NULL`.
+- `mode`: A mode to use for compression.
+Supported are either `NULL`, which means no compression at all; `Gz`, which makes use of PHP's Zlib extension; and `Bz2`, which makes use of PHP's Bz2 extension.
+The default value is `NULL`.
- `target`: The target where the decompressed files will be written to.
-All options can be set at instantiation or by using a related method. For
-example, the related methods for `target` are `getTarget()` and `setTarget()`.
-You can also use the `setOptions()` method which accepts an array of all
-options.
+All options can be set at instantiation or by using a related method.
+For example, the related methods for `target` are `getTarget()` and `setTarget()`.
+You can also use the `setOptions()` method which accepts an array of all options.
> ### Directory Usage
>
-> When compressing directories with Tar, the complete file path is used. This
-> means that created Tar files will not only have the subdirectory, but the
-> complete path for the compressed file.
+> When compressing directories with Tar, the complete file path is used.
+> This means that created Tar files will not only have the subdirectory, but the complete path for the compressed file.
### Zip Adapter
@@ -727,9 +702,9 @@ To customize compression, this adapter supports the following options:
- `archive`: This parameter sets the archive file which should be used or created.
- `target`: The target where the decompressed files will be written to.
-All options can be set at instantiation or by using a related method. For example, the related
-methods for `target` are `getTarget()` and `setTarget()`. You can also use the `setOptions()` method
-which accepts an array of all options.
+All options can be set at instantiation or by using a related method.
+For example, the related methods for `target` are `getTarget()` and `setTarget()`.
+You can also use the `setOptions()` method which accepts an array of all options.
## DenyList
@@ -737,8 +712,8 @@ TIP: **New Feature**
Available since version 2.12.0
Previously known as `Blacklist`.
-This filter will return `null` if the value being filtered is present in the filter's list of
-values. If the value is not present, it will return that value.
+This filter will return `null` if the value being filtered is present in the filter's list of values.
+If the value is not present, it will return that value.
For the opposite functionality, see the [`AllowList` filter](#allowlist).
@@ -818,9 +793,8 @@ These filters were deprecated in version 2.24.0 and will be removed in version 3
You are encouraged to implement your own encryption or decryption filters by implementing `FilterInterface` around a dedicated crypto library.
See [Writing Filters](writing-filters.md)
-These filters allow encrypting and decrypting any given string; they do so via
-the use of adapters. Included adapters support `Laminas\Crypt\BlockCipher` and
-PHP's OpenSSL extension.
+These filters allow encrypting and decrypting any given string; they do so via the use of adapters.
+Included adapters support `Laminas\Crypt\BlockCipher` and PHP's OpenSSL extension.
### Supported Options
@@ -830,46 +804,39 @@ The following options are supported for `Laminas\Filter\Encrypt` and
#### General Options
- `adapter`: This sets the encryption adapter to use.
-- `compression`: If the encrypted value should be compressed. Default is no
- compression.
+- `compression`: If the encrypted value should be compressed.
+Default is no compression.
#### BlockCipher Options
-- `algorithm`: The algorithm to use with `Laminas\Crypt\Symmetric\Mcrypt` (use the
- the `getSupportedAlgorithms()` method of that class to determine what is
- supported). If not set, it defaults to `aes`, the Advanced Encryption Standard
- (see the [laminas-crypt BlockCipher documentation](https://docs.laminas.dev/laminas-crypt/block-cipher/)
- for details).
-- `key`: The encryption key with which the input will be encrypted. You need the
- same key for decryption.
-- `mode`: The encryption mode to use. It should be a
- [valid PHP mcrypt modes](http://php.net/manual/en/mcrypt.constants.php).
- If not set, it defaults to 'cbc'.
-- `mode_directory`: The directory where the mode can be found. If not set, it
- defaults to the path set within the `Mcrypt` extension.
-- `vector`: The initialization vector which shall be used. If not set, it will
- be a random vector.
+- `algorithm`: The algorithm to use with `Laminas\Crypt\Symmetric\Mcrypt` (use the the `getSupportedAlgorithms()` method of that class to determine what is supported).
+If not set, it defaults to `aes`, the Advanced Encryption Standard (see the [laminas-crypt BlockCipher documentation](https://docs.laminas.dev/laminas-crypt/block-cipher/) for details).
+- `key`: The encryption key with which the input will be encrypted.
+You need the same key for decryption.
+- `mode`: The encryption mode to use.
+It should be a [valid PHP mcrypt modes](http://php.net/manual/en/mcrypt.constants.php).
+If not set, it defaults to 'cbc'.
+- `mode_directory`: The directory where the mode can be found.
+If not set, it defaults to the path set within the `Mcrypt` extension.
+- `vector`: The initialization vector which shall be used.
+If not set, it will be a random vector.
#### OpenSSL Options
-- `envelope`: The encrypted envelope key from the user who encrypted the
- content. You can either provide the path and filename of the key file, or just
- the content of the key file itself. When the `package` option has been set,
- then you can omit this parameter.
+- `envelope`: The encrypted envelope key from the user who encrypted the content.
+You can either provide the path and filename of the key file, or just the content of the key file itself.
+When the `package` option has been set, then you can omit this parameter.
- `package`: If the envelope key should be packed with the encrypted value.
- Default is `FALSE`.
-- `private`: The private key to use for encrypting the content. You can either
- provide the path and filename of the key file, or just the content of the key
- file itself.
-- `public`: The public key of the user for whom you want to provide the
- encrypted content. You can either provide the path and filename of the key
- file, or just the content of the key file itself.
+Default is `FALSE`.
+- `private`: The private key to use for encrypting the content.
+You can either provide the path and filename of the key file, or just the content of the key file itself.
+- `public`: The public key of the user for whom you want to provide the encrypted content.
+You can either provide the path and filename of the key file, or just the content of the key file itself.
### Adapter Usage
-As these two encryption methodologies work completely different, the usage
-of the adapters differ. You have to select the adapter you want to use when
-initiating the filter.
+As these two encryption methodologies work completely different, the usage of the adapters differ.
+You have to select the adapter you want to use when initiating the filter.
```php
// Use the BlockCipher adapter
@@ -879,8 +846,7 @@ $filter1 = new Laminas\Filter\Encrypt(['adapter' => 'BlockCipher']);
$filter2 = new Laminas\Filter\Encrypt(['adapter' => 'openssl']);
```
-To set another adapter, you can use `setAdapter()`; `getAdapter()` will return
-the currently composed adapter.
+To set another adapter, you can use `setAdapter()`; `getAdapter()` will return the currently composed adapter.
```php
// Use the OpenSSL adapter
@@ -895,9 +861,7 @@ $filter->setAdapter('openssl');
### Encryption with BlockCipher
-To encrypt a string using the `BlockCipher` adapter, you have to specify the
-encryption key by either calling the `setKey()` method or passing it to the
-constructor.
+To encrypt a string using the `BlockCipher` adapter, you have to specify the encryption key by either calling the `setKey()` method or passing it to the constructor.
```php
// Use the default AES encryption algorithm
@@ -938,14 +902,11 @@ var_dump($filter->getEncryption());
> ### Default BlockCipher Algorithm
>
-> The `BlockCipher` adapter uses the [Mcrypt](http://php.net/mcrypt) extension
-> by default. That means you will need to install the Mcrypt module in your PHP
-> environment.
+> The `BlockCipher` adapter uses the [Mcrypt](http://php.net/mcrypt) extension by default.
+> That means you will need to install the Mcrypt module in your PHP environment.
-If you don't specify an initialization Vector (salt or iv), the `BlockCipher` will
-generate a random value during each encryption. If you try to execute the
-following code, the output will always be different (note that even if the output
-is always different, you can still decrypt it using the same key).
+If you don't specify an initialization Vector (salt or iv), the `BlockCipher` will generate a random value during each encryption.
+If you try to execute the following code, the output will always be different (note that even if the output is always different, you can still decrypt it using the same key).
```php
$key = 'encryption key';
@@ -959,9 +920,8 @@ for ($i = 0; $i < 10; $i++) {
}
```
-If you want to obtain the same output, you need to specify a fixed vector, using
-the `setVector()` method. This following example always produces the same
-encryption output:
+If you want to obtain the same output, you need to specify a fixed vector, using the `setVector()` method.
+This following example always produces the same encryption output:
```php
// use the default adapter that is BlockCipher
@@ -977,17 +937,15 @@ printf("%s\n", $filter->filter('message'));
> ### Use different Vectors
>
-> For security purposes, it's always better to use a different vector on each
-> encryption. We suggest using `setVector()` only in exceptional circumstances.
+> For security purposes, it's always better to use a different vector on each encryption.
+> We suggest using `setVector()` only in exceptional circumstances.
### Decryption with BlockCipher
-For decrypting content previously encrypted with `BlockCipher`, you need to use
-the same options used for encryption.
+For decrypting content previously encrypted with `BlockCipher`, you need to use the same options used for encryption.
If you used only the encryption key, you can just use it to decrypt the content.
-As soon as you have provided all options, decryption works the same as
-encryption.
+As soon as you have provided all options, decryption works the same as encryption.
```php
$content = '04636a6cb8276fad0787a2e187803b6557f77825d5ca6ed4392be702b9754bb3MTIzNDU2Nzg5MDEyMzQ1NgZ+zPwTGpV6gQqPKECinig=';
@@ -1000,17 +958,13 @@ printf("Decrypt: %s\n", $filter->filter($content));
// Decrypt: message
```
-Note that even if we did not specify the same vector, the `BlockCipher` is able
-to decrypt the message because the vector is stored in the encryption string
-itself (note that the vector can be stored in plaintext; it is not a secret, and
-only used to improve the randomness of the encryption algorithm).
+Note that even if we did not specify the same vector, the `BlockCipher` is able to decrypt the message because the vector is stored in the encryption string itself (note that the vector can be stored in plaintext; it is not a secret, and only used to improve the randomness of the encryption algorithm).
### Encryption with OpenSSL
-If you have installed the `OpenSSL` extension, you can also use the `OpenSSL`
-adapter. You can get or set the public key either during instantiation, or later
-via the `setPublicKey()` method. The private key can also be set after-the-fact
-via the `setPrivateKey()` method.
+If you have installed the `OpenSSL` extension, you can also use the `OpenSSL` adapter.
+You can get or set the public key either during instantiation, or later via the `setPublicKey()` method.
+The private key can also be set after-the-fact via the `setPrivateKey()` method.
```php
// Use openssl and provide a private key
@@ -1027,8 +981,7 @@ $filter->setPublicKey('/public/key/path/public.pem');
>
> The `OpenSSL` adapter will not work with invalid or missing keys.
-When you want to decode content encoded with a passphrase, you will not only
-need the public key, but also the passphrase:
+When you want to decode content encoded with a passphrase, you will not only need the public key, but also the passphrase:
```php
// Use openssl and provide a private key
@@ -1040,12 +993,10 @@ $filter = new Laminas\Filter\Encrypt([
]);
```
-When providing the encrypted content to the recipient, you will also need to
-ensure they have the passphrase and the envelope keys so they may decrypt the
-message. You can get the envelope keys using the `getEnvelopeKey()` method:
+When providing the encrypted content to the recipient, you will also need to ensure they have the passphrase and the envelope keys so they may decrypt the message.
+You can get the envelope keys using the `getEnvelopeKey()` method:
-A complete example for encrypting content with `OpenSSL` looks like the
-following:
+A complete example for encrypting content with `OpenSSL` looks like the following:
```php
// Use openssl and provide a private key
@@ -1065,13 +1016,11 @@ print $encrypted;
### Simplified usage with OpenSSL
-As noted in the previous section, you need to provide the envelope key to the
-recipient in order for them to decrypt the message. This adds complexity,
-particularly if you are encrypting multiple values.
+As noted in the previous section, you need to provide the envelope key to the recipient in order for them to decrypt the message.
+This adds complexity, particularly if you are encrypting multiple values.
-To simplify usage, you can set the `package` option to `TRUE` when creating your
-`Encrypt` instance (the default value is `FALSE`). This will return a value
-containing both the encrypted message *and* the envelope key:
+To simplify usage, you can set the `package` option to `TRUE` when creating your `Encrypt` instance (the default value is `FALSE`).
+This will return a value containing both the encrypted message *and* the envelope key:
```php
// Use openssl and provide a private key
@@ -1088,16 +1037,15 @@ print $encrypted;
// For decryption look at the Decrypt filter
```
-Now the returned value contains the encrypted value and the envelope. You don't
-need to fetch the envelope key separately.
+Now the returned value contains the encrypted value and the envelope.
+You don't need to fetch the envelope key separately.
-However, there is one negative aspect to this: the encrypted value can now only
-be decrypted by using `Laminas\Filter\Encrypt`.
+However, there is one negative aspect to this: the encrypted value can now only be decrypted by using `Laminas\Filter\Encrypt`.
### Compressing Content
-Based on the original value, the encrypted value can be a very large string. To
-reduce the value, `Laminas\Filter\Encrypt` allows the usage of compression.
+Based on the original value, the encrypted value can be a very large string.
+To reduce the value, `Laminas\Filter\Encrypt` allows the usage of compression.
The `compression` option can either be set to the name of a compression adapter,
or to an array which sets all required options for the compression adapter.
@@ -1130,9 +1078,7 @@ $filter2 = new Laminas\Filter\Encrypt([
### Decryption with OpenSSL
-Decryption with `OpenSSL` follows the same patterns as for encryption, with one
-difference: you must have all data, including the envelope key, from the person
-who encrypted the content.
+Decryption with `OpenSSL` follows the same patterns as for encryption, with one difference: you must have all data, including the envelope key, from the person who encrypted the content.
As an example:
@@ -1163,8 +1109,7 @@ $filter->setEnvelopeKey('/key/from/encoder/envelope_key.pem');
Finally, you can decode the content.
-Our complete example for decrypting the previously encrypted content looks like
-this:
+Our complete example for decrypting the previously encrypted content looks like this:
```php
// Use openssl and provide a private key
@@ -1185,7 +1130,8 @@ print $decrypted;
This filter will ensure that, given a string that looks like a URI with a host-name and scheme, the scheme will be forced to `https` by default, or any other arbitrary scheme provided as an option.
-Any value that cannot be identified as an URI to begin with, will be returned un-filtered. Furthermore, URI parsing is rudimentary so for reliable results, you should ensure that the input is a valid URI prior to filtering.
+Any value that cannot be identified as an URI to begin with, will be returned un-filtered.
+Furthermore, URI parsing is rudimentary so for reliable results, you should ensure that the input is a valid URI prior to filtering.
### Supported Options
@@ -1209,24 +1155,21 @@ 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
- "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
- 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.
+- `quotestyle`: Equivalent to the PHP `htmlentities()` native function parameter `quote_style`.
+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 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
@@ -1238,8 +1181,8 @@ print $filter->filter('<');
### Quote Style
-`Laminas\Filter\HtmlEntities` allows changing the quote style used. This can be useful when you want to
-leave double, single, or both types of quotes un-filtered.
+`Laminas\Filter\HtmlEntities` allows changing the quote style used.
+This can be useful when you want to leave double, single, or both types of quotes un-filtered.
```php
$filter = new Laminas\Filter\HtmlEntities(['quotestyle' => ENT_QUOTES]);
@@ -1248,8 +1191,8 @@ $input = "A 'single' and " . '"double"';
print $filter->filter($input);
```
-The above example returns `A 'single' and "double"`. Notice
-that 'single' as well as "double" quotes are filtered.
+The above example returns `A 'single' and "double"`.
+Notice that 'single' as well as "double" quotes are filtered.
```php
$filter = new Laminas\Filter\HtmlEntities(['quotestyle' => ENT_COMPAT]);
@@ -1258,8 +1201,8 @@ $input = "A 'single' and " . '"double"';
print $filter->filter($input);
```
-The above example returns `A 'single' and "double"`. Notice that
-"double" quotes are filtered while 'single' quotes are not altered.
+The above example returns `A 'single' and "double"`.
+Notice that "double" quotes are filtered while 'single' quotes are not altered.
```php
$filter = new Laminas\Filter\HtmlEntities(['quotestyle' => ENT_NOQUOTES]);
@@ -1268,15 +1211,13 @@ $input = "A 'single' and " . '"double"';
print $filter->filter($input);
```
-The above example returns `A 'single' and "double"`. Notice that neither
-"double" or 'single' quotes are altered.
+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`.
+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();
@@ -1286,9 +1227,9 @@ 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.
+`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();
@@ -1297,9 +1238,8 @@ $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`.
+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();
@@ -1348,19 +1288,17 @@ This will return '-4'.
### Migration from 2.0-2.3 to 2.4+
-Version 2.4 adds support for PHP 7. In PHP 7, `int` is a reserved keyword, which required renaming
-the `Int` filter. If you were using the `Int` filter directly previously, you will now receive an
-`E_USER_DEPRECATED` notice on instantiation. Please update your code to refer to the `ToInt` class
-instead.
+Version 2.4 adds support for PHP 7.
+In PHP 7, `int` is a reserved keyword, which required renaming the `Int` filter.
+If you were using the `Int` filter directly previously, you will now receive an `E_USER_DEPRECATED` notice on instantiation.
+Please update your code to refer to the `ToInt` class instead.
-Users pulling their `Int` filter instance from the filter plugin manager receive a `ToInt` instance
-instead starting in 2.4.0.
+Users pulling their `Int` filter instance from the filter plugin manager receive a `ToInt` instance instead starting in 2.4.0.
## ToNull
-This filter will change the given input to be `NULL` if it meets specific
-criteria. This is often necessary when you work with databases and want to have
-a `NULL` value instead of a boolean or any other type.
+This filter will change the given input to be `NULL` if it meets specific criteria.
+This is often necessary when you work with databases and want to have a `NULL` value instead of a boolean or any other type.
### Supported Options
@@ -1380,16 +1318,14 @@ $result = $filter->filter($value);
// returns null instead of the empty string
```
-This means that without providing any configuration, `Laminas\Filter\ToNull` will
-accept all input types and return `NULL` in the same cases as `empty()`.
+This means that without providing any configuration, `Laminas\Filter\ToNull` will accept all input types and return `NULL` in the same cases as `empty()`.
Any other value will be returned as is, without any changes.
### Changing the Default Behavior
-Sometimes it's not enough to filter based on `empty()`. Therefore
-`Laminas\Filter\ToNull` allows you to configure which types will be converted, and
-which not.
+Sometimes it's not enough to filter based on `empty()`.
+Therefore `Laminas\Filter\ToNull` allows you to configure which types will be converted, and which not.
The following types can be handled:
@@ -1399,11 +1335,12 @@ The following types can be handled:
- `float`: Converts an float `0.0` value to `NULL`.
- `string`: Converts an empty string `''` to `NULL`.
- `zero`: Converts a string containing the single character zero (`'0'`) to `NULL`.
-- `all`: Converts all above types to `NULL`. (This is the default behavior.)
+- `all`: Converts all above types to `NULL`.
+(This is the default behavior.)
-There are several ways to select which of the above types are filtered. You can
-give one or multiple types and add them, you can give an array, you can use
-constants, or you can give a textual string. See the following examples:
+There are several ways to select which of the above types are filtered.
+You can give one or multiple types and add them, you can give an array, you can use constants, or you can give a textual string.
+See the following examples:
```php
// converts false to null
@@ -1427,15 +1364,15 @@ $filter = new Laminas\Filter\ToNull([
]);
```
-You can also give a `Traversable` or an array to set the wished types. To set
-types afterwards use `setType()`.
+You can also give a `Traversable` or an array to set the wished types.
+To set types afterwards use `setType()`.
### Migration from 2.0-2.3 to 2.4+
-Version 2.4 adds support for PHP 7. In PHP 7, `null` is a reserved keyword, which required renaming
-the `Null` filter. If you were using the `Null` filter directly previously, you will now receive an
-`E_USER_DEPRECATED` notice on instantiation. Please update your code to refer to the `ToNull` class
-instead.
+Version 2.4 adds support for PHP 7.
+In PHP 7, `null` is a reserved keyword, which required renaming the `Null` filter.
+If you were using the `Null` filter directly previously, you will now receive an `E_USER_DEPRECATED` notice on instantiation.
+Please update your code to refer to the `ToNull` class instead.
Users pulling their `Null` filter instance from the filter plugin manager receive a `ToNull`
instance instead starting in 2.4.0.
@@ -1463,12 +1400,10 @@ $filter->filter(['muppet' => 'Kermit']); // ['muppet' => 'Kermit']
## NumberFormat
-The `NumberFormat` filter can be used to return locale-specific number and percentage strings. It
-extends the `NumberParse` filter, which acts as wrapper for the `NumberFormatter` class within the
-Internationalization extension (Intl).
+The `NumberFormat` filter can be used to return locale-specific number and percentage strings.
+It extends the `NumberParse` filter, which acts as wrapper for the `NumberFormatter` class within the Internationalization extension (Intl).
-This filter is part of the laminas-i18n package; you will need to include that
-package in your application to use it.
+This filter is part of the laminas-i18n package; you will need to include that package in your application to use it.
### Supported Options
@@ -1478,21 +1413,17 @@ The following options are supported for `NumberFormat`:
NumberFormat([ string $locale [, int $style [, int $type ]]])
```
-- `$locale`: (Optional) Locale in which the number would be formatted (locale
- name, e.g. `en_US`). If unset, it will use the default locale
- (`Locale::getDefault()`). Methods for getting/setting the locale are also
- available: `getLocale()` and `setLocale()`.
+- `$locale`: (Optional) Locale in which the number would be formatted (locale name, e.g. `en_US`).
+If unset, it will use the default locale (`Locale::getDefault()`).
+Methods for getting/setting the locale are also available: `getLocale()` and `setLocale()`.
-- `$style`: (Optional) Style of the formatting, one of the
- [format style constants](http://www.php.net/manual/class.numberformatter.php#intl.numberformatter-constants.unumberformatstyle).
- If unset, it will use `NumberFormatter::DEFAULT_STYLE` as the default style.
- Methods for getting/setting the format style are also available: `getStyle()`
- and `setStyle()`.
+- `$style`: (Optional) Style of the formatting, one of the [format style constants](http://www.php.net/manual/class.numberformatter.php#intl.numberformatter-constants.unumberformatstyle).
+If unset, it will use `NumberFormatter::DEFAULT_STYLE` as the default style.
+Methods for getting/setting the format style are also available: `getStyle()` and `setStyle()`.
-- `$type`: (Optional) The [formatting type](http://www.php.net/manual/class.numberformatter.php#intl.numberformatter-constants.types)
- to use. If unset, it will use `NumberFormatter::TYPE_DOUBLE` as the default
- type. Methods for getting/setting the format type are also available:
- `getType()` and `setType()`.
+- `$type`: (Optional) The [formatting type](http://www.php.net/manual/class.numberformatter.php#intl.numberformatter-constants.types) to use.
+If unset, it will use `NumberFormatter::TYPE_DOUBLE` as the default type.
+Methods for getting/setting the format type are also available: `getType()` and `setType()`.
### Basic Usage
@@ -1512,12 +1443,10 @@ echo $filter->filter(0.00123456789);
## NumberParse
-The `NumberParse` filter can be used to parse a number from a string. It acts as
-a wrapper for the `NumberFormatter` class within the Internationalization
-extension (Intl).
+The `NumberParse` filter can be used to parse a number from a string.
+It acts as a wrapper for the `NumberFormatter` class within the Internationalization extension (Intl).
-This filter is part of the laminas-i18n package; you will need to include that
-package in your application to use it.
+This filter is part of the laminas-i18n package; you will need to include that package in your application to use it.
### Supported Options
@@ -1527,21 +1456,17 @@ The following options are supported for `NumberParse`:
NumberParse([ string $locale [, int $style [, int $type ]]])
```
-- `$locale`: (Optional) Locale in which the number would be parsed (locale name,
- e.g. `en_US`). If unset, it will use the default locale
- (`Locale::getDefault()`). Methods for getting/setting the locale are also
- available: `getLocale()` and `setLocale()`.
+- `$locale`: (Optional) Locale in which the number would be parsed (locale name, e.g. `en_US`).
+If unset, it will use the default locale (`Locale::getDefault()`).
+Methods for getting/setting the locale are also available: `getLocale()` and `setLocale()`.
-- `$style`: (Optional) Style of the parsing, one of the
- [format style constants](http://www.php.net/manual/class.numberformatter.php#intl.numberformatter-constants.unumberformatstyle).
- If unset, it will use `NumberFormatter::DEFAULT_STYLE` as the default style.
- Methods for getting/setting the parse style are also available: `getStyle()`
- and `setStyle()`.
+- `$style`: (Optional) Style of the parsing, one of the [format style constants](http://www.php.net/manual/class.numberformatter.php#intl.numberformatter-constants.unumberformatstyle).
+If unset, it will use `NumberFormatter::DEFAULT_STYLE` as the default style.
+Methods for getting/setting the parse style are also available: `getStyle()` and `setStyle()`.
-- `$type`: (Optional) The [parsing type](http://www.php.net/manual/class.numberformatter.php#intl.numberformatter-constants.types)
- to use. If unset, it will use `NumberFormatter::TYPE_DOUBLE` as the default
- type. Methods for getting/setting the parse type are also available:
- `getType()` and `setType()`.
+- `$type`: (Optional) The [parsing type](http://www.php.net/manual/class.numberformatter.php#intl.numberformatter-constants.types) to use.
+If unset, it will use `NumberFormatter::TYPE_DOUBLE` as the default type.
+Methods for getting/setting the parse type are also available: `getType()` and `setType()`.
### Basic Usage
@@ -1561,8 +1486,7 @@ echo $filter->filter('1,23456789E-3');
## PregReplace
-`Laminas\Filter\PregReplace` performs a search using regular expressions and replaces all found
-elements.
+`Laminas\Filter\PregReplace` performs a search using regular expressions and replaces all found elements.
### Supported Options
@@ -1576,12 +1500,11 @@ The following options are supported for `Laminas\Filter\PregReplace`:
To use this filter properly, you must give both options listed above.
-The `pattern` option has to be given to set the pattern to search for. It can be
-a string for a single pattern, or an array of strings for multiple patterns.
+The `pattern` option has to be given to set the pattern to search for.
+It can be a string for a single pattern, or an array of strings for multiple patterns.
-The `replacement` option indicates the string to replace matches with, and can
-contain placeholders for matched groups from the search `pattern`. The value may
-be a string replacement, or an array of string replacements.
+The `replacement` option indicates the string to replace matches with, and can contain placeholders for matched groups from the search `pattern`.
+The value may be a string replacement, or an array of string replacements.
```php
$filter = new Laminas\Filter\PregReplace([
@@ -1594,8 +1517,7 @@ $filter->filter($input);
// returns 'Hi john!'
```
-You can also use `setPattern()` to set the pattern(s), and `setReplacement()` set
-the replacement(s).
+You can also use `setPattern()` to set the pattern(s), and `setReplacement()` set the replacement(s).
```php
$filter = new Laminas\Filter\PregReplace();
@@ -1613,8 +1535,7 @@ For more complex usage, read the
## RealPath
-This filter will resolve given links and pathnames, and returns the canonicalized
-absolute pathnames.
+This filter will resolve given links and pathnames, and returns the canonicalized absolute pathnames.
### Supported Options
@@ -1625,13 +1546,12 @@ The following options are supported for `Laminas\Filter\RealPath`:
### Basic Usage
-For any given link or pathname, its absolute path will be returned. References
-to `/./`, `/../` and extra `/` sequences in the input path will be stripped. The
-resulting path will not have any symbolic links, `/./`, or `/../` sequences.
+For any given link or pathname, its absolute path will be returned.
+References to `/./`, `/../` and extra `/` sequences in the input path will be stripped.
+The resulting path will not have any symbolic links, `/./`, or `/../` sequences.
-`Laminas\Filter\RealPath` will return `FALSE` on failure, e.g. if the file does not exist. On BSD
-systems `Laminas\Filter\RealPath` doesn't fail if only the last path component doesn't exist, while
-other systems will return `FALSE`.
+`Laminas\Filter\RealPath` will return `FALSE` on failure, e.g. if the file does not exist.
+On BSD systems `Laminas\Filter\RealPath` doesn't fail if only the last path component doesn't exist, while other systems will return `FALSE`.
```php
$filter = new Laminas\Filter\RealPath();
@@ -1643,9 +1563,8 @@ $filtered = $filter->filter($path);
### Non-Existing Paths
-Sometimes it is useful to get paths to files that do n0t exist; e.g., when you
-want to get the real path for a path you want to create. You can then either
-provide a `FALSE` `exists` value at initiation, or use `setExists()` to set it.
+Sometimes it is useful to get paths to files that do not exist; e.g., when you want to get the real path for a path you want to create.
+You can then either provide a `FALSE` `exists` value at initiation, or use `setExists()` to set it.
```php
$filter = new Laminas\Filter\RealPath(false);
@@ -1725,11 +1644,9 @@ print $filter->filter('SAMPLE');
### Handling alternate Encoding
-By default, `StringToLower` will only handle characters from the locale of your
-server; characters from other charsets will be ignored. If you have the mbstring
-extension, however, you can use the filter with other encodings. Pass the
-desired encoding when initiating the `StringToLower` filter, or use the
-`setEncoding()` method to change it.
+By default, `StringToLower` will only handle characters from the locale of your server; characters from other charsets will be ignored.
+If you have the mbstring extension, however, you can use the filter with other encodings.
+Pass the desired encoding when initiating the `StringToLower` filter, or use the `setEncoding()` method to change it.
```php
// using UTF-8
@@ -1770,8 +1687,7 @@ print $filter->filter('Sample');
### Different encoded Strings
-Like the `StringToLower` filter, this filter will only handle characters
-supported by your server locale, unless you have the mbstring extension enabled.
+Like the `StringToLower` filter, this filter will only handle characters supported by your server locale, unless you have the mbstring extension enabled.
Using different character sets works the same as with `StringToLower`.
```php
@@ -1783,16 +1699,14 @@ $filter->setEncoding('ISO-8859-1');
## StringTrim
-This filter modifies a given string such that certain characters are removed
-from the beginning and end.
+This filter modifies a given string such that certain characters are removed from the beginning and end.
### Supported Options
The following options are supported for `Laminas\Filter\StringTrim`:
-- `charlist`: List of characters to remove from the beginning and end of the
- string. If this is not set or is null, the default behavior will be invoked,
- which is to remove only whitespace from the beginning and end of the string.
+- `charlist`: List of characters to remove from the beginning and end of the string.
+If this is not set or is null, the default behavior will be invoked, which is to remove only whitespace from the beginning and end of the string.
### Basic Usage
@@ -1802,8 +1716,8 @@ $filter = new Laminas\Filter\StringTrim();
print $filter->filter(' This is (my) content: ');
```
-The above example returns `This is (my) content:`. Notice that the whitespace
-characters have been removed.
+The above example returns `This is (my) content:`.
+Notice that the whitespace characters have been removed.
### Specifying alternate Characters
@@ -1814,16 +1728,15 @@ $filter = new Laminas\Filter\StringTrim(':');
print $filter->filter(' This is (my) content:');
```
-The above example returns `This is (my) content`. Notice that the whitespace
-characters and colon are removed. You can also provide a `Traversable` or an
-array with a `charlist` key. To set the desired character list after
-instantiation, use the `setCharList()` method. `getCharList()` returns the
-current character list.
+The above example returns `This is (my) content`.
+Notice that the whitespace characters and colon are removed.
+You can also provide a `Traversable` or an array with a `charlist` key.
+To set the desired character list after instantiation, use the `setCharList()` method.
+`getCharList()` returns the current character list.
## StripNewlines
-This filter modifies a given string and removes all new line characters within
-that string.
+This filter modifies a given string and removes all new line characters within that string.
### Supported Options
@@ -1837,8 +1750,8 @@ $filter = new Laminas\Filter\StripNewlines();
print $filter->filter(' This is (my)``\n\r``content: ');
```
-The above example returns `This is (my) content:`. Notice that all newline
-characters have been removed.
+The above example returns `This is (my) content:`.
+Notice that all newline characters have been removed.
## StripTags
@@ -1846,22 +1759,19 @@ This filter can strip XML and HTML tags from given content.
> ### Laminas\\Filter\\StripTags is potentially insecure
>
-> Be warned that `Laminas\\Filter\\StripTags` should only be used to strip *all*
-> available tags. Using `Laminas\\Filter\\StripTags` to make your site secure by
-> stripping *some* unwanted tags will lead to unsecure and dangerous code,
-> including potential XSS vectors.
+> Be warned that `Laminas\\Filter\\StripTags` should only be used to strip *all* available tags.
+> Using `Laminas\\Filter\\StripTags` to make your site secure by stripping *some* unwanted tags will lead to unsecure and dangerous code, including potential XSS vectors.
>
-> For a fully secure solution that allows selected filtering of HTML tags, use
-> either Tidy or HtmlPurifier.
+> For a fully secure solution that allows selected filtering of HTML tags, use either Tidy or HtmlPurifier.
### Supported Options
The following options are supported for `Laminas\Filter\StripTags`:
-- `allowAttribs`: This option sets the attributes which are accepted. All other
- attributes are stripped from the given content.
-- `allowTags`: This option sets the tags which are accepted. All other tags will
- be stripped from; the given content.
+- `allowAttribs`: This option sets the attributes which are accepted.
+All other attributes are stripped from the given content.
+- `allowTags`: This option sets the tags which are accepted.
+All other tags will be stripped from; the given content.
### Basic Usage
@@ -1873,8 +1783,7 @@ print $filter->filter('My content');
The result will be the stripped content `My content`.
-When the content contains broken or partial tags, any content following the
-opening tag will be completely removed:
+When the content contains broken or partial tags, any content following the opening tag will be completely removed:
```php
$filter = new Laminas\Filter\StripTags();
@@ -1886,8 +1795,8 @@ The above will return `This contains`, with the rest being stripped.
### Allowing defined Tags
-`Laminas\Filter\StripTags` allows stripping all but an allowed set of tags. As an
-example, this can be used to strip all markup except for links:
+`Laminas\Filter\StripTags` allows stripping all but an allowed set of tags.
+As an example, this can be used to strip all markup except for links:
```php
$filter = new Laminas\Filter\StripTags(['allowTags' => 'a']);
@@ -1896,14 +1805,13 @@ $input = "A text with
a link";
print $filter->filter($input);
```
-The above will return `A text with a link`;
-it strips all tags but the link. By providing an array, you can specify multiple
-tags at once.
+The above will return `A text with a link`; it strips all tags but the link.
+By providing an array, you can specify multiple tags at once.
> ### Warning
>
-> Do not use this feature to secure content. This component does not replace the
-> use of a properly configured html filter.
+> Do not use this feature to secure content.
+> This component does not replace the use of a properly configured html filter.
### Allowing defined Attributes
@@ -1919,15 +1827,12 @@ $input = "A text with
a 
picture"
print $filter->filter($input);
```
-The above will return `A text with a picture`; it
-strips all tags but `![]()
`, and all attributes but `src` from those tags.By
-providing an array you can set multiple attributes at once.
+The above will return `A text with a picture`; it strips all tags but `![]()
`, and all attributes but `src` from those tags.By providing an array you can set multiple attributes at once.
### Allow specific Tags with specific Attributes
-You can also pass the tag allow list as a set of tag/attribute values. Each key
-will be an allowed tag, pointing to a list of allowed attributes for that
-tag.
+You can also pass the tag allow list as a set of tag/attribute values.
+Each key will be an allowed tag, pointing to a list of allowed attributes for that tag.
```php
$allowedElements = [
@@ -1953,7 +1858,8 @@ 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 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.
diff --git a/docs/book/v2/static-filter.md b/docs/book/v2/static-filter.md
index 5eae7260..10346af4 100644
--- a/docs/book/v2/static-filter.md
+++ b/docs/book/v2/static-filter.md
@@ -3,13 +3,10 @@
CAUTION: **Deprecated**
This filter is deprecated since version 2.15.0 and [will be removed](migration/preparing-for-v3.md#static-filter-removal) in version 3.0.
-If it is inconvenient to load a given filter class and create an instance of
-the filter, you can use `StaticFilter` with it's method `execute()` 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.
+If it is inconvenient to load a given filter class and create an instance of the filter, you can use `StaticFilter` with it's method `execute()` 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');
@@ -25,18 +22,14 @@ echo StaticFilter::execute(
);
```
-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
-create an instance of the filter and invoke it. instance of the filter object
-and calling its `filter()` method.
+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 create an instance of the filter and invoke it.
+instance of the filter object and calling its `filter()` method.
-Additionally, [filter chains](filter-chains.md) allow you to instantiate and run multiple filters
-on demand to process sets of input data.
+Additionally, [filter chains](filter-chains.md) allow you to instantiate and run multiple filters on demand to process sets of input data.
## Using custom Filters
-You can set and receive the `FilterPluginManager` for the `StaticFilter` to
-amend the standard filter classes:
+You can set and receive the `FilterPluginManager` for the `StaticFilter` to amend the standard filter classes:
```php
$pluginManager = StaticFilter::getPluginManager()
diff --git a/docs/book/v2/word.md b/docs/book/v2/word.md
index 7e1f6540..ba57f516 100644
--- a/docs/book/v2/word.md
+++ b/docs/book/v2/word.md
@@ -1,7 +1,6 @@
# Word Filters
-In addition to the standard set of filters, there are several classes specific
-to filtering word strings.
+In addition to the standard set of filters, there are several classes specific to filtering word strings.
## CamelCaseToDash
@@ -29,8 +28,8 @@ This filter modifies a given string such that `CamelCaseWords` are converted to
The following options are supported for `Laminas\Filter\Word\CamelCaseToSeparator`:
-- `separator`: A separator character. If this is not set, the default separator
- is a space.
+- `separator`: A separator character.
+If this is not set, the default separator is a space.
### Basic Usage
@@ -74,8 +73,7 @@ The above example returns `This_Is_My_Content`.
## DashToCamelCase
-This filter modifies a given string such that `words-with-dashes` are converted
-to `WordsWithDashes`.
+This filter modifies a given string such that `words-with-dashes` are converted to `WordsWithDashes`.
### Supported Options
@@ -93,15 +91,14 @@ The above example returns `ThisIsMyContent`.
## DashToSeparator
-This filter modifies a given string such that `words-with-dashes` are converted
-to `words with dashes`.
+This filter modifies a given string such that `words-with-dashes` are converted to `words with dashes`.
### Supported Options
The following options are supported for `Laminas\Filter\Word\DashToSeparator`:
-- `separator`: A separator character. If this is not set, the default separator
- is a space.
+- `separator`: A separator character.
+If this is not set, the default separator is a space.
### Basic Usage
@@ -126,8 +123,7 @@ The above example returns `this is my content`.
## DashToUnderscore
-This filter modifies a given string such that `words-with-dashes` are converted
-to `words_with_dashes`.
+This filter modifies a given string such that `words-with-dashes` are converted to `words_with_dashes`.
### Supported Options
@@ -145,15 +141,14 @@ The above example returns `this_is_my_content`.
## SeparatorToCamelCase
-This filter modifies a given string such that `words with separators` are
-converted to `WordsWithSeparators`.
+This filter modifies a given string such that `words with separators` are converted to `WordsWithSeparators`.
### Supported Options
The following options are supported for `Laminas\Filter\Word\SeparatorToCamelCase`:
-- `separator`: A separator character. If this is not set, the default separator
- is a space.
+- `separator`: A separator character.
+If this is not set, the default separator is a space.
### Basic Usage
@@ -178,15 +173,14 @@ The above example returns `ThisIsMyContent`.
## SeparatorToDash
-This filter modifies a given string such that `words with separators` are
-converted to `words-with-separators`.
+This filter modifies a given string such that `words with separators` are converted to `words-with-separators`.
### Supported Options
The following options are supported for `Laminas\Filter\Word\SeparatorToDash`:
-- `separator`: A separator character. If this is not set, the default separator
- is a space.
+- `separator`: A separator character.
+If this is not set, the default separator is a space.
### Basic Usage
@@ -211,17 +205,16 @@ The above example returns `this-is-my-content`.
## SeparatorToSeparator
-This filter modifies a given string such that `words with separators` are
-converted to `words-with-separators`.
+This filter modifies a given string such that `words with separators` are converted to `words-with-separators`.
### Supported Options
The following options are supported for `Laminas\Filter\Word\SeparatorToSeparator`:
-- `searchSeparator`: The search separator character. If this is not set, the
- default separator is a space.
-- `replaceSeparator`: The replacement separator character. If this is not set, the
- default separator is a dash (`-`).
+- `searchSeparator`: The search separator character.
+If this is not set, the default separator is a space.
+- `replaceSeparator`: The replacement separator character.
+If this is not set, the default separator is a dash (`-`).
### Basic Usage
@@ -245,8 +238,7 @@ The above example returns `this-is-my-content`.
## UnderscoreToCamelCase
-This filter modifies a given string such that `words_with_underscores` are
-converted to `WordsWithUnderscores`.
+This filter modifies a given string such that `words_with_underscores` are converted to `WordsWithUnderscores`.
### Supported Options
@@ -264,15 +256,14 @@ The above example returns `ThisIsMyContent`.
## UnderscoreToSeparator
-This filter modifies a given string such that `words_with_underscores` are
-converted to `words with underscores`.
+This filter modifies a given string such that `words_with_underscores` are converted to `words with underscores`.
### Supported Options
The following options are supported for `Laminas\Filter\Word\UnderscoreToSeparator`:
-- `separator`: A separator character. If this is not set, the default separator
- is a space.
+- `separator`: A separator character.
+If this is not set, the default separator is a space.
### Basic Usage
@@ -297,8 +288,7 @@ The above example returns `this is my content`.
## UnderscoreToDash
-This filter modifies a given string such that `words_with_underscores` are
-converted to `words-with-underscores`.
+This filter modifies a given string such that `words_with_underscores` are converted to `words-with-underscores`.
### Supported Options
diff --git a/docs/book/v2/writing-filters.md b/docs/book/v2/writing-filters.md
index 48552743..55607ca7 100644
--- a/docs/book/v2/writing-filters.md
+++ b/docs/book/v2/writing-filters.md
@@ -1,9 +1,7 @@
# Writing Filters
-`Laminas\Filter` supplies a set of commonly needed filters, but developers will
-often need to write custom filters for their particular use cases. You can do
-so by writing classes that implement `Laminas\Filter\FilterInterface`, which
-defines a single method, `filter()`.
+`Laminas\Filter` supplies a set of commonly needed filters, but developers will often need to write custom filters for their particular use cases.
+You can do so by writing classes that implement `Laminas\Filter\FilterInterface`, which defines a single method, `filter()`.
## Example