Introduce Rules::getPublicSuffix

Because Rules::resolve try to comply to PublicSuffix List algorithm some
exception are not always caught

Rules::getPublicSuffix is more strict than Rules::resolve and only returns the
public suffix information for a given domain.

The Domain and PublicSuffix value object now implements two modifiers
::toUnicode and ::toAscii to convers their value according to IDN UTS 46
algorithm. Domain names are still not validated but if the conversion can
not be perform an Exception is thrown.

Author: nyamsprod

CHANGELOG.md

@@ -1,6 +1,33 @@
 # Changelog
 
-All Notable changes to `PHP Domain Parser` will be documented in this file
+All Notable changes to `PHP Domain Parser` **5.x** series will be documented in this file
+
+## Next - TBD
+
+### Added
+
+- `Pdp\Rules::supports` returns a boolean to indicates if a given section is supported
+- `Pdp\Rules::getPublicSuffix` returns a `Pdp\PublicSuffix` value object
+- `Pdp\Rules::__set_state` is implemented
+- `Pdp\Domain::getSection` returns a string containing the section name used to determine the public suffix
+- `Pdp\Domain::toUnicode` returns a `Pdp\Domain` with its value converted to its Unicode form
+- `Pdp\Domain::toAscii` returns a `Pdp\Domain` with its value converted to its AScii form
+- `Pdp\PublicSuffix::getSection` returns a string containing the section name used to determine the public suffix
+- `Pdp\PublicSuffix::toUnicode` returns a `Pdp\PublicSuffix` with its value converted to its Unicode form
+- `Pdp\PublicSuffix::toAscii` returns a `Pdp\PublicSuffix` with its value converted to its AScii form
+
+### Fixed
+
+- `Pdp\Domain::getDomain` returns the normalized form of the domain name
+- `Pdp\PublicSuffix` is no longer internal.
+
+### Deprecated
+
+- None
+
+### Removed
+
+- None
 
 ## 5.1.0 - 2017-12-18
 

README.md

@@ -64,10 +64,17 @@ final class Rules
     public static function createFromPath(string $path, $context = null): self
     public static function createFromString(string $content): self
     public function __construct(array $rules)
+    public function supports(string $section): bool
+    public function getPublicSuffix(string $domain = null, string $section = self::ALL_DOMAINS): PublicSuffix
     public function resolve(string $domain = null, string $section = self::ALL_DOMAINS): Domain
 }
 ~~~
 
+**NEW IN VERSION 5.2:**
+
+- `Rules::supports` returns a boolean to tell whether the specific section is present in the `Rules` object;
+- `Rules::getPublicSuffix` returns a `PublicSuffix` object determined from the `Rules` object;
+
 **NEW IN VERSION 5.1:**
 
 - `Rules::createFromString` expects a string content which follows [the PSL format](https://publicsuffix.org/list/#list-format);
@@ -104,9 +111,18 @@ final class Domain implements JsonSerializable
     public function isKnown(): bool;
     public function isICANN(): bool;
     public function isPrivate(): bool;
+    public function getSection(): string;
+    public function toUnicode(): self;
+    public function toAscii(): self;
 }
 ~~~
 
+**NEW IN VERSION 5.2:**
+
+- `Domain::getSection` returns the section string name if presents else returns an empty string;
+- `Domain::toUnicode` returns an instance with the domain converted to its unicode representation;
+- `Domain::toAscii` returns an instance with the domain converted to its ascii representation;
+
 **THIS EXAMPLE ILLUSTRATES HOW THE OBJECT WORK BUT SHOULD BE AVOIDED IN PRODUCTON**
 
 ~~~php
@@ -169,6 +185,28 @@ If the domain name or some of its part are seriously malformed or unrecognized,
 - `Pdp\Domain::isICANN` returns `true` if the public suffix is found using a PSL which includes the ICANN DOMAINS section;
 - `Pdp\Domain::isPrivate` returns `true` if the public suffix is found using a PSL which includes the PRIVATE DOMAINS section;
 
