Improve package after review

- simplify domain validation
- improve Rules::resolve and Rules::getPublicSuffix argument signature
- added DomainInterface::__toString method
- Documentation updated

Author: nyamsprod

CHANGELOG.md

@@ -8,26 +8,26 @@ All Notable changes to `PHP Domain Parser` **5.x** series will be documented in
 
 - `Pdp\PublicSuffixListSection` interface implemented by `Pdp\Rules` and `Pdp\PublicSuffix`
 - `Pdp\DomainInterface` interface implemented by `Pdp\Domain` and `Pdp\PublicSuffix`
-- `Pdp\Domain` implements the `Countable` interface.
-- `Pdp\Domain::getContent` returns the Domain name value replaces `Pdp\Domain::getDomain`
+- `Pdp\Domain::getContent` replaces `Pdp\Domain::getDomain`
 - `Pdp\Domain::withPublicSuffix` updates the `Pdp\Domain` public suffix part.
 - `Pdp\Domain::withSubDomain` updates the `Pdp\Domain` sub domain part.
 - `Pdp\Domain::withLabel` adds a new label to the `Pdp\Domain`.
 - `Pdp\Domain::withoutLabel` removes a label from the `Pdp\Domain`.
 - `Pdp\Domain::resolve` attach a public suffix to the `Pdp\Domain`.
-- `Pdp\Domain::isResolvable` tell whether the current `Pdp\Domain` can have a public suffix attached to it or not.
+- `Pdp\Domain::isResolvable` tells whether the current `Pdp\Domain` can have a public suffix attached to it or not.
 - `Pdp\PublicSuffix::createFromDomain` returns a new `Pdp\PublicSuffix` object from a `Pdp\Domain`object
 
 ### Fixed
 
 - `Pdp\Domain` domain part computation (public suffix, registrable domain and sub domain)
 - `Pdp\Domain` and `Pdp\PublicSuffix` host validation compliance to RFC improved
-- Improved `Pdp\Converter` and `Pdp\Manager` class to better report error on IDN conversion.
+- Improve `Pdp\Converter` and `Pdp\Manager` class to better report error on IDN conversion.
+- Improve `Pdp\Installer` vendor directory resolution see [PR #222](https://github.com/jeremykendall/php-domain-parser/pull/222)
 
 ### Deprecated
 
 - `Pdp\Domain::getDomain` use instead `Pdp\Domain::getContent`
-- `Pdp\PublicSuffixListSection::ALL_DOMAINS` use the empty string instead
+- `Pdp\Rules::ALL_DOMAINS` use the empty string instead
 
 ### Removed
 

README.md

@@ -88,12 +88,13 @@ Using the above code you can parse and get public suffix informations about any
 The `Pdp\Domain` returned by the `Pdp\Rules::resolve` method is an immutable value object representing a valid domain name. This object let's you access all the domain name properties as well as the public suffix informations attached to it using the following methods.
 
 ~~~php
-public function Domain::getLabel(int $key): ?string
-public function Domain::keys(?string $label): int[]
+public function Domain::__toString(): string
 public function Domain::getContent(): ?string
 public function Domain::getPublicSuffix(): ?string
 public function Domain::getRegistrableDomain(): ?string
 public function Domain::getSubDomain(); ?string
+public function Domain::getLabel(int $key): ?string
+public function Domain::keys(?string $label): int[]
 public function Domain::isResolvable(): bool;
 public function Domain::isKnown(): bool;
 public function Domain::isICANN(): bool;
@@ -154,17 +155,37 @@ $newDomain->isKnown(); //return true;
 
 ### Getting the domain public suffix information.
 
-The `Pdp\Rules` object is responsible for public suffix resolution for a given domain. Public suffix resolution is done using the `Pdp\Rules::resolve` or `Pdp\Rules::getPublicSuffix` methods which expects at most two parameters:
+~~~php
+<?php
+
+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 function resolve($domain, $section = ''): Domain
+    public function getPublicSuffix($domain, $section = ''): PublicSuffix
+}
+~~~
+
+The `Pdp\Rules` object is responsible for public suffix resolution for a given domain. Public suffix resolution is done using:
+
+- the `Pdp\Rules::resolve` method which returns a `Pdp\Domain` object;
+- the `Pdp\Rules::getPublicSuffix` methods which returns a `Pdp\PublicSuffix` object;
+
+Both methods expect the same arguments:
 
