Introduce DomainInterface

- Domain and PublicSuffix implements DomainInterface
- Improve internal code for Domain PublicSuffix and Rules class
- Domain validation is now supported on instanciation

Author: nyamsprod

CHANGELOG.md

@@ -6,12 +6,14 @@ All Notable changes to `PHP Domain Parser` **5.x** series will be documented in
 
 ### Added
 
+- `Pdp\DomainInterface` interface implemented by `Pdp\Domain` and `Pdp\PublicSuffix`
 - `Pdp\Domain::getContent` returns the Domain name value replaces `Pdp\Domain::getDomain`
 - `Pdp\Domain` implements the `Countable` interface.
 
 ### Fixed
 
 - `Pdp\Domain` domain part computation (public suffix, registrable domain and sub domain)
+- `Pdp\Domain` and `Pdp\PublicSuffix` host validation compliance to RFC improved
 
 ### Deprecated
 

data/pdp-PSL_FULL_5a3cc7f81795bb2e48e848af42d287b4.cache

@@ -104,7 +104,7 @@ private function addRule(array $list, array $rule_parts): array
         // "The domain and all rules must be canonicalized in the normal way
         // for hostnames - lower-case, Punycode (RFC 3492)."
 
-        $part = $this->idnToAscii($part);
+        $part = $this->idnToAscii(strtolower($part));
         $isDomain = true;
         if (0 === strpos($part, '!')) {
             $part = substr($part, 1);

src/Converter.php

@@ -11,7 +11,6 @@
 
 namespace Pdp;
 
-use Countable;
 use JsonSerializable;
 
 /**
@@ -28,7 +27,7 @@
  * @author Jeremy Kendall <[email protected]>
  * @author Ignace Nyamagana Butera <[email protected]>
  */
-final class Domain implements Countable, JsonSerializable
+final class Domain implements DomainInterface, JsonSerializable
 {
     use IDNAConverterTrait;
 
@@ -37,6 +36,11 @@ final class Domain implements Countable, JsonSerializable
      */
     private $domain;
 
+    /**
+     * @var string[]
+     */
+    private $labels;
+
     /**
      * @var PublicSuffix
      */
@@ -66,59 +70,51 @@ public static function __set_state(array $properties): self
      * @param string|null  $domain
      * @param PublicSuffix $publicSuffix
      */
-    public function __construct($domain = null, PublicSuffix $publicSuffix = null)
+    public function __construct(string $domain = null, PublicSuffix $publicSuffix = null)
     {
-        $this->domain = $this->setDomain($domain);
+        list($this->domain, $this->labels) = $this->setDomain($domain);
         $this->publicSuffix = $this->setPublicSuffix($publicSuffix);
+        $this->assertValidState();
         $this->registrableDomain = $this->setRegistrableDomain();
         $this->subDomain = $this->setSubDomain();
     }
 
     /**
-     * Normalize the given domain.
+     * Sets the public suffix domain part.
      *
-     * @param string|null $domain
+     * @param PublicSuffix|null $publicSuffix
      *
-     * @return string|null
+     * @return PublicSuffix
      */
-    private function setDomain(string $domain = null)
+    private function setPublicSuffix(PublicSuffix $publicSuffix = null): PublicSuffix
     {
-        if (null === $domain) {
-            return null;
-        }
-
-        if (false !== strpos($domain, '%')) {
-            $domain = rawurldecode($domain);
+        if (null === $publicSuffix
+            || null === $this->domain
+            || false === strpos($this->domain, '.')
+            || count($this->labels) === count($publicSuffix)
+        ) {
+            return new PublicSuffix();
         }
 
-        return strtolower($domain);
+        return $publicSuffix;
     }
 
     /**
-     * Sets the public suffix domain part.
-     *
-     * @param PublicSuffix|null $publicSuffix
+     * assert the domain internal state is valid
      *
-     * @return PublicSuffix
+     * @throws Exception if the public suffix does not match the domain
      */
-    private function setPublicSuffix(PublicSuffix $publicSuffix = null): PublicSuffix
+    protected function assertValidState()
     {
-        $publicSuffix = $publicSuffix ?? new PublicSuffix();
-        if (null === $publicSuffix->getContent()) {
-            return $publicSuffix;
-        }
-
-        if (null === $this->domain || false === strpos($this->domain, '.')) {
-            return new PublicSuffix();
+        foreach ($this->publicSuffix as $offset => $label) {
+            if ($label !== $this->labels[$offset]) {
+                throw new Exception(sprintf('The submitted public suffix `%s` is invalid for the given domain `%s`', $this->publicSuffix->getContent(), $this->domain));
+            }
         }
-
-        return $publicSuffix;
     }
 
     /**
      * Computes the registrable domain part.
-     *
-     * @return string|null
      */
     private function setRegistrableDomain()
     {
@@ -129,9 +125,6 @@ private function setRegistrableDomain()
         $labels = explode('.', $this->domain);
         $countLabels = count($labels);
         $countPublicSuffixLabels = count($this->publicSuffix);
-        if ($countLabels === $countPublicSuffixLabels) {
-            return null;
-        }
 
         return implode('.', array_slice($labels, $countLabels - $countPublicSuffixLabels - 1));
     }
@@ -157,16 +150,30 @@ private function setSubDomain()
         return implode('.', array_slice($labels, 0, $countLabels - $countLabelsToRemove));
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function getIterator()
+    {
+        foreach ($this->labels as $offset => $label) {
+            yield $label;
+        }
+    }
+
     /**
      * {@inheritdoc}
      */
     public function jsonSerialize()
     {
-        return array_merge([
+        return [
             'domain' => $this->domain,
             'registrableDomain' => $this->registrableDomain,
             'subDomain' => $this->subDomain,
-        ], $this->publicSuffix->jsonSerialize());
+            'publicSuffix' => $this->publicSuffix->getContent(),
+            'isKnown' => $this->isKnown(),
+            'isICANN' => $this->isICANN(),
+            'isPrivate' => $this->isPrivate(),
+        ];
     }
 
     /**
@@ -182,19 +189,11 @@ public function __debugInfo()
      */
     public function count()
     {
-        if (null === $this->domain) {
-            return 0;
-        }
-
-        return count(explode('.', $this->domain));
+        return count($this->labels);
     }
 
     /**
-     * Returns the domain content.
-     *
-     * This method should return null on seriously malformed domain name
-     *
-     * @return string|null
+     * {@inheritdoc}
      */
     public function getContent()
     {
@@ -206,7 +205,7 @@ public function getContent()
      *
      * DEPRECATION WARNING! This method will be removed in the next major point release
      *
-     * @deprecated deprecated since version 5.3
+     * @deprecated 5.3 deprecated
      * @see Domain::getContent
      *
      * This method should return null on seriously malformed domain name
@@ -218,6 +217,26 @@ public function getDomain()
         return $this->getContent();
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function getLabel(int $offset)
+    {
+        if ($offset < 0) {
+            $offset += count($this->labels);
+        }
+
+        return $this->labels[$offset] ?? null;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function keys(string $label): array
+    {
+        return array_keys($this->labels, $label, true);
+    }
+
     /**
      * Returns the registrable domain.
      *
@@ -258,7 +277,7 @@ public function getPublicSuffix()
     }
 
     /**
-     * Tells whether the public suffix has been matching rule in a Public Suffix List.
+     * Tells whether the public suffix has a matching rule in a Public Suffix List.
      *
      * @return bool
      */
@@ -288,45 +307,41 @@ public function isPrivate(): bool
     }
 
     /**
-     * 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
+     * {@inheritdoc}
      */
-    public function toAscii(): self
+    public function toAscii()
     {
-        if (null === $this->domain || false !== strpos($this->domain, 'xn--')) {
+        static $pattern = '/[^\x20-\x7f]/';
+        if (null === $this->domain || !preg_match($pattern, $this->domain)) {
             return $this;
         }
 
-        $newDomain = $this->idnToAscii($this->domain);
-        if ($newDomain === $this->domain) {
-            return $this;
-        }
+        $clone = clone $this;
+        $clone->domain = $this->idnToAscii($this->domain);
+        $clone->labels = array_reverse(explode('.', $clone->domain));
+        $clone->publicSuffix = $this->publicSuffix->toAscii();
+        $clone->registrableDomain = $clone->setRegistrableDomain();
+        $clone->subDomain = $clone->setSubDomain();
 
-        return new self($newDomain, $this->publicSuffix->toAscii());
+        return $clone;
     }
 
     /**
-     * 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
+     * {@inheritdoc}
      */
-    public function toUnicode(): self
+    public function toUnicode()
     {
         if (null === $this->domain || false === strpos($this->domain, 'xn--')) {
             return $this;
         }
 
-        return new self($this->idnToUnicode($this->domain), $this->publicSuffix->toUnicode());
+        $clone = clone $this;
+        $clone->domain = $this->idnToUnicode($this->domain);
+        $clone->labels = array_reverse(explode('.', $clone->domain));
+        $clone->publicSuffix = $this->publicSuffix->toUnicode();
+        $clone->registrableDomain = $clone->setRegistrableDomain();
+        $clone->subDomain = $clone->setSubDomain();
+
+        return $clone;
     }
 }

src/Domain.php

@@ -0,0 +1,84 @@
+<?php
+/**
+ * PHP Domain Parser: Public Suffix List based URL parsing.
+ *
+ * @see http://github.com/jeremykendall/php-domain-parser for the canonical source repository
+ *
+ * @copyright Copyright (c) 2017 Jeremy Kendall (http://jeremykendall.net)
+ * @license   http://github.com/jeremykendall/php-domain-parser/blob/master/LICENSE MIT License
+ */
+declare(strict_types=1);
+
+namespace Pdp;
+
+use Countable;
+use IteratorAggregate;
+
+/**
+ * Domain Interface
+ *
+ * @see https://tools.ietf.org/html/rfc1034#section-3.5
+ * @see https://tools.ietf.org/html/rfc1123#section-2.1
+ * @see https://tools.ietf.org/html/rfc5890
+ *
+ * @author Ignace Nyamagana Butera <[email protected]>
+ */
+interface DomainInterface extends Countable, IteratorAggregate
+{
+    /**
+     * Returns the domain content.
+     *
+     * @return string|null
+     */
+    public function getContent();
+
+    /**
+     * Retrieves a single domain label.
+     *
+     * If $offset is non-negative, the returned value will be the label at $offset position.
+     * If $offset is negative, the returned value will be the label at $offset position from the end.
+     *
+     * If no label is found the submitted $offset the returned value will be null.
+     *
+     * @param int $offset the label offset
+     *
+     * @return string|null
+     */
+    public function getLabel(int $offset);
+
+    /**
+     * Returns the associated key for each label.
+     *
+     * If a value is specified only the keys associated with
+     * the given value will be returned
+     *
+     * @param string $label the total number of argument given to the method
+     *
+     * @return int[]
+     */
+    public function keys(string $label): array;
+
+    /**
+     * Converts the domain to its IDNA ASCII form.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance with its content converted to its IDNA ASCII form
+     *
+     * @throws Exception if the domain can not be converted to ASCII using IDN UTS46 algorithm
+     *
+     * @return static
+     */
+    public function toAscii();
+
+    /**
+     * Converts the domain to its IDNA UTF8 form.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance with its content converted to its IDNA UTF8 form
+     *
+     * @throws Exception if the domain can not be converted to Unicode using IDN UTS46 algorithm
+     *
+     * @return static
+     */
+    public function toUnicode();
+}