From b0ce318f87cdcd3eee49dd3ff1bf134911870ef0 Mon Sep 17 00:00:00 2001
From: George Steel <george@net-glue.co.uk>
Date: Wed, 26 Jun 2024 09:33:07 +0100
Subject: [PATCH] Document method removals and behaviour changes for individual
 validators

Signed-off-by: George Steel <george@net-glue.co.uk>
---
 docs/book/v3/migration/v2-to-v3.md | 97 +++++++++++++++++++++++++++++-
 1 file changed, 96 insertions(+), 1 deletion(-)

diff --git a/docs/book/v3/migration/v2-to-v3.md b/docs/book/v3/migration/v2-to-v3.md
index 0df266dd..d6eafcb7 100644
--- a/docs/book/v3/migration/v2-to-v3.md
+++ b/docs/book/v3/migration/v2-to-v3.md
@@ -26,10 +26,105 @@ The [`laminas-i18n`](https://docs.laminas.dev/laminas-i18n/validators/introducti
 
 ## Changes to Individual Validators
 
-### Digits
+### General Changes
+
+#### Removal of "Getters" and "Setters"
+
+In general, most validators no longer have "getters" and "setters" for options and configuration.
+
+Taking the `Regex` validator as an example, in the 2.x series, it was possible to create a regex validator and then configure it _after_ it had been constructed.
+This allows the creation of validator instances with an invalid state, or configuration.
+
+Removing getters and setters forces us to provide valid configuration of the validator instance at construction time, vastly reducing the API surface and closing off potential sources of bugs.
+
+#### Consistent Construction via an Array of Options
+
+In the 2.x series, _most_ validators accepted a range of constructor arguments, for example, a single options array, an `ArrayAccess` or `Traversable` and frequently variadic arguments of the most important configuration parameters.
+
+Generally speaking, validators now only accept associative arrays with improved documentation of exactly which options are available.
+
+### Callback
+
+The following methods have been removed:
+
+- `setCallback`
+- `getCallback`
+- `setCallbackOptions`
+- `getCallbackOptions`
+
+A new option `bind` has been added that will bind the given callback to the scope of the validator so that you can manipulate error messages from within the callback itself.
+
+The [documentation](../validators/callback.md#callbacks-and-scope) has been updated with the relevant details.
+
+### `Laminas\Validator\Digits`
 
 This validator no longer uses the Digits filter from `laminas/laminas-filter`, so its static filter property has been removed. This change is unlikely to cause any problems unless for some reason you have extended this class.
 
+### `Laminas\Validator\Explode`
+
+The following methods have been removed:
+
+- `setValidator`
+- `getValidator`
+- `setValueDelimiter`
+- `getValueDelimiter`
+- `setValidatorPluginManager`
+- `getValidatorPluginManager`
+- `setBreakOnFirstFailure`
+- `isBreakOnFirstFailure`
+
+Behaviour changes:
+
+- Non-string input will now cause a validation failure
+- The composed validator can now be specified as a FQCN
+- The constructor now only accepts an associative array
+- Error messages match the same format as other validators, i.e. `array<string, string>`
+
+### `Laminas\Validator\Regex`
+
+The following methods have been removed:
+
+- `setPattern`
+- `getPattern`
+
+Behaviour changes:
+
+- Non string input will now fail validation. Previously, scalars would be cast to string before pattern validation leading to possible bugs, for example, floating point numbers could be cast to scientific notation.
+- Now the pattern is a required option in the constructor, an invalid pattern will cause an exception during `__construct` instead of during validation.
+- The single constructor argument must now be either an associative array of options, or the regex pattern as a string.
+
+### `Laminas\Validator\StringLength`
+
+The following methods have been removed:
+
+- `setMin`
+- `getMin`
+- `setMax`
+- `getMax`
+- `getStringWrapper`
+- `setStringWrapper`
+- `getEncoding`
+- `setEncoding`
+- `getLength`
+- `setLength`
+
+Behaviour changes:
+
+- The constructor now only accepts an associative array of options.
+- Malformed multibyte input is now handled more consistently: In the event that any of the string wrappers cannot reliably detect the length of a string, an exception will be thrown.
+
+### `Laminas\Validator\Timezone`
+
+The following methods have been removed
+
+- `setType`
+
+Behaviour changes:
+
+- The constructor now only accepts an associative array of documented options
+- The `type` option can now only be one of the type constants declared on the class, i.e. `Timezone::ABBREVIATION`, `Timezone::LOCATION`, or `Timezone::ALL`
+- When validating timezone abbreviations, the check is now case-insensitive, so `CET` will pass validation when previously it did not.
+
 ## Removed Features
 
 ### `Laminas\Csrf` Validator Removal