Update documentation for 5.5 release

Author: nyamsprod

CHANGELOG.md

@@ -6,7 +6,8 @@ All Notable changes to `PHP Domain Parser` **5.x** series will be documented in
 
 ### Added
 
-- Support for `IDNA_OPTIONS` settings in all the classes see [#236](https://github.com/jeremykendall/php-domain-parser/pull/236) thanks to [Insolita](https://github.com/Insolita)
+- Support for IDNA options see [#236](https://github.com/jeremykendall/php-domain-parser/pull/236) thanks to [Insolita](https://github.com/Insolita). 
+
 - `PublicSuffix::labels` and `Domain::labels` to return the VO labels see [#241](https://github.com/jeremykendall/php-domain-parser/pull/241)
 
 ### Fixed

README.md

@@ -89,6 +89,33 @@ foreach($tldList as $tld) {
 
 Using the above code you have parse, validate and resolve a domain name and its public suffix status against the Public Suffix list.
 
+**Starting with vesion 5.5 support for IDNA options is added to the package**
+
+**Before**
+
+~~~php
+$manager = new Manager(new Cache(), new CurlHttpClient());
+$rules = $manager->getRules();
+
+$domain = $rules->resolve('faß.test.de');
+echo $domain->toAscii()->getContent(); // 'fass.test.de'
+~~~
+
+**After**
+
+~~~php
+$manager = new Manager(new Cache(), new CurlHttpClient());
+$rules = $manager->getRules(Manager::PSL_URL, null, IDNA_NONTRANSITIONAL_TO_ASCII,
+            IDNA_NONTRANSITIONAL_TO_UNICODE);
+// or
+// $rules = $rules
+//     ->withAsciiIDNAOption(IDNA_NONTRANSITIONAL_TO_ASCII)
+//     ->withUnicodeIDNAOption(IDNA_NONTRANSITIONAL_TO_UNICODE);
+
+$domain = $rules->resolve('faß.test.de');
+echo $domain->toAscii()->getContent(); // 'xn--fa-hia.test.de'
+~~~
+
 Documentation
 --------
 
@@ -135,6 +162,8 @@ public function Domain::append($label): Domain
 public function Domain::prepend($label): Domain
 public function Domain::withPublicSuffix($publicSuffix): Domain
 public function Domain::withSubDomain($subDomain): Domain
+public function Domain::withAsciiIDNAOption(int $option): Domain
+public function Domain::withUnicodeIDNAOption(int $option): Domain
 ~~~
 
 ~~~php
@@ -162,7 +191,6 @@ Because the `Pdp\Domain` object is immutable:
 
 **WARNING: URI and URL accept registered name which encompass domain name. Therefore, some URI host are invalid domain name and will trigger an exception if you try to instantiate a `Pdp\Domain` with them.**
 
-
 The `Pdp\Domain` object can tell whether a public suffix can be attached to it using the `Pdp\Domain::isResolvable` method.
 
 ~~~php
@@ -222,11 +250,27 @@ namespace Pdp;
 
 final class Rules
 {
-    public static function createFromPath(string $path, $context = null): Rules
-    public static function createFromString(string $content): Rules
-    public function __construct(array $rules)
+    public static function createFromPath(
+        string $path, $context = null,
+        int $asciiIDNAOption = IDNA_DEFAULT,
+        int $unicodeIDNAOption = IDNA_DEFAULT
+    ): Rules
+    public static function createFromString(
+        string $content,
+        int $asciiIDNAOption = IDNA_DEFAULT,
+        int $unicodeIDNAOption = IDNA_DEFAULT
+    ): Rules
+    public function __construct(
+        array $rules,
+        int $asciiIDNAOption = IDNA_DEFAULT,
+        int $unicodeIDNAOption = IDNA_DEFAULT
+    ): void
     public function resolve($domain, string $section = ''): Domain
     public function getPublicSuffix($domain, string $section = ''): PublicSuffix
+    public function getAsciiIDNAOption(): int
+    public function getUnicodeIDNAOption(): int
+    public function withAsciiIDNAOption(int $asciiIDNAOption): Rules
+    public function withUnicodeIDNAOption(int $unicodeIDNAOption): Rules
 }
 ~~~
 
@@ -304,12 +348,16 @@ namespace Pdp;
 
 final class TopLevelDomains implements Countable, IteratorAggregate
 {
-    public static function createFromPath(string $path, $context = null): Rules
-    public static function createFromString(string $content): Rules
-    public function __construct(array $records, string $version, DateTimeInterface $modifiedDate)
+    public static function createFromPath(string $path, $context = null, int $asciiIDNAOption = IDNA_DEFAULT, int $unicodeIDNAOption = IDNA_DEFAULT): Rules
+    public static function createFromString(string $content, int $asciiIDNAOption = IDNA_DEFAULT, int $unicodeIDNAOption = IDNA_DEFAULT): Rules
+    public function __construct(array $records, string $version, DateTimeInterface $modifiedDate, int $asciiIDNAOption = IDNA_DEFAULT, int $unicodeIDNAOption = IDNA_DEFAULT)
     public function resolve($domain): Domain
     public function contains($domain): bool
     public function isEmpty(): bool
+    public function getAsciiIDNAOption(): int
+    public function getUnicodeIDNAOption(): int
+    public function withAsciiIDNAOption(int $option): TopLevelDomains
+    public function withUnicodeIDNAOption(int $option): TopLevelDomains
 }
 ~~~
 
@@ -353,10 +401,6 @@ final class Manager
     const RZD_URL = 'https://data.iana.org/TLD/tlds-alpha-by-domain.txt';
 
     public function __construct(CacheInterface $cache, HttpClient $http, $ttl = null)
-    public function getRules(string $source_url = self::PSL_URL, $ttl = null): Rules
-    public function refreshRules(string $source_url = self::PSL_URL, $ttl = null): bool
-    public function getTLDs(string $source_url = self::RZD_URL, $ttl = null): Rules
-    public function refreshTLDs(string $source_url = self::RZD_URL, $ttl = null): bool
 }
 ~~~
 
@@ -376,7 +420,6 @@ The `$ttl` argument can be:
 
 **the `$ttl` argument is added to improve PSR-16 interoperability**
 
-
 The `Pdp\HttpClient` is a simple interface which exposes the `HttpClient::getContent` method. This method expects a string URL representation has its sole argument and returns the body from the given URL resource as a string.  
 If an error occurs while retrieving such body a `HttpClientException` exception is thrown.
 
@@ -414,7 +457,8 @@ public Manager::refreshRules(string $source_url = self::PSL_URL, $ttl = null): b
 public Manager::refreshTLD(string $source_url = self::RZD_URL, $ttl = null): bool
 ~~~
 
-The both methods method enables refreshing your local copy of the stored resources with your [PSR-16](http://www.php-fig.org/psr/psr-16/) Cache and retrieved using the Http Client. By default the method will use the resource default source URL but you are free to substitute this URL with your own.  
+The both methods method enables refreshing your local copy of the stored resources with your [PSR-16](http://www.php-fig.org/psr/psr-16/) Cache and retrieved using the Http Client. By default the method will use the resource default source URL but you are free to substitute this URL with your own.
+
 The method returns a boolean value which is `true` on success.
 
 ~~~php
@@ -432,8 +476,19 @@ if ($retval) {
 ~~~php
 <?php
 
-public Manager::getRules(string $source_url = self::PSL_URL, $ttl = null): Rules
-public Manager::getTLDs(string $source_url = self::RZD_URL, $ttl = null): TopLevelDomains
+public Manager::getRules(
+    string $source_url = self::PSL_URL,
+    $ttl = null,
+    int $asciiIDNAOption = IDNA_DEFAULT,
+    int $unicodeIDNAOption = IDNA_DEFAULT    
+): Rules
+
+public Manager::getTLDs(
+    string $source_url = self::RZD_URL,
+    $ttl = null,
+    int $asciiIDNAOption = IDNA_DEFAULT,
+    int $unicodeIDNAOption = IDNA_DEFAULT
+): TopLevelDomains
 ~~~
 
 These methods returns a `Pdp\Rules` or `Pdp\TopLevelDomains` objects seeded with their corresponding data fetch from the cache or from the external resources depending on the submitted `$ttl` argument.
@@ -445,6 +500,17 @@ These methods take an optional `$source_url` argument which specifies the PSL so
 
 On error, theses methods will throw an `Pdp\Exception`.
 
+ **since 5.5***
+
+the following optional arguments are added to the methods:
+
+- `$asciiIDNAOption` optional IDNA option for ascii conversion;
+- `$asciiIDNAOption` optional IDNA option for unicode conversion;
+
+**theses arguments are a combination of `IDNA_*` constants (except `IDNA_ERROR_*` constants).**
+
+They are used when instantiated the returned object.
+
 **THIS IS THE RECOMMENDED WAY OF USING THE LIBRARY**
 
 ~~~php