Improve Rules code

- Constants are now attached to the `Rules` class instead of the `PublicSuffix` class
- The `Parser` class is renamed `Converter` to avoid BC break usage
- The `PublicSuffix` class is made internal

Author: nyamsprod

CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All Notable changes to `PHP Domain Parser` will be documented in this file
+
+## 4.0.0 - TBD
+
+### Added
+
+- `Pdp\Exception` a base exception for the library
+- `Pdp\Rules` a class to resolve domain name against the public suffix list
+- `Pdp\Domain` an immutable value object to represents a parsed domain name
+- `Pdp\Installer` a class to enable improve PSL maintenance
+- `Pdp\Cache` a PSR-16 file cache implementation to cache a local copy of the PSL
+- `Pdp\Manager` a class to enable managing PSL sources and `Rules` objects creation
+- `Pdp\Converter` a class to convert the PSL into a PHP array
+
+### Fixed
+
+- Domain class with invalid domain names improved supported
+- idn_* conversion error better handled
+
+### Deprecated
+
+- None
+
+### Removed
+
+- URL Parsing capabilities API is removed
+- `Pdp\PublicSuffixList` class replaced by the `Pdp\Rules` class
+- `Pdp\PublicSuffixManager` class replaced by the `Pdp\Manager` class
+- `Pdp\HttpAdapter\HttpAdapterInterface` interface replaced by the `Pdp\HttpClient` interface
+- `Pdp\HttpAdapter\CurlHttpAdapter` class replaced by the `Pdp\CurlHttpClient` class

README.md

@@ -18,10 +18,8 @@ Consider the domain www.pref.okinawa.jp.  In this domain, the
 *public suffix* portion is **okinawa.jp**, the *registrable domain* is
 **pref.okinawa.jp**, and the *subdomain* is **www**. You can't regex that.
 
