improve dockblock

Author: nyamsprod

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All Notable changes to `PHP Domain Parser` will be documented in this file
 
-## 4.0.0 - TBD
+## 5.0.0 - TBD
 
 ### Added
 
@@ -16,8 +16,9 @@ All Notable changes to `PHP Domain Parser` will be documented in this file
 
 ### Fixed
 
-- Domain class with invalid domain names improved supported
+- invalid domain names improved supported
 - idn_* conversion error better handled
+- domain name with RFC3986 encoded string improved supported
 
 ### Deprecated
 

README.md

@@ -256,7 +256,7 @@ The `Rules` class resolves the submitted domain against the parsed rules from th
 ~~~php
 <?php
 
-final class Domain
+final class Domain implements JsonSerializable
 {
     public function getDomain(): ?string
     public function getPublicSuffix(): ?string
@@ -292,6 +292,17 @@ $domain->getSubDomain();         //returns 'www'
 $domain->isKnown();              //returns true
 $domain->isICANN();              //returns true
 $domain->isPrivate();            //returns false
+echo json_encode($domain, JSON_PRETTY_PRINT);
+// returns
+//  {
+//      "domain": "www.ulb.ac.be",
+//      "registrableDomain": "ulb.ac.be",
+//      "subDomain": "www",
+//      "publicSuffix": "ac.be",
+//      "isKnown": true,
+//      "isICANN": true,
+//      "isPrivate": false
+//  }
 
 //let's resolve the same domain against the PRIVATE DOMAIN SECTION
 

composer.json

@@ -66,7 +66,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "4.x-dev"
+            "dev-master": "5.x-dev"
         }
     },
     "config": {

src/Domain.php

@@ -11,16 +11,23 @@
 
 namespace Pdp;
 
+use JsonSerializable;
+
 /**
  * Domain Value Object
  *
- * Lifted pretty much completely from Jeremy Kendall PDP
- * project
+ * WARNING: "Some people use the PSL to determine what is a valid domain name
+ * and what isn't. This is dangerous, particularly in these days where new
+ * gTLDs are arriving at a rapid pace, if your software does not regularly
+ * receive PSL updates, it will erroneously think new gTLDs are not
+ * valid. The DNS is the proper source for this innormalizeion. If you must use
+ * it for this purpose, please do not bake static copies of the PSL into your
+ * software with no update mechanism."
  *
  * @author Jeremy Kendall <[email protected]>
  * @author Ignace Nyamagana Butera <[email protected]>
  */
-final class Domain
+final class Domain implements JsonSerializable
 {
     /**
      * @var string|null
@@ -63,8 +70,12 @@ public function __construct($domain = null, PublicSuffix $publicSuffix)
      */
     private function setRegistrableDomain()
     {
-        if (!$this->hasRegistrableDomain()) {
-            return;
+        if (strpos((string) $this->domain, '.') === false) {
+            return null;
+        }
+
+        if (in_array($this->publicSuffix->getContent(), [null, $this->domain], true)) {
+            return null;
         }
 
         $nbLabelsToRemove = count($this->publicSuffix) + 1;
@@ -75,18 +86,7 @@ private function setRegistrableDomain()
     }
 
     /**
-     * Tells whether the domain has a registrable domain part.
-     *
-     * @return bool
-     */
-    private function hasRegistrableDomain(): bool
-    {
-        return strpos((string) $this->domain, '.') > 0
-            && !in_array($this->publicSuffix->getContent(), [null, $this->domain], true);
-    }
-
-    /**
-     * Normalize the domain according to its representation.
+     * Normalizes the domain according to its representation.
      *
      * @param string $domain
      *
@@ -108,13 +108,13 @@ private function normalize(string $domain)
     }
 
     /**
-     * Compute the sub domain part.
+     * Computes the sub domain part.
      *
      * @return string|null
      */
     private function setSubDomain()
     {
-        if (!$this->hasRegistrableDomain()) {
+        if (null === $this->registrableDomain) {
             return null;
         }
 
@@ -125,95 +125,61 @@ private function setSubDomain()
             return null;
         }
 
-        $domain = implode('.', array_slice($domainLabels, 0, $countLabels - $nbLabelsToRemove));
+        $subDomain = implode('.', array_slice($domainLabels, 0, $countLabels - $nbLabelsToRemove));
 
-        return $this->normalize($domain);
+        return $this->normalize($subDomain);
     }
 
     /**
-     * @return string|null
-     */
-    public function getDomain()
-    {
-        return $this->domain;
-    }
-
-    /**
-     * @return string|null
+     * {@inheritdoc}
      */
-    public function getPublicSuffix()
+    public function jsonSerialize()
     {
-        return $this->publicSuffix->getContent();
+        return [
+            '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(),
+        ];
     }
 
     /**
-     * Does the domain have a matching rule in the Public Suffix List?
-     *
-     * WARNING: "Some people use the PSL to determine what is a valid domain name
-     * and what isn't. This is dangerous, particularly in these days where new
-     * gTLDs are arriving at a rapid pace, if your software does not regularly
-     * receive PSL updates, because it will erroneously think new gTLDs are not
-     * valid. The DNS is the proper source for this innormalizeion. If you must use
-     * it for this purpose, please do not bake static copies of the PSL into your
-     * software with no update mechanism."
-     *
-     * @see https://publicsuffix.org/learn/
-     *
-     * @return bool
+     * {@inheritdoc}
      */
-    public function isKnown(): bool
+    public function __debugInfo()
     {
-        return $this->publicSuffix->isKnown();
+        return $this->jsonSerialize();
     }
 
     /**
-     * Does the domain have a matching rule in the Public Suffix List ICANN section
-     *
-     * WARNING: "Some people use the PSL to determine what is a valid domain name
-     * and what isn't. This is dangerous, particularly in these days where new
-     * gTLDs are arriving at a rapid pace, if your software does not regularly
-     * receive PSL updates, because it will erroneously think new gTLDs are not
-     * valid. The DNS is the proper source for this innormalizeion. If you must use
-     * it for this purpose, please do not bake static copies of the PSL into your
-     * software with no update mechanism."
-     *
-     * @see https://publicsuffix.org/learn/
-     *
-     * @return bool
+     * {@inheritdoc}
      */
-    public function isICANN(): bool
+    public static function __set_state(array $properties)
     {
-        return $this->publicSuffix->isICANN();
+        return new self($properties['domain'], $properties['publicSuffix']);
     }
 
     /**
-     * Does the domain have a matching rule in the Public Suffix List Private section
-     *
-     * WARNING: "Some people use the PSL to determine what is a valid domain name
-     * and what isn't. This is dangerous, particularly in these days where new
-     * gTLDs are arriving at a rapid pace, if your software does not regularly
-     * receive PSL updates, because it will erroneously think new gTLDs are not
-     * valid. The DNS is the proper source for this innormalizeion. If you must use
-     * it for this purpose, please do not bake static copies of the PSL into your
-     * software with no update mechanism."
+     * Returns the full domain name.
      *
-     * @see https://publicsuffix.org/learn/
+     * This method should return null on seriously malformed domain name
      *
-     * @return bool
+     * @return string|null
      */
-    public function isPrivate(): bool
+    public function getDomain()
     {
-        return $this->publicSuffix->isPrivate();
+        return $this->domain;
     }
 
     /**
-     * Get registrable domain.
+     * Returns the registrable domain.
      *
-     * Algorithm #7: The registered or registrable domain is the public suffix
-     * plus one additional label.
+     * The registered or registrable domain is the public suffix plus one additional label.
      *
-     * This method should return null if the domain provided is a public suffix,
-     * per the test cases provided by Mozilla.
+     * This method should return null if the registrable domain is the same as the public suffix.
      *
      * @see https://publicsuffix.org/list/
      * @see https://raw.githubusercontent.com/publicsuffix/list/master/tests/test_psl.txt
@@ -226,12 +192,12 @@ public function getRegistrableDomain()
     }
 
     /**
-     * Get the sub domain.
+     * Returns the sub domain.
      *
-     * This method should return null if
+     * The sub domain represents the remaining labels without the registrable domain.
      *
-     * - the registrable domain is null
-     * - the registrable domain is the same as the public suffix
+     * This method should return null if the registrable domain is null
+     * This method should return null if the registrable domain is the same as the public suffix
      *
      * @return string|null registrable domain
      */
@@ -241,26 +207,48 @@ public function getSubDomain()
     }
 
     /**
-     * {@inheritdoc}
+     * Returns the public suffix.
+     *
+     * @return string|null
      */
-    public function __debugInfo()
+    public function getPublicSuffix()
     {
-        return [
-            'domain' => $this->domain,
-            'publicSuffix' => $this->publicSuffix->getContent(),
-            'registrableDomain' => $this->registrableDomain,
-            'subDomain' => $this->subDomain,
-            'isKnown' => $this->isKnown(),
-            'isICANN' => $this->isICANN(),
-            'isPrivate' => $this->isPrivate(),
-        ];
+        return $this->publicSuffix->getContent();
     }
 
     /**
-     * {@inheritdoc}
+     * Tells whether the public suffix has a matching rule in a Public Suffix List.
+     *
+     * @see https://publicsuffix.org/learn/
+     *
+     * @return bool
      */
-    public static function __set_state(array $properties)
+    public function isKnown(): bool
     {
-        return new self($properties['domain'], $properties['publicSuffix']);
+        return $this->publicSuffix->isKnown();
+    }
+
+    /**
+     * Tells whether the public suffix has a matching rule in a Public Suffix List ICANN Section.
+     *
+     * @see https://publicsuffix.org/learn/
+     *
+     * @return bool
+     */
+    public function isICANN(): bool
+    {
+        return $this->publicSuffix->isICANN();
+    }
+
+    /**
+     * Tells whether the public suffix has a matching rule in a Public Suffix List Private Section.
+     *
+     * @see https://publicsuffix.org/learn/
+     *
+     * @return bool
+     */
+    public function isPrivate(): bool
+    {
+        return $this->publicSuffix->isPrivate();
     }
 }

src/Installer.php

@@ -15,6 +15,8 @@
 
 /**
  * A class to manage PSL ICANN Section rules updates
+ *
+ * @author Ignace Nyamagana Butera <[email protected]>
  */
 final class Installer
 {

src/Manager.php

@@ -46,7 +46,7 @@ public function __construct(CacheInterface $cache, HttpClient $http)
     }
 
     /**
-     * Gets ICANN Public Suffix List Rules.
+     * Gets the Public Suffix List Rules.
      *
      * @param string $source_url the Public Suffix List URL
      *
@@ -66,7 +66,6 @@ public function getRules(string $source_url = self::PSL_URL): Rules
 
         $rules = $this->cache->get($cacheKey);
 
-
         return new Rules(json_decode($rules, true));
     }
 
@@ -85,10 +84,11 @@ private function getCacheKey(string $str): string
     }
 
     /**
-     * Downloads Public Suffix List and writes text cache and PHP cache. If these files
-     * already exist, they will be overwritten.
+     * Downloads, converts and cache the Public Suffix.
+     *
+     * If a local cache already exists, it will be overwritten.
      *
-     * Returns true if all list are correctly refreshed
+     * Returns true if the refresh was successful
      *
      * @param string $source_url the Public Suffix List URL
      *