Merge branch 'hotfix/15' into develop

Forward port #15

doc/book/zend.i18n.filters.md

@@ -0,0 +1,174 @@
+# I18n Filters
+
+Zend Framework comes with a set of filters related to Internationalization.
+
+## 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.
+
+### Supported Options
+
+The following options are supported for `Alnum`:
+
+`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()`
+
+- `$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
+
+```php
+// Default settings, deny whitespace
+$filter = new \Zend\I18n\Filter\Alnum();
+echo $filter->filter("This is (my) content: 123");
+// Returns "Thisismycontent123"
+
+// First param in constructor is $allowWhiteSpace
+$filter = new \Zend\I18n\Filter\Alnum(true);
+echo $filter->filter("This is (my) content: 123");
+// Returns "This is my content 123"
+```
+
+> ## Note
+`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`.
+
+## Alpha
+
+The `Alpha` filter can be used to return only alphabetic characters in the unicode "letter"
+category. All other characters are suppressed.
+
+### Supported Options
+
+The following options are supported for `Alpha`:
+
+`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()`
+
+- `$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
+
+```php
+// Default settings, deny whitespace
+$filter = new \Zend\I18n\Filter\Alpha();
+echo $filter->filter("This is (my) content: 123");
+// Returns "Thisismycontent"
+
+// Allow whitespace
+$filter = new \Zend\I18n\Filter\Alpha(true);
+echo $filter->filter("This is (my) content: 123");
+// Returns "This is my content "
+```
+
+> ## Note
+`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`.
+
+## 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).
+
+### Supported Options
+
+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()`
+
+- `$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()`
+
+### Basic Usage
+
+```php
+$filter = new \Zend\I18n\Filter\NumberFormat("de_DE");
+echo $filter->filter(1234567.8912346);
+// Returns "1.234.567,891"
+
+$filter = new \Zend\I18n\Filter\NumberFormat("en_US", NumberFormatter::PERCENT);
+echo $filter->filter(0.80);
+// Returns "80%"
+
+$filter = new \Zend\I18n\Filter\NumberFormat("fr_FR", NumberFormatter::SCIENTIFIC);
+echo $filter->filter(0.00123456789);
+// Returns "1,23456789E-3"
+```
+
+## 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).
+
+### Supported Options
+
+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()`
+
+- `$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()`
+
+### Basic Usage
+
+```php
+$filter = new \Zend\I18n\Filter\NumberParse("de_DE");
+echo $filter->filter("1.234.567,891");
+// Returns 1234567.8912346
+
+$filter = new \Zend\I18n\Filter\NumberParse("en_US", NumberFormatter::PERCENT);
+echo $filter->filter("80%");
+// Returns 0.80
+
+$filter = new \Zend\I18n\Filter\NumberParse("fr_FR", NumberFormatter::SCIENTIFIC);
+echo $filter->filter("1,23456789E-3");
+// Returns 0.00123456789
+```

doc/book/zend.i18n.translating.md

@@ -0,0 +1,103 @@
+# Translating
+
+ZendI18n comes with a complete translation suite which supports all major formats and includes
+popular features like plural translations and text domains. The Translator component is mostly
+dependency free, except for the fallback to a default locale, where it relies on the Intl PHP
+extension.
+
+The translator itself is initialized without any parameters, as any configuration to it is optional.
+A translator without any translations will actually do nothing but just return the given message
+IDs.
+
+## Adding translations
+
+To add translations to the translator, there are two options. You can either add every translation
+file individually, which is the best way if you use translation formats which store multiple locales
+in the same file, or you can add translations via a pattern, which works best for formats which
+contain one locale per file.
+
+To add a single file to the translator, use the `addTranslationFile()` method:
+
+```php
+use Zend\I18n\Translator\Translator;
+
+$translator = new Translator();
+$translator->addTranslationFile($type, $filename, $textDomain, $locale);
+```
+
+The type given there is a name of one of the format loaders listed in the next section. Filename
+points to the file containing the translations, and the text domain specifies a category name for
+the translations. If the text domain is omitted, it will default to the "default" value. The locale
+specifies which language the translated strings are from and is only required for formats which
+contain translations for a single locale.
+
+> ## Note
+For each text domain and locale combination, there can only be one file loaded. Every successive
+file would override the translations which were loaded prior.
+
+When storing one locale per file, you should specify those files via a pattern. This allows you to
+add new translations to the file system, without touching your code. Patterns are added with the
+`addTranslationFilePattern()` method:
+
+```php
+use Zend\I18n\Translator\Translator;
+
+$translator = new Translator();
+$translator->addTranslationFilePattern($type, $baseDir, $pattern, $textDomain);
+```
+
+The parameters for adding patterns is pretty similar to adding individual files, except that you
+don't specify a locale and give the file location as a sprintf pattern. The locale is passed to the
+sprintf call, so you can either use %s or %1$s where it should be substituted. So when your
+translation files are located in /var/messages/LOCALE/messages.mo, you would specify your pattern as
+/var/messages/%s/messages.mo.
+
+## Supported formats
+
+The translator supports the following major translation formats:
+
+- PHP arrays
+- Gettext
+- INI
+
+## Setting a locale
+
+By default, the translator will get the locale to use from the Intl extension's `Locale` class. If
+you want to set an alternative locale explicitly, you can do so by passing it to the `setLocale()`
+method.
+
+When there is no translation for a specific message ID in a locale, the message ID itself will be
+returned by default. Alternatively you can set a fallback locale which is used to retrieve a
+fallback translation. To do so, pass it to the `setFallbackLocale()` method.
+
+## Translating messages
+
+Translating messages can accomplished by calling the `translate()` method of the translator:
+
+```php
+$translator->translate($message, $textDomain, $locale);
+```
+
+The message is the ID of your message to translate. If it does not exist in the loader translations
+or is empty, the original message ID will be returned. The text domain parameter is the one you
+specified when adding translations. If omitted, the default text domain will be used. The locale
+parameter will usually not be used in this context, as by default the locale is taken from the
+locale set in the translator.
+
+To translate plural messages, you can use the `translatePlural()` method. It works similar to
+`translate()`, but instead of a single message it takes a singular and a plural value and an
+additional integer number on which the returned plural form is based on:
+
+```php
+$translator->translatePlural($singular, $plural, $number, $textDomain, $locale);
+```
+
+Plural translations are only available if the underlying format supports the transport of plural
+messages and plural rule definitions.
+
+## Caching
+
+In production it makes sense to cache your translations. This not only saves you from loading and
+parsing the individual formats each time, but also guarantees an optimized loading procedure. To
+enable caching, simply pass a `Zend\Cache\Storage\Adapter` to the `setCache()` method. To disable
+the cache, you can just pass a null value to it.

