Add native types to public API

This changeset adds native types to the public API as discussed in #219.

Once merged, I'm planning to add PHPStan in a follow-up PR which would take advantage of these types.

Builds on top of #222, #223 and reactphp/cache#60

Author: WyriHaximus

src/Config/Config.php

@@ -26,7 +26,7 @@ final class Config
      * @return self
      * @codeCoverageIgnore
      */
-    public static function loadSystemConfigBlocking()
+    public static function loadSystemConfigBlocking(): self
     {
         // Use WMIC output on Windows
         if (DIRECTORY_SEPARATOR === '\\') {
@@ -71,7 +71,7 @@ public static function loadSystemConfigBlocking()
      * @return self
      * @throws RuntimeException if the path can not be loaded (does not exist)
      */
-    public static function loadResolvConfBlocking($path = null)
+    public static function loadResolvConfBlocking(?string $path = null): self
     {
         if ($path === null) {
             $path = '/etc/resolv.conf';
@@ -122,7 +122,7 @@ public static function loadResolvConfBlocking($path = null)
      * @return self
      * @link https://ss64.com/nt/wmic.html
      */
-    public static function loadWmicBlocking($command = null)
+    public static function loadWmicBlocking(?string $command = null): self
     {
         $contents = shell_exec($command === null ? 'wmic NICCONFIG get "DNSServerSearchOrder" /format:CSV' : $command);
         preg_match_all('/(?<=[{;,"])([\da-f.:]{4,})(?=[};,"])/i', $contents, $matches);
@@ -133,5 +133,8 @@ public static function loadWmicBlocking($command = null)
         return $config;
     }
 
+    /**
+     * @var array<string>
+     */
     public $nameservers = [];
 }

src/Config/HostsFile.php

@@ -24,10 +24,9 @@ class HostsFile
     /**
      * Returns the default path for the hosts file on this system
      *
-     * @return string
      * @codeCoverageIgnore
      */
-    public static function getDefaultPath()
+    public static function getDefaultPath(): string
     {
         // use static path for all Unix-based systems
         if (DIRECTORY_SEPARATOR !== '\\') {
@@ -59,7 +58,7 @@ public static function getDefaultPath()
      * @return self
      * @throws RuntimeException if the path can not be loaded (does not exist)
      */
-    public static function loadFromPathBlocking($path = null)
+    public static function loadFromPathBlocking(?string $path = null): self
     {
         if ($path === null) {
             $path = self::getDefaultPath();
@@ -73,16 +72,23 @@ public static function loadFromPathBlocking($path = null)
         return new self($contents);
     }
 
+    /**
+     * @var string
+     */
     private $contents;
 
     /**
      * Instantiate new hosts file with the given hosts file contents
      *
      * @param string $contents
      */
-    public function __construct($contents)
+    public function __construct(string $contents)
     {
-        // remove all comments from the contents
+        /**
+         * remove all comments from the contents
+         *
+         * @var string $contents
+         */
         $contents = preg_replace('/[ \t]*#.*/', '', strtolower($contents));
 
         $this->contents = $contents;
@@ -92,9 +98,9 @@ public function __construct($contents)
      * Returns all IPs for the given hostname
      *
      * @param string $name
-     * @return string[]
+     * @return iterable<string>
      */
-    public function getIpsForHost($name)
+    public function getIpsForHost(string $name): iterable
     {
         $name = strtolower($name);
 
@@ -113,17 +119,15 @@ public function getIpsForHost($name)
                 }
             }
         }
-
-        return $ips;
     }
 
     /**
      * Returns all hostnames for the given IPv4 or IPv6 address
      *
      * @param string $ip
-     * @return string[]
+     * @return iterable<string>
      */
-    public function getHostsForIp($ip)
+    public function getHostsForIp(string $ip): iterable
     {
         // check binary representation of IP to avoid string case and short notation
         $ip = @inet_pton($ip);

src/Model/Record.php

@@ -131,18 +131,18 @@ final class Record
      *   considered a BC break. See the format definition of known types above
      *   for more details.
      *
-     * @var string|string[]|array
+     * @var string|array<string>
      */
     public $data;
 
     /**
      * @param string                $name
-     * @param int                   $type
-     * @param int                   $class
-     * @param int                   $ttl
-     * @param string|string[]|array $data
+     * @param int                    $type
+     * @param int                        $class
+     * @param int                        $ttl
+     * @param string|array<string> $data
      */
-    public function __construct($name, $type, $class, $ttl, $data)
+    public function __construct(string $name, int $type, int $class, int $ttl, $data)
     {
         $this->name     = $name;
         $this->type     = $type;

src/Query/CachingExecutor.php

@@ -5,6 +5,7 @@
 use React\Cache\CacheInterface;
 use React\Dns\Model\Message;
 use React\Promise\Promise;
+use React\Promise\PromiseInterface;
 
 final class CachingExecutor implements ExecutorInterface
 {
@@ -24,7 +25,7 @@ public function __construct(ExecutorInterface $executor, CacheInterface $cache)
         $this->cache = $cache;
     }
 
-    public function query(Query $query)
+    public function query(Query $query): PromiseInterface
     {
         $id = $query->name . ':' . $query->type . ':' . $query->class;
 
@@ -65,7 +66,7 @@ function (Message $message) use ($id) {
      * @return int
      * @internal
      */
-    public function ttl(Message $message)
+    public function ttl(Message $message): int
     {
         // select TTL from answers (should all be the same), use smallest value if available
         // @link https://tools.ietf.org/html/rfc2181#section-5.2

src/Query/CoopExecutor.php

@@ -3,6 +3,7 @@
 namespace React\Dns\Query;
 
 use React\Promise\Promise;
+use React\Promise\PromiseInterface;
 
 /**
  * Cooperatively resolves hosts via the given base executor to ensure same query is not run concurrently
@@ -45,7 +46,7 @@ public function __construct(ExecutorInterface $base)
         $this->executor = $base;
     }
 
-    public function query(Query $query)
+    public function query(Query $query): PromiseInterface
     {
         $key = $this->serializeQueryToIdentity($query);
         if (isset($this->pending[$key])) {

src/Query/ExecutorInterface.php

@@ -2,6 +2,9 @@
 
 namespace React\Dns\Query;
 
+use React\Dns\Model\Message;
+use React\Promise\PromiseInterface;
+
 interface ExecutorInterface
 {
     /**
@@ -36,8 +39,8 @@ interface ExecutorInterface
      * ```
      *
      * @param Query $query
-     * @return \React\Promise\PromiseInterface<\React\Dns\Model\Message>
+     * @return PromiseInterface<Message>
      *     resolves with response message on success or rejects with an Exception on error
      */
-    public function query(Query $query);
+    public function query(Query $query): PromiseInterface;
 }

src/Query/FallbackExecutor.php

@@ -3,6 +3,7 @@
 namespace React\Dns\Query;
 
 use React\Promise\Promise;
+use React\Promise\PromiseInterface;
 
 final class FallbackExecutor implements ExecutorInterface
 {
@@ -15,7 +16,7 @@ public function __construct(ExecutorInterface $executor, ExecutorInterface $fall
         $this->fallback = $fallback;
     }
 
-    public function query(Query $query)
+    public function query(Query $query): PromiseInterface
     {
         $cancelled = false;
         $promise = $this->executor->query($query);

src/Query/HostsFileExecutor.php

@@ -5,6 +5,7 @@
 use React\Dns\Config\HostsFile;
 use React\Dns\Model\Message;
 use React\Dns\Model\Record;
+use React\Promise\PromiseInterface;
 use function React\Promise\resolve;
 
 /**
@@ -25,7 +26,7 @@ public function __construct(HostsFile $hosts, ExecutorInterface $fallback)
         $this->fallback = $fallback;
     }
 
-    public function query(Query $query)
+    public function query(Query $query): PromiseInterface
     {
         if ($query->class === Message::CLASS_IN && ($query->type === Message::TYPE_A || $query->type === Message::TYPE_AAAA)) {
             // forward lookup for type A or AAAA

src/Query/RetryExecutor.php

@@ -16,7 +16,7 @@ public function __construct(ExecutorInterface $executor, $retries = 2)
         $this->retries = $retries;
     }
 
-    public function query(Query $query)
+    public function query(Query $query): PromiseInterface
     {
         return $this->tryQuery($query, $this->retries);
     }

src/Query/SelectiveTransportExecutor.php

@@ -3,6 +3,7 @@
 namespace React\Dns\Query;
 
 use React\Promise\Promise;
+use React\Promise\PromiseInterface;
 
 /**
  * Send DNS queries over a UDP or TCP/IP stream transport.
@@ -61,7 +62,7 @@ public function __construct(ExecutorInterface $datagramExecutor, ExecutorInterfa
         $this->streamExecutor = $streamExecutor;
     }
 
-    public function query(Query $query)
+    public function query(Query $query): PromiseInterface
     {
         $pending = $this->datagramExecutor->query($query);