-- `$domain` a domain name as a string
+- `$domain` a domain name
 - `$section` a string which specifies which section of the PSL you want to validate the given domain against. The possible values are:
     - `Rules::ICANN_DOMAINS`, to validate against the PSL ICANN DOMAINS section only.
     - `Rules::PRIVATE_DOMAINS`, to validate against the PSL PRIVATE DOMAINS section only.
     - the empty string to validate against all the PSL sections.
 
 By default, the `$section` argument is equal to the empty string. If an unsupported section is submitted a `Pdp\Exception` exception will be thrown.
 
-While the `Pdp\Rules::resolve` returns a `Pdp\Domain` object, the `Pdp\Rules::getPublicSuffix` returns a `Pdp\PublicSuffix` object.
+The `Pdp\PublicSuffix` object exposes the same methods as the `Pdp\Domain` object minus all the modifying methods, `toAscii` and `toUnicode` excluded.
 
 **THIS EXAMPLE ILLUSTRATES HOW THE OBJECT WORK BUT SHOULD BE AVOIDED IN PRODUCTON**
 
@@ -178,6 +199,7 @@ $pdp_url = 'https://raw.githubusercontent.com/publicsuffix/list/master/public_su
 $rules = Rules::createFromPath($pdp_url);
 
 $domain = $rules->resolve('www.Ulb.AC.be'); // resolution is done against all the sections available
+echo $domain; // returns www.ulb.ac.be
 echo json_encode($domain, JSON_PRETTY_PRINT);
 // returns
 //  {
@@ -190,9 +212,9 @@ echo json_encode($domain, JSON_PRETTY_PRINT);
 //      "isPrivate": false
 //  }
 
-//The same domain will yield a different result using the PSL PRIVATE DOMAIN SECTION only
+//The same domain will yield a different result using the PSL ICANN DOMAIN SECTION only
 
-$domain = $rules->resolve('www.Ulb.AC.be', Rules::PRIVATE_DOMAINS);
+$domain = $rules->resolve('www.Ulb.AC.be', Rules::ICANN_DOMAINS);
 echo json_encode($domain, JSON_PRETTY_PRINT);
 // returns
 //  {

data/pdp-PSL_FULL_5a3cc7f81795bb2e48e848af42d287b4.cache