doc/book/zend.i18n.validator.alnum.md

@@ -0,0 +1,50 @@
+# Alnum Validator
+
+`Zend\I18n\Validator\Alnum` allows you to validate if a given value contains only alphabetical
+characters and digits. There is no length limitation for the input you want to validate.
+
+## Supported Options
+
+The following options are supported for `Zend\I18n\Validator\Alnum`:
+
+- **allowWhiteSpace**: If whitespace characters are allowed. This option defaults to `FALSE`
+
+## Basic usage
+
+A basic example is the following one:
+
+```php
+$validator = new Zend\I18n\Validator\Alnum();
+if ($validator->isValid('Abcd12')) {
+    // value contains only allowed chars
+} else {
+    // false
+}
+```
+
+## Using whitespaces
+
+Per default whitespaces are not accepted because they are not part of the alphabet. Still, there is
+a way to accept them as input. This allows to validate complete sentences or phrases.
+
+To allow the usage of whitespaces you need to give the `allowWhiteSpace` option. This can be done
+while creating an instance of the validator, or afterwards by using `setAllowWhiteSpace()`. To get
+the actual state you can use `getAllowWhiteSpace()`.
+
+```php
+$validator = new Zend\I18n\Validator\Alnum(array('allowWhiteSpace' => true));
+if ($validator->isValid('Abcd and 12')) {
+    // value contains only allowed chars
+} else {
+    // false
+}
+```
+
+## Using different languages
+
+There are actually 3 languages which are not accepted in their own script. These languages are
+**korean**, **japanese** and **chinese** because this languages are using an alphabet where a single
+character is build by using multiple characters.
+
+In the case you are using these languages, the input will only be validated by using the english
+alphabet.

doc/book/zend.i18n.validator.alpha.md

@@ -0,0 +1,60 @@
+# Alpha Validator
+
+`Zend\I18n\Validator\Alpha` allows you to validate if a given value contains only alphabetical
+characters. There is no length limitation for the input you want to validate. This validator is
+related to the `Zend\I18n\Validator\Alnum` validator with the exception that it does not accept
+digits.
+
+## Supported options for Zend\\I18n\\Validator\\Alpha
+
+The following options are supported for `Zend\I18n\Validator\Alpha`:
+
+- **allowWhiteSpace**: If whitespace characters are allowed. This option defaults to `FALSE`
+
+## Basic usage
+
+A basic example is the following one:
+
+```php
+$validator = new Zend\I18n\Validator\Alpha();
+if ($validator->isValid('Abcd')) {
+    // value contains only allowed chars
+} else {
+    // false
+}
+```
+
+## Using whitespaces
+
+Per default whitespaces are not accepted because they are not part of the alphabet. Still, there is
+a way to accept them as input. This allows to validate complete sentences or phrases.
+
+To allow the usage of whitespaces you need to give the `allowWhiteSpace` option. This can be done
+while creating an instance of the validator, or afterwards by using `setAllowWhiteSpace()`. To get
+the actual state you can use `getAllowWhiteSpace()`.
+
+```php
+$validator = new Zend\I18n\Validator\Alpha(array('allowWhiteSpace' => true));
+if ($validator->isValid('Abcd and efg')) {
+    // value contains only allowed chars
+} else {
+    // false
+}
+```
+
+## Using different languages
+
+When using `Zend\I18n\Validator\Alpha` then the language which the user sets within his browser will
+be used to set the allowed characters. This means when your user sets **de** for german then he can
+also enter characters like **ä**, **ö** and **ü** additionally to the characters from the english
+alphabet.
+
+Which characters are allowed depends completely on the used language as every language defines it's
+own set of characters.
+
+There are actually 3 languages which are not accepted in their own script. These languages are
+**korean**, **japanese** and **chinese** because this languages are using an alphabet where a single
+character is build by using multiple characters.
+
+In the case you are using these languages, the input will only be validated by using the english
+alphabet.