-Other similar libraries focus primarily on URL building, parsing, and
-manipulation and additionally include public suffix domain parsing.  PHP Domain
-Parser was built around accurate Public Suffix List based parsing from the very
-beginning, adding a URL object simply for the sake of completeness.
+PHP Domain Parser was built around accurate Public Suffix List based parsing from the very
+beginning. For URL parsing, building or manipulation please refer to [better libraries](https://packagist.org/packages/sabre/uri?q=uri%20rfc3986&p=0) who are more focus on those area of development
 
 System Requirements
 -------
@@ -50,7 +48,6 @@ Documentation
 
 ### Public Suffix Manager
 
-
 ~~~php
 <?php
 
@@ -240,40 +237,28 @@ namespace Pdp;
 
 final class Rules
 {
+    const ALL_DOMAINS = 'ALL_DOMAINS';
+    const ICANN_DOMAINS = 'ICANN_DOMAINS';
+    const PRIVATE_DOMAINS = 'PRIVATE_DOMAINS';
+
     public function __construct(array $rules)
-    public function resolve(string $domain = null, string $type = Domain::UNKNOWN_DOMAIN): Domain
+    public function resolve(string $domain = null, string $type = self::ALL_DOMAINS): Domain
 }
 ~~~
 
 The `Rules` constructor expects a `array` representation of the Public Suffix List. This `array` representation is constructed by the `Manager` and stored using a PSR-16 compliant cache.
 
-The `Rules` class resolves the submitted domain against the parsed rules from the PSL. This is done using the `Rules::resolve` method which returns a `Pdp\Domain` object. The method expect a valid domain and you can optionnally specify against which section of rules you want to validate the given domain. By default all section are used (ie `PRIVATE` and `ICANN`) if the submitted section is invalid or unknown, the resolver will fallback to use the entire list.
-
-~~~php
-<?php
-
-final class PublicSuffix
-{
-
-    const ICANN = 'ICANN_DOMAIN';
-    const PRIVATE = 'PRIVATE_DOMAIN';
-    const ALL = 'ALL_DOMAIN';
-    const UNKNOWN = 'UNKNOWN_DOMAIN';
+The `Rules` class resolves the submitted domain against the parsed rules from the PSL. This is done using the `Rules::resolve` method which returns a `Pdp\Domain` object. The method expects
 
-    public function __construct(?string $domain = null, string $type = self::UNKNOWN);
-    public function getContent(): ?string
-    public function isKnown(): bool;
-    public function isICANN(): bool;
-    public function isPrivate(): bool;
-}
-~~~
+- a valid domain name as a string
+- a string to optionnally specify which section of the PSL you want to validate the given domain against.  
+ By default all sections are used `Rules::ALL_DOMAINS` but you can validate your domain against the ICANN only section (`Rules::ICANN_DOMAINS` or the private section (`Rules::PRIVATE_DOMAINS`) of the PSL.
 
 ~~~php
 <?php
 
 final class Domain
 {
-    public function __construct(?string $domain = null, PublicSuffix $publicSuffix);
     public function getDomain(): ?string
     public function getPublicSuffix(): ?string
     public function getRegistrableDomain(): ?string
@@ -286,7 +271,7 @@ final class Domain
 
 The `Domain` getters method always return normalized value according to the domain status against the PSL rules.
 
-<p class="message-notice"><code>Domain::isValid</code> status depends on the PSL rules used. For the same domain, depending on the rules used a domain public suffix may be valid or not.</p>
+<p class="message-notice"><code>Domain::isKnown</code> status depends on the PSL rules used. For the same domain, depending on the rules used a domain public suffix may be known or not.</p>
 
 ~~~php
 <?php
@@ -305,23 +290,23 @@ $domain->getDomain();            //returns 'www.ulb.ac.be'
 $domain->getPublicSuffix();      //returns 'ac.be'
 $domain->getRegistrableDomain(); //returns 'ulb.ac.be'
 $domain->getSubDomain();         //returns 'www'
-$domain->isValid();              //returns true
+$domain->isKnown();              //returns true
 $domain->isICANN();              //returns true
 $domain->isPrivate();            //returns false
 
-//let's resolve the same URI againts the PRIVATE DOMAIN SECTION
+//let's resolve the same domain against the PRIVATE DOMAIN SECTION
 
-$domain = $rules->resolve('www.ulb.ac.be', Domain::PRIVATE_DOMAIN);
+$domain = $rules->resolve('www.ulb.ac.be', Rules::PRIVATE_DOMAINS);
 $domain->getDomain();            //returns 'www.ulb.ac.be'
 $domain->getPublicSuffix();      //returns 'be'
 $domain->getRegistrableDomain(); //returns 'ac.be'
 $domain->getSubDomain();         //returns 'www.ulb'
-$domain->isValid();              //returns false
+$domain->isKnown();              //returns false
 $domain->isICANN();              //returns false
 $domain->isPrivate();            //returns false
 ~~~
 
-<p class="message-warning"><strong>Warning:</strong> 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 information. If you must use it for this purpose, please do not bake static copies of the PSL into your software with no update mechanism.</p>
+<p class="message-warning"><strong>Warning:</strong> 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 may erroneously think new gTLDs are not known. The DNS is the proper source for this information. If you must use it for this purpose, please do not bake static copies of the PSL into your software with no update mechanism.</p>
 
 Contributing
 -------

composer.json

@@ -29,11 +29,12 @@
     "keywords": [
         "Public Suffix List",
         "domain parsing",
-        "url parsing"
+        "icann",
+        "idn",
+        "psl"
     ],
     "require": {
         "php": ">=7.0",
-        "ext-curl": "*",
         "ext-intl": "*",
         "psr/simple-cache": "^1"
     },
@@ -43,7 +44,8 @@
         "friendsofphp/php-cs-fixer": "^2.7"
     },
     "suggest": {
-        "psr/simple-cache-implementation": "To enable using other cache providers"
+        "psr/simple-cache-implementation": "To enable using other cache providers",
+        "ext-curl": "To use the package http client"
     },
     "autoload": {
         "psr-4": {

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

@@ -16,9 +16,9 @@
 /**
  * Public Suffix List Parser.
  *
- * This class parses the Public Suffix List
+ * This class convert the Public Suffix List into an associative, multidimensional array
  */
-final class Parser
+final class Converter
 {
     /**
      * Convert the Public Suffix List into
@@ -28,12 +28,9 @@ final class Parser
      *
      * @return array
      */
-    public function parse(string $content): array
+    public function convert(string $content): array
     {
-        $rules = [
-            PublicSuffix::ICANN => [],
-            PublicSuffix::PRIVATE => [],
-        ];
+        $rules = [Rules::ICANN_DOMAINS => [], Rules::PRIVATE_DOMAINS => []];
         $file = new SplTempFileObject();
         $file->fwrite($content);
         $file->setFlags(SplTempFileObject::DROP_NEW_LINE | SplTempFileObject::READ_AHEAD | SplTempFileObject::SKIP_EMPTY);
@@ -59,18 +56,18 @@ public function parse(string $content): array
     private function getSection(string $section, string $line): string
     {
         if ($section == '' && strpos($line, '// ===BEGIN ICANN DOMAINS===') === 0) {
-            return PublicSuffix::ICANN;
+            return Rules::ICANN_DOMAINS;
         }
 
-        if ($section == PublicSuffix::ICANN && strpos($line, '// ===END ICANN DOMAINS===') === 0) {
+        if ($section == Rules::ICANN_DOMAINS && strpos($line, '// ===END ICANN DOMAINS===') === 0) {
             return '';
         }
 
         if ($section == '' && strpos($line, '// ===BEGIN PRIVATE DOMAINS===') === 0) {
-            return PublicSuffix::PRIVATE;
+            return Rules::PRIVATE_DOMAINS;
         }
 
-        if ($section == PublicSuffix::PRIVATE && strpos($line, '// ===END PRIVATE DOMAINS===') === 0) {
+        if ($section == Rules::PRIVATE_DOMAINS && strpos($line, '// ===END PRIVATE DOMAINS===') === 0) {
             return '';
         }
 

src/Parser.php renamed to src/Converter.php

@@ -28,7 +28,7 @@ final class Domain
     private $domain;
 
     /**
-     * @var string|null
+     * @var PublicSuffix
      */
     private $publicSuffix;
 
@@ -52,23 +52,26 @@ public function __construct($domain = null, PublicSuffix $publicSuffix)
     {
         $this->domain = $domain;
         $this->publicSuffix = $publicSuffix;
-        $this->setRegistrableDomain();
-        $this->setSubDomain();
+        $this->registrableDomain = $this->setRegistrableDomain();
+        $this->subDomain = $this->setSubDomain();
     }
 
     /**
-     * Compute the registrable domain part
+     * Compute the registrable domain part.
+     *
+     * @return string|null
      */
     private function setRegistrableDomain()
     {
         if (!$this->hasRegistrableDomain()) {
             return;
         }
 
-        $countLabelsToRemove = count($this->publicSuffix) + 1;
+        $nbLabelsToRemove = count($this->publicSuffix) + 1;
         $domainLabels = explode('.', $this->domain);
-        $domain = implode('.', array_slice($domainLabels, count($domainLabels) - $countLabelsToRemove));
-        $this->registrableDomain = $this->normalize($domain);
+        $registrableDomain = implode('.', array_slice($domainLabels, count($domainLabels) - $nbLabelsToRemove));
+
+        return $this->normalize($registrableDomain);
     }
 
     /**
@@ -105,23 +108,26 @@ private function normalize(string $domain)
     }
 
     /**
-     * Compute the sub domain part
+     * Compute the sub domain part.
+     *
+     * @return string|null
      */
     private function setSubDomain()
     {
         if (!$this->hasRegistrableDomain()) {
-            return;
+            return null;
         }
 
+        $nbLabelsToRemove = count($this->publicSuffix) + 1;
         $domainLabels = explode('.', $this->domain);
         $countLabels = count($domainLabels);
-        $countLabelsToRemove = count($this->publicSuffix) + 1;
-        if ($countLabels === $countLabelsToRemove) {
-            return;
+        if ($countLabels === $nbLabelsToRemove) {
+            return null;
         }
 
-        $domain = implode('.', array_slice($domainLabels, 0, $countLabels - $countLabelsToRemove));
-        $this->subDomain = $this->normalize($domain);
+        $domain = implode('.', array_slice($domainLabels, 0, $countLabels - $nbLabelsToRemove));
+
+        return $this->normalize($domain);
     }
 
     /**

src/Domain.php

@@ -96,11 +96,11 @@ private function getCacheKey(string $str): string
      */
     public function refreshRules(string $source_url = self::PSL_URL): bool
     {
-        static $parser;
-        $parser = $parser ?? new Parser();
+        static $converter;
+        $converter = $converter ?? new Converter();
         $content = $this->http->getContent($source_url);
-        $rules = $parser->parse($content);
-        if (empty($rules[PublicSuffix::ICANN]) || empty($rules[PublicSuffix::PRIVATE])) {
+        $rules = $converter->convert($content);
+        if (empty($rules[Rules::ICANN_DOMAINS]) || empty($rules[Rules::PRIVATE_DOMAINS])) {
             return false;
         }
 

src/Manager.php

@@ -16,16 +16,12 @@
 /**
  * Public Suffix Value Object
  *
- * @author Jeremy Kendall <[email protected]>
  * @author Ignace Nyamagana Butera <[email protected]>
+ *
+ * @internal
  */
 final class PublicSuffix implements Countable
 {
-    const ICANN = 'ICANN_DOMAIN';
-    const PRIVATE = 'PRIVATE_DOMAIN';
-    const ALL = 'ALL_DOMAIN';
-    const UNKNOWN = 'UNKNOWN_DOMAIN';
-
     /**
      * @var string|null
      */
@@ -34,21 +30,17 @@ final class PublicSuffix implements Countable
     /**
      * @var string
      */
-    private $type = '';
+    private $type;
 
     /**
      * New instance.
      *
      * @param string|null $publicSuffix
      * @param string      $type
      */
-    public function __construct(string $publicSuffix = null, string $type = self::UNKNOWN)
+    public function __construct(string $publicSuffix = null, string $type = '')
     {
         $this->publicSuffix = $publicSuffix;
-        if (!in_array($type, [self::UNKNOWN, self::PRIVATE, self::ICANN], true)) {
-            $type = self::UNKNOWN;
-        }
-
         $this->type = $type;
     }
 
@@ -89,7 +81,7 @@ public function count()
      */
     public function isKnown(): bool
     {
-        return self::UNKNOWN !== $this->type;
+        return '' !== $this->type;
     }
 
     /**
@@ -109,7 +101,7 @@ public function isKnown(): bool
      */
     public function isICANN(): bool
     {
-        return self::ICANN === $this->type;
+        return Rules::ICANN_DOMAINS === $this->type;
     }
 
     /**
@@ -129,7 +121,7 @@ public function isICANN(): bool
      */
     public function isPrivate(): bool
     {
-        return self::PRIVATE === $this->type;
+        return Rules::PRIVATE_DOMAINS === $this->type;
     }
 
     /**