+The `Rules::getPublicSuffix` method expects the same arguments as `Rules::resolve` but returns a `Pdp\PublicSuffix` object instead.
+
+~~~php
+<?php
+
+final class PublicSuffix implements Countable, JsonSerializable
+{
+    public function getContent(): ?string
+    public function isKnown(): bool;
+    public function isICANN(): bool;
+    public function isPrivate(): bool;
+    public function getSection(): string;
+    public function toUnicode(): self;
+    public function toAscii(): self;
+}
+~~~
+
+While `Rules::resolve` will only throws an exception if the section value is invalid, the `Rules::getPublicSuffix` is more restrictive and will additionnally throw if:
+
+- If the Domain is invalid or seriously malformed
+- If the PublicSuffix can not be normalized and converted using the domain encoding.
+
 **WARNING:**
 
 **The `Pdp\Rules::resolve` does not validate the submitted host. You are require to use a host validator prior to using this library.**

data/pdp-PSL-FULL-5a3cc7f81795bb2e48e848af42d287b4.cache

@@ -17,6 +17,9 @@
  * Public Suffix List Parser.
  *
  * This class convert the Public Suffix List into an associative, multidimensional array
+ *
+ * @author Jeremy Kendall <[email protected]>
+ * @author Ignace Nyamagana Butera <[email protected]>
  */
 final class Converter
 {

src/Converter.php

@@ -49,6 +49,14 @@ final class Domain implements JsonSerializable
      */
     private $subDomain;
 
+    /**
+     * {@inheritdoc}
+     */
+    public static function __set_state(array $properties): self
+    {
+        return new self($properties['domain'], $properties['publicSuffix']);
+    }
+
     /**
      * New instance.
      *
@@ -57,12 +65,36 @@ final class Domain implements JsonSerializable
      */
     public function __construct($domain = null, PublicSuffix $publicSuffix = null)
     {
+        if (false !== strpos((string) $domain, '%')) {
+            $domain = rawurldecode($domain);
+        }
+
+        if (null !== $domain) {
+            $domain = strtolower($domain);
+        }
+
         $this->domain = $domain;
-        $this->publicSuffix = $publicSuffix ?? new PublicSuffix();
+        $this->publicSuffix = $this->setPublicSuffix($publicSuffix);
         $this->registrableDomain = $this->setRegistrableDomain();
         $this->subDomain = $this->setSubDomain();
     }
 
+    /**
+     * Filter the PublicSuffix
+     *
+     * @param PublicSuffix|null $publicSuffix
+     *
+     * @return PublicSuffix
+     */
+    private function setPublicSuffix(PublicSuffix $publicSuffix = null): PublicSuffix
+    {
+        if (null === $publicSuffix || null === $this->domain) {
+            return new PublicSuffix();
+        }
+
+        return $publicSuffix;
+    }
+
     /**
      * Compute the registrable domain part.
      *
@@ -82,29 +114,7 @@ private function setRegistrableDomain()
         $domainLabels = explode('.', $this->domain);
         $registrableDomain = implode('.', array_slice($domainLabels, count($domainLabels) - $nbLabelsToRemove));
 
-        return $this->normalize($registrableDomain);
-    }
-
-    /**
-     * Normalizes the domain according to its representation.
-     *
-     * @param string $domain
-     *
-     * @return string|null
-     */
-    private function normalize(string $domain)
-    {
-        $func = 'idn_to_utf8';
-        if (false !== strpos($domain, 'xn--')) {
-            $func = 'idn_to_ascii';
-        }
-
-        $domain = $func($domain, 0, INTL_IDNA_VARIANT_UTS46);
-        if (false === $domain) {
-            return null;
-        }
-
-        return strtolower($domain);
+        return $registrableDomain;
     }
 
     /**
@@ -127,23 +137,19 @@ private function setSubDomain()
 
         $subDomain = implode('.', array_slice($domainLabels, 0, $countLabels - $nbLabelsToRemove));
 
-        return $this->normalize($subDomain);
+        return $subDomain;
     }
 
     /**
      * {@inheritdoc}
      */
     public function jsonSerialize()
     {
-        return [
+        return array_merge([
             'domain' => $this->domain,
             'registrableDomain' => $this->registrableDomain,
             'subDomain' => $this->subDomain,
-            'publicSuffix' => $this->publicSuffix->getContent(),
-            'isKnown' => $this->publicSuffix->isKnown(),
-            'isICANN' => $this->publicSuffix->isICANN(),
-            'isPrivate' => $this->publicSuffix->isPrivate(),
-        ];
+        ], $this->publicSuffix->jsonSerialize());
     }
 
     /**
@@ -154,14 +160,6 @@ public function __debugInfo()
         return $this->jsonSerialize();
     }
 
-    /**
-     * {@inheritdoc}
-     */
-    public static function __set_state(array $properties)
-    {
-        return new self($properties['domain'], $properties['publicSuffix']);
-    }
-
     /**
      * Returns the full domain name.
      *
@@ -214,7 +212,7 @@ public function getPublicSuffix()
     }
 
     /**
-     * Tells whether the public suffix has a matching rule in a Public Suffix List.
+     * Tells whether the public suffix has been matching rule in a Public Suffix List.
      *
      * @return bool
      */
@@ -242,4 +240,62 @@ public function isPrivate(): bool
     {
         return $this->publicSuffix->isPrivate();
     }
+
+    /**
+     * Returns the public suffix section name used to determine the public suffix.
+     *
+     * @return string
+     */
+    public function getSection(): string
+    {
+        return $this->publicSuffix->getSection();
+    }
+
+    /**
+     * Converts the domain to its IDNA ASCII form.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance with is content converted to its IDNA ASCII form
+     *
+     * @throws Exception if the domain can not be converted to ASCII using IDN UTS46 algorithm
+     *
+     * @return self
+     */
+    public function toAscii(): self
+    {
+        if (null === $this->domain || false !== strpos($this->domain, 'xn--')) {
+            return $this;
+        }
+
+        $domain = idn_to_ascii($this->domain, 0, INTL_IDNA_VARIANT_UTS46, $arr);
+        if (!$arr['errors']) {
+            return new self($domain, $this->publicSuffix->toAscii());
+        }
+
+        throw new Exception(sprintf('The following domain `%s` can not be converted to ascii', $this->domain));
+    }
+
+    /**
+     * Converts the domain to its IDNA UTF8 form.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance with is content converted to its IDNA UTF8 form
+     *
+     * @throws Exception if the domain can not be converted to Unicode using IDN UTS46 algorithm
+     *
+     * @return self
+     */
+    public function toUnicode(): self
+    {
+        if (null === $this->domain || false === strpos($this->domain, 'xn--')) {
+            return $this;
+        }
+
+        $domain = idn_to_utf8($this->domain, 0, INTL_IDNA_VARIANT_UTS46, $arr);
+        if (!$arr['errors']) {
+            return new self($domain, $this->publicSuffix->toUnicode());
+        }
+
+        throw new Exception(sprintf('The following domain `%s` can not be converted to unicode', $this->domain));
+    }
 }

src/Domain.php

@@ -40,7 +40,7 @@ public static function updateLocalCache(Event $event = null)
 
         require $vendor.'/autoload.php';
 
-        $io->write('Updating your Public Suffix List ICANN Section local cache.');
+        $io->write('Updating your Public Suffix List local cache.');
         if (!extension_loaded('curl')) {
             $io->writeError([
                 '😓 😓 😓 Your local cache could not be updated. 😓 😓 😓',

src/Installer.php

@@ -18,6 +18,9 @@
  *
  * This class obtains, writes, caches, and returns PHP representations
  * of the Public Suffix List ICANN section
+ *
+ * @author Jeremy Kendall <[email protected]>
+ * @author Ignace Nyamagana Butera <[email protected]>
  */
 final class Manager
 {