Merge pull request #16 from gsteel/initial-docs

Initial documentation

docs/book/element/phone-number.md

@@ -0,0 +1,140 @@
+# PhoneNumber
+
+`Laminas\I18n\PhoneNumber\Form\Element\PhoneNumber` is a text input form element that automatically attaches a PhoneNumber validator.
+
+## Basic Usage
+
+This element automatically adds a `type` attribute of value `tel`.
+
+```php
+use Laminas\I18n\PhoneNumber\Form\Element\PhoneNumber;
+use Laminas\Form\Form;
+
+$phone = new PhoneNumber('number');
+$phone->setLabel('Phone Number');
+$phone->setAttributes([
+    'autocomplete' => 'tel', // 'tel-national' is also an option.
+]);
+
+$form = new Form();
+$form->add($phone);
+```
+
+Using array notation:
+
+```php
+use Laminas\I18n\PhoneNumber\Form\Element\PhoneNumber;
+use Laminas\Form\Form;
+
+$form = new Form();
+$form->add([
+    'type' => PhoneNumber::class,
+    'name' => 'phone-number',
+    'options' => [
+        'label' => 'Phone Number',
+    ],
+    'attributes' => [
+        'autocomplete' => 'tel'
+    ],
+]);
+```
+
+TIP: **Autocomplete Attribute**
+To make it easier for users to autofill valid information, the [autocomplete attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) can be used. A value of `tel` should autofill the users phone number with the country dialling code, whereas a value of `tel-national` will autofill the number without the country dialling code. For example:
+
+```php
+$form->add([
+    'type' => PhoneNumber::class,
+    'name' => 'phone-number',
+    'attributes' => [
+        'autocomplete' => 'tel' // or 'tel-national'
+    ],
+]);
+```
+
+## Available Options
+
+Along with the options relevant to all form elements such as `label`, the phone number input also allows you to pass validator options to the [phone number validator](../validators/phone-number.md):
+
+```php
+use Laminas\I18n\PhoneNumber\Form\Element\PhoneNumber;
+use Laminas\I18n\PhoneNumber\PhoneNumberValue;
+use Laminas\Form\Element\Text;
+use Laminas\Form\Form;
+
+$form = new Form();
+$form->add([
+    'type' => PhoneNumber::class,
+    'name' => 'phone-number',
+    'options' => [
+        'label' => 'Phone Number',
+        'default_country' => 'ZA',
+        'country_context' => 'country-code-field',
+        'allowed_types' => PhoneNumberValue::TYPE_MOBILE,
+    ],
+    'attributes' => [
+        'autocomplete' => 'tel-national'
+    ],
+]);
+$form->add([
+    'type' => Text::class,
+    'name' => 'country-code-field',
+    'options' => [
+        'label' => 'Country',
+    ],
+]);
+```
+
+## Public Methods
+
+The following methods are specific to the `PhoneNumber` element; all other methods
+defined by the [parent `Element` class](https://docs.laminas.dev/laminas-form/v3/element/element/#public-methods) are also
+available.
+
+### `setOptions(array $options): void`
+
+Set options for an element of type `PhoneNumber`.
+The accepted options, in addition to the inherited options of [`Laminas\Form\Element`](https://docs.laminas.dev/laminas-form/v3/element/element/) are:
+
+- `default_country`, which calls `setDefaultCountry()`
+- `country_context`, which calls `setCountryContext()`
+- `allowed_types`, which calls `setAllowedTypes()`
+
+```php
+$element->setOptions([
+    'default_country' => 'DE',
+    'country_context' => 'country-code-input-name',
+    'allowed_types' => PhoneNumberValue::TYPE_RECOMMENDED,
+])
+```
+
+### Set Default Country Code
+
+Sets the default country to validate national phone numbers against.
+
+```php
+$element->setDefaultCountry('GB');
+```
+
+### Set the Country Validation Context Key
+
+Sets the name of another input in your form that can be used to determine the country for validating national phone numbers, instead of the default country.
+
+```php
+$element->setCountryContext('the-country-code-input-name');
+```
+
+### Set the Acceptable Number Types
+
+Provide a bitmask of [phone number types](../validators/phone-number.md#limiting-acceptable-number-types) to limit the types of number that are considered valid. For example:
+
+```php
+use Laminas\I18n\PhoneNumber\PhoneNumberValue;
+
+$element->setAllowedTypes(PhoneNumberValue::TYPE_MOBILE | PhoneNumberValue::TYPE_EMERGENCY);
+```
+
+### Retrieve default Input Specification
+
+`getInputSpecification(): array` returns an [input filter specification](https://docs.laminas.dev/laminas-inputfilter/specs/), which includes the `StringTrim` filter, and a phone number validator configured with the `default_country`, `country_context`, and `allowed_types` options.
+The validator options are described in greater detail in the documentation for the [phone number validator](../validators/phone-number.md).

docs/book/filters/to-e164.md

@@ -0,0 +1,66 @@
+# ToE164
+
+The `ToE164` filter can be used to format phone numbers to [E.164 format](https://en.wikipedia.org/wiki/E.164).
+
+## Basic Usage
+
+```php
+use Laminas\I18n\CountryCode;
+use Laminas\I18n\PhoneNumber\Filter\ToE164;
+
+$country = CountryCode::fromString('GB');
+$filter  = new ToE164($country);
+
+echo $filter->filter('01234 567 890'); // "+441234567890"
+```
+
+Regardless of the configured default country code, the `ToE164` filter will still format a recognisable number for any region:
+
+```php
+use Laminas\I18n\CountryCode;
+use Laminas\I18n\PhoneNumber\Filter\ToE164;
+
+$country = CountryCode::fromString('SE');
+$filter  = new ToE164($country);
+
+echo $filter->filter('44 (0) 1234 567 890'); // "+441234567890"
+```
+
+## Changing the Default Country Code
+
+Given an already instantiated filter instance, the country code can be changed in 2 ways:
+
+- Via the `setCountryCode` method
+- Via the `setOptions` method
+
+The `setCountryCode` method accepts a `CountryCode` value object, or a 2-letter [ISO 3166 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) string:
+
+```php
+use Laminas\I18n\CountryCode;
+use Laminas\I18n\PhoneNumber\Filter\ToE164;
+
+$country = CountryCode::fromString('GB');
+$filter  = new ToE164($country);
+
+$filter->setCountryCode('FR');
+// …or
+$filter->setCountryCode(CountryCode::fromString('DE'));
+```
+
+The `setOptions` method accepts an array or iterable in the following format:
+
+```php
+$options = [
+    'country-code' => 'US',
+];
+
+$filter->setOptions($options);
+```
+
+## Filtering Invalid Data
+
+When the filter receives values that cannot be recognised as valid phone numbers, the original input is returned as-is.
+
+```php
+$filter->filter('Not a phone number'); // "Not a phone number"
+```

docs/book/filters/to-international-phone-number.md

@@ -0,0 +1,66 @@
+# ToInternationalPhoneNumber
+
+The `ToInternationalPhoneNumber` filter can be used to format phone numbers to the international format expected by the region the phone number belongs to.
+
+## Basic Usage
+
+```php
+use Laminas\I18n\CountryCode;
+use Laminas\I18n\PhoneNumber\Filter\ToInternationalPhoneNumber;
+
+$country = CountryCode::fromString('US');
+$filter  = new ToInternationalPhoneNumber($country);
+
+echo $filter->filter('(510) 123 4567'); // "+1 510-123-4567"
+```
+
+Regardless of the configured default country code, the `ToInternationalPhoneNumber` filter will still format a recognisable number for any region:
+
+```php
+use Laminas\I18n\CountryCode;
+use Laminas\I18n\PhoneNumber\Filter\ToInternationalPhoneNumber;
+
+$country = CountryCode::fromString('SE');
+$filter  = new ToInternationalPhoneNumber($country);
+
+echo $filter->filter('44 (0) 1234 567 890'); // "+44 1234 567890"
+```
+
+## Changing the Default Country Code
+
+Given an already instantiated filter instance, the country code can be changed in 2 ways:
+
+- Via the `setCountryCode` method
+- Via the `setOptions` method
+
+The `setCountryCode` method accepts a `CountryCode` value object, or a 2-letter [ISO 3166 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) string:
+
+```php
+use Laminas\I18n\CountryCode;
+use Laminas\I18n\PhoneNumber\Filter\ToInternationalPhoneNumber;
+
+$country = CountryCode::fromString('GB');
+$filter  = new ToInternationalPhoneNumber($country);
+
+$filter->setCountryCode('FR');
+// …or
+$filter->setCountryCode(CountryCode::fromString('DE'));
+```
+
+The `setOptions` method accepts an array or iterable in the following format:
+
+```php
+$options = [
+    'country-code' => 'US',
+];
+
+$filter->setOptions($options);
+```
+
+## Filtering Invalid Data
+
+When the filter receives values that cannot be recognised as valid phone numbers, the original input is returned as-is.
+
+```php
+$filter->filter('Not a phone number'); // "Not a phone number"
+```

docs/book/filters/to-national-phone-number.md

@@ -0,0 +1,66 @@
+# ToNationalPhoneNumber
+
+The `ToNationalPhoneNumber` filter can be used to format phone numbers to the national format expected by the region the phone number belongs to.  
+
+## Basic Usage
+
+```php
+use Laminas\I18n\CountryCode;
+use Laminas\I18n\PhoneNumber\Filter\ToNationalPhoneNumber;
+
+$country = CountryCode::fromString('US');
+$filter  = new ToNationalPhoneNumber($country);
+
+echo $filter->filter('+1 510 123 4567'); // "(510) 123-4567"
+```
+
+Regardless of the configured default country code, the `ToNationalPhoneNumber` filter will still format a recognisable number for any region:
+
+```php
+use Laminas\I18n\CountryCode;
+use Laminas\I18n\PhoneNumber\Filter\ToNationalPhoneNumber;
+
+$country = CountryCode::fromString('SE');
+$filter  = new ToNationalPhoneNumber($country);
+
+echo $filter->filter('+441234567890'); // "01234 567890"
+```
+
+## Changing the Default Country Code
+
+Given an already instantiated filter instance, the country code can be changed in 2 ways:
+
+- Via the `setCountryCode` method
+- Via the `setOptions` method
+
+The `setCountryCode` method accepts a `CountryCode` value object, or a 2-letter [ISO 3166 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) string:
+
+```php
+use Laminas\I18n\CountryCode;
+use Laminas\I18n\PhoneNumber\Filter\ToNationalPhoneNumber;
+
+$country = CountryCode::fromString('GB');
+$filter  = new ToNationalPhoneNumber($country);
+
+$filter->setCountryCode('FR');
+// …or
+$filter->setCountryCode(CountryCode::fromString('DE'));
+```
+
+The `setOptions` method accepts an array or iterable in the following format:
+
+```php
+$options = [
+    'country-code' => 'US',
+];
+
+$filter->setOptions($options);
+```
+
+## Filtering Invalid Data
+
+When the filter receives values that cannot be recognised as valid phone numbers, the original input is returned as-is.
+
+```php
+$filter->filter('Not a phone number'); // "Not a phone number"
+```