@@ -72,7 +72,10 @@ public static function __set_state(array $properties): self
      */
     public function __construct($domain = null, PublicSuffix $publicSuffix = null)
     {
-        list($this->domain, $this->labels) = $this->setDomain($domain);
+        $this->labels = $this->setLabels($domain);
+        if (!empty($this->labels)) {
+            $this->domain = implode('.', array_reverse($this->labels));
+        }
         $this->publicSuffix = $this->setPublicSuffix($publicSuffix ?? new PublicSuffix());
         $this->registrableDomain = $this->setRegistrableDomain();
         $this->subDomain = $this->setSubDomain();
@@ -92,7 +95,7 @@ public function __construct($domain = null, PublicSuffix $publicSuffix = null)
     private function setPublicSuffix(PublicSuffix $publicSuffix): PublicSuffix
     {
         if (null === $publicSuffix->getContent()) {
-            return new PublicSuffix();
+            return $publicSuffix;
         }
 
         if (!$this->isResolvable()) {
@@ -115,11 +118,11 @@ private function setPublicSuffix(PublicSuffix $publicSuffix): PublicSuffix
     /**
      * Normalize the domain name encoding content.
      *
-     * @param mixed $subject
+     * @param PublicSuffix $subject
      *
-     * @return mixed
+     * @return PublicSuffix
      */
-    private function normalize($subject)
+    private function normalize(PublicSuffix $subject): PublicSuffix
     {
         if (null === $this->domain || null === $subject->getContent()) {
             return $subject;
@@ -135,6 +138,8 @@ private function normalize($subject)
 
     /**
      * Computes the registrable domain part.
+     *
+     * @return string|null
      */
     private function setRegistrableDomain()
     {
@@ -222,6 +227,14 @@ public function getContent()
         return $this->domain;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function __toString()
+    {
+        return (string) $this->domain;
+    }
+
     /**
      * Returns the full domain name.
      *
@@ -301,11 +314,16 @@ public function getPublicSuffix()
     /**
      * Tells whether the given domain can be resolved.
      *
+     * A domain is resolvable if:
+     *     - it contains at least 2 labels
+     *     - it is not a absolute domain (end with a '.' character)
+     *
      * @return bool
      */
     public function isResolvable(): bool
     {
-        return 2 <= count($this->labels);
+        return 2 <= count($this->labels)
+            && '.' !== substr($this->domain, -1, 1);
     }
 
     /**
@@ -506,13 +524,14 @@ public function withPublicSuffix($publicSuffix): self
     public function withLabel(int $key, $label): self
     {
         if (!$label instanceof PublicSuffix) {
-            $label = new PublicSuffix($label);
+            $label = $this->normalize(new PublicSuffix($label));
         }
 
-        if (1 !== count($label)) {
-            throw new Exception(sprintf('The label `%s` is invalid', $label->getContent()));
+        if (1 != count($label)) {
+            throw new Exception(sprintf('The label `%s` is invalid', (string) $label));
         }
 
+        $label = (string) $label;
         $nb_labels = count($this->labels);
         $offset = filter_var($key, FILTER_VALIDATE_INT, ['options' => ['min_range' => - $nb_labels - 1, 'max_range' => $nb_labels]]);
         if (false === $offset) {
@@ -523,15 +542,16 @@ public function withLabel(int $key, $label): self
             $offset = $nb_labels + $offset;
         }
 
-        $label = $this->normalize($label)->getContent();
         if ($label === ($this->labels[$offset] ?? null)) {
             return $this;
         }
 
+        $labels = $this->labels;
+        $labels[$offset] = $label;
+        ksort($labels);
+
         $clone = clone $this;
-        $clone->labels[$offset] = $label;
-        ksort($clone->labels);
-        $clone->labels = array_values($clone->labels);
+        $clone->labels = array_values($labels);
         $clone->domain = implode('.', array_reverse($clone->labels));
         if (null !== $this->publicSuffix->getLabel($offset)) {
             $clone->publicSuffix = new PublicSuffix();

src/Domain.php

@@ -32,6 +32,13 @@ interface DomainInterface extends Countable, IteratorAggregate
      */
     public function getContent();
 
+    /**
+     * Returns the domain content as a string.
+     *
+     * @return string
+     */
+    public function __toString();
+
     /**
      * Retrieves a single domain label.
      *
@@ -81,4 +88,13 @@ public function toAscii();
      * @return static
      */
     public function toUnicode();
+
+
+    /**
+     * {@inheritdoc}
+     *
+     * The external iterator iterates over the DomainInterface labels
+     * from the right-most label to the left-most label.
+     */
+    public function getIterator();
 }

src/DomainInterface.php

@@ -113,26 +113,26 @@ private function idnToUnicode(string $domain): string
      * Returns an array containing the formatted domain name in lowercase
      * with its associated labels in reverse order
      *
-     * For example: setDomain('wWw.uLb.Ac.be') should return ['www.ulb.ac.be', ['be', 'ac', 'ulb', 'www']];
+     * For example: setLabels('wWw.uLb.Ac.be') should return ['www.ulb.ac.be', ['be', 'ac', 'ulb', 'www']];
      *
      * @param mixed $domain
      *
      * @throws Exception If the domain is invalid
      *
-     * @return array
+     * @return string[]
      */
-    private function setDomain($domain = null): array
+    private function setLabels($domain = null): array
     {
         if ($domain instanceof DomainInterface) {
-            return [$domain->getContent(), iterator_to_array($domain, false)];
+            return iterator_to_array($domain, false);
         }
 
         if (null === $domain) {
-            return [$domain, []];
+            return [];
         }
 
         if ('' === $domain) {
-            return [$domain, ['']];
+            return [''];
         }
 
         if (!is_scalar($domain) && !method_exists($domain, '__toString')) {
@@ -155,9 +155,7 @@ private function setDomain($domain = null): array
             )
             ^(?:(?&reg_name)\.){0,126}(?&reg_name)\.?$/ix';
         if (preg_match($domain_name, $formatted_domain)) {
-            $domain = strtolower($formatted_domain);
-
-            return [$domain, array_reverse(explode('.', $domain))];
+            return array_reverse(explode('.', strtolower($formatted_domain)));
         }
 
         // a domain name can not contains URI delimiters or space
@@ -175,9 +173,7 @@ private function setDomain($domain = null): array
         //if a domain name contains UTF-8 chars it must be convertible using IDNA UTS46
         $ascii_domain = idn_to_ascii($formatted_domain, 0, INTL_IDNA_VARIANT_UTS46, $arr);
         if (0 === $arr['errors']) {
-            $idn_domain = $this->idnToUnicode($ascii_domain);
-
-            return [$idn_domain, array_reverse(explode('.', $idn_domain))];
+            return array_reverse(explode('.', $this->idnToUnicode($ascii_domain)));
         }
 
         throw new Exception(sprintf('The domain `%s` is invalid : %s', $domain, self::getIdnErrors($arr['errors'])));

src/IDNAConverterTrait.php

@@ -105,11 +105,7 @@ private static function getVendorPath(Event $event = null)
      */
     private static function getIO(Event $event = null)
     {
-        if (null !== $event) {
-            return $event->getIO();
-        }
-
-        return new class() {
+        return null !== $event ? $event->getIO() : new class() {
             public function write($messages, bool $newline = true, int $verbosity = 2)
             {
                 $this->doWrite($messages, $newline, false, $verbosity);

src/Installer.php

@@ -81,7 +81,11 @@ public static function createFromDomain(Domain $domain): self
      */
     public function __construct($publicSuffix = null, string $section = '')
     {
-        list($this->publicSuffix, $this->labels) = $this->setDomain($publicSuffix);
+        $this->labels = $this->setLabels($publicSuffix);
+        if (!empty($this->labels)) {
+            $this->publicSuffix = implode('.', array_reverse($this->labels));
+        }
+
         $this->section = $this->setSection($section);
     }
 
@@ -155,6 +159,14 @@ public function getContent()
         return $this->publicSuffix;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function __toString()
+    {
+        return (string) $this->publicSuffix;
+    }
+
     /**
      * {@inheritdoc}
      */

src/PublicSuffix.php

@@ -103,7 +103,7 @@ public function __construct(array $rules)
      *
      * @return PublicSuffix
      */
-    public function getPublicSuffix($domain = null, string $section = self::ALL_DOMAINS): PublicSuffix
+    public function getPublicSuffix($domain, string $section = self::ALL_DOMAINS): PublicSuffix
     {
         $section = $this->validateSection($section);
         $domain = $domain instanceof Domain ? $domain : new Domain($domain);
@@ -122,7 +122,7 @@ public function getPublicSuffix($domain = null, string $section = self::ALL_DOMA
      *
      * @return Domain
      */
-    public function resolve($domain = null, string $section = self::ALL_DOMAINS): Domain
+    public function resolve($domain, string $section = self::ALL_DOMAINS): Domain
     {
         $section = $this->validateSection($section);
         try {