Adding methods to improve Rules public API

Author: nyamsprod

src/Rules.php

@@ -211,19 +211,74 @@ public function resolve($domain, string $section = self::ALL_DOMAINS): Domain
     {
         $section = $this->validateSection($section);
         try {
-            $domain = $domain instanceof Domain
-                ? $domain
-                : new Domain($domain, null, $this->asciiIDNAOption, $this->unicodeIDNAOption);
-            if (!$domain->isResolvable()) {
-                return $domain;
+            if ('' === $section) {
+                return $this->cookieResolve($domain);
+            } elseif (self::ICANN_DOMAINS === $section) {
+                return $this->icannResolve($domain);
             }
 
-            return $domain->resolve($this->findPublicSuffix($domain, $section));
-        } catch (Exception $e) {
+            return $this->privateResolve($domain);
+        } catch (CouldNotResolvePublicSuffix $exception) {
+            return new Domain($domain, null, $this->asciiIDNAOption, $this->unicodeIDNAOption);
+        } catch (Exception $exception) {
             return new Domain(null, null, $this->asciiIDNAOption, $this->unicodeIDNAOption);
         }
     }
 
+    /**
+     * Returns PSL info for a given domain against the PSL rules for cookie domain detection.
+     *
+     * @param mixed $domain the domain value
+     */
+    public function cookieResolve($domain): Domain
+    {
+        $domain = $this->validateDomain($domain);
+
+        return $domain->resolve($this->findPublicSuffix($domain, ''));
+    }
+
+    /**
+     * Returns PSL info for a given domain against the PSL rules for ICANN domain detection.
+     *
+     * @param mixed $domain
+     */
+    public function icannResolve($domain): Domain
+    {
+        $domain = $this->validateDomain($domain);
+
+        return $domain->resolve($this->findPublicSuffix($domain, self::ICANN_DOMAINS));
+    }
+
+    /**
+     * Returns PSL info for a given domain against the PSL rules for private domain detection.
+     *
+     * @param mixed $domain
+     */
+    public function privateResolve($domain): Domain
+    {
+        $domain = $this->validateDomain($domain);
+
+        return $domain->resolve($this->findPublicSuffix($domain, self::PRIVATE_DOMAINS));
+    }
+
+    /**
+     * Returns PSL info for a given domain.
+     *
+     * @param mixed $domain
+     */
+    private function validateDomain($domain): Domain
+    {
+        if (!($domain instanceof Domain)) {
+            $domain = new Domain($domain, null, $this->asciiIDNAOption, $this->unicodeIDNAOption);
+        }
+
+        if (!$domain->isResolvable()) {
+            throw new CouldNotResolvePublicSuffix(sprintf('The domain `%s` can not contain a public suffix', $domain->getContent()));
+        }
+
+        return $domain;
+    }
+
     /**
      * Assert the section status.
      *

tests/RulesTest.php

@@ -114,6 +114,10 @@ public function testwithIDNAOptions(): void
 
     /**
      * @covers ::resolve
+     * @covers ::cookieResolve
+     * @covers ::icannResolve
+     * @covers ::privateResolve
+     * @covers ::validateDomain
      * @covers ::validateSection
      * @covers \Pdp\Domain::isResolvable
      * @covers \Pdp\PublicSuffix::setSection
@@ -191,6 +195,8 @@ public function testIsSuffixValidTrue(): void
 
     /**
      * @covers ::resolve
+     * @covers ::cookieResolve
+     * @covers ::validateDomain
      * @covers ::validateSection
      * @covers \Pdp\Domain::isResolvable
      * @covers ::findPublicSuffix
@@ -215,6 +221,8 @@ public function testIsSuffixValidFalseWithPunycoded(): void
 
     /**
      * @covers ::resolve
+     * @covers ::icannResolve
+     * @covers ::validateDomain
      * @covers ::validateSection
      * @covers \Pdp\Domain::isResolvable
      * @covers ::findPublicSuffix
@@ -239,6 +247,8 @@ public function testSubDomainIsNull(): void
 
     /**
      * @covers ::resolve
+     * @covers ::cookieResolve
+     * @covers ::validateDomain
      * @covers ::validateSection
      * @covers \Pdp\IDNAConverterTrait::parse
      */
@@ -281,6 +291,8 @@ public function testWithAbsoluteHostInvalid(): void
 
     /**
      * @covers ::resolve
+     * @covers ::privateResolve
+     * @covers ::validateDomain
      * @covers ::validateSection
      * @covers ::findPublicSuffix
      * @covers ::findPublicSuffixFromSection
@@ -299,6 +311,8 @@ public function testWithPrivateDomainInvalid(): void
 
     /**
      * @covers ::resolve
+     * @covers ::privateResolve
+     * @covers ::validateDomain
      * @covers ::validateSection
      * @covers ::findPublicSuffix
      * @covers ::findPublicSuffixFromSection
@@ -367,6 +381,8 @@ public function testWithDomainInterfaceObject(): void
 
     /**
      * @covers ::resolve
+     * @covers ::icannResolve
+     * @covers ::validateDomain
      * @covers \Pdp\Domain::setRegistrableDomain
      * @covers \Pdp\Domain::getRegistrableDomain
      * @dataProvider parseDataProvider
@@ -383,6 +399,8 @@ public function testGetRegistrableDomain($publicSuffix, $registrableDomain, $dom
 
     /**
      * @covers ::resolve
+     * @covers ::icannResolve
+     * @covers ::validateDomain
      * @covers \Pdp\IDNAConverterTrait::parse
      * @covers \Pdp\Domain::setPublicSuffix
      * @covers \Pdp\Domain::getPublicSuffix