Skip to content

Commit 6c7b3af

Browse files
WyriHaximusWyriHaximus
committed
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
1 parent 30c5e43 commit 6c7b3af

20 files changed

+101
-117
lines changed

‎src/Config/Config.php‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ final class Config
2626
* @return self
2727
* @codeCoverageIgnore
2828
*/
29-
public static function loadSystemConfigBlocking()
29+
public static function loadSystemConfigBlocking(): self
3030
{
3131
// Use WMIC output on Windows
3232
if (DIRECTORY_SEPARATOR === '\\') {
@@ -71,7 +71,7 @@ public static function loadSystemConfigBlocking()
7171
* @return self
7272
* @throws RuntimeException if the path can not be loaded (does not exist)
7373
*/
74-
public static function loadResolvConfBlocking($path = null)
74+
public static function loadResolvConfBlocking(?string $path = null): self
7575
{
7676
if ($path === null) {
7777
$path = '/etc/resolv.conf';
@@ -122,7 +122,7 @@ public static function loadResolvConfBlocking($path = null)
122122
* @return self
123123
* @link https://ss64.com/nt/wmic.html
124124
*/
125-
public static function loadWmicBlocking($command = null)
125+
public static function loadWmicBlocking(?string $command = null): self
126126
{
127127
$contents = shell_exec($command === null ? 'wmic NICCONFIG get "DNSServerSearchOrder" /format:CSV' : $command);
128128
preg_match_all('/(?<=[{;,"])([\da-f.:]{4,})(?=[};,"])/i', $contents, $matches);
@@ -133,5 +133,8 @@ public static function loadWmicBlocking($command = null)
133133
return $config;
134134
}
135135

136+
/**
137+
* @var array<string>
138+
*/
136139
public $nameservers = [];
137140
}

‎src/Config/HostsFile.php‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,9 @@ class HostsFile
2424
/**
2525
* Returns the default path for the hosts file on this system
2626
*
27-
* @return string
2827
* @codeCoverageIgnore
2928
*/
30-
public static function getDefaultPath()
29+
public static function getDefaultPath(): string
3130
{
3231
// use static path for all Unix-based systems
3332
if (DIRECTORY_SEPARATOR !== '\\') {
@@ -59,7 +58,7 @@ public static function getDefaultPath()
5958
* @return self
6059
* @throws RuntimeException if the path can not be loaded (does not exist)
6160
*/
62-
public static function loadFromPathBlocking($path = null)
61+
public static function loadFromPathBlocking(?string $path = null): self
6362
{
6463
if ($path === null) {
6564
$path = self::getDefaultPath();
@@ -77,10 +76,8 @@ public static function loadFromPathBlocking($path = null)
7776

7877
/**
7978
* Instantiate new hosts file with the given hosts file contents
80-
*
81-
* @param string $contents
8279
*/
83-
public function __construct($contents)
80+
public function __construct(string $contents)
8481
{
8582
// remove all comments from the contents
8683
$contents = preg_replace('/[ \t]*#.*/', '', strtolower($contents));
@@ -92,9 +89,9 @@ public function __construct($contents)
9289
* Returns all IPs for the given hostname
9390
*
9491
* @param string $name
95-
* @return string[]
92+
* @return array<string>
9693
*/
97-
public function getIpsForHost($name)
94+
public function getIpsForHost(string $name): array
9895
{
9996
$name = strtolower($name);
10097

@@ -121,9 +118,9 @@ public function getIpsForHost($name)
121118
* Returns all hostnames for the given IPv4 or IPv6 address
122119
*
123120
* @param string $ip
124-
* @return string[]
121+
* @return array<string>
125122
*/
126-
public function getHostsForIp($ip)
123+
public function getHostsForIp(string $ip): array
127124
{
128125
// check binary representation of IP to avoid string case and short notation
129126
$ip = @inet_pton($ip);

‎src/Model/Message.php‎

Lines changed: 8 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -82,11 +82,8 @@ final class Message
8282

8383
/**
8484
* Creates a new request message for the given query
85-
*
86-
* @param Query $query
87-
* @return self
8885
*/
89-
public static function createRequestForQuery(Query $query)
86+
public static function createRequestForQuery(Query $query): self
9087
{
9188
$request = new Message();
9289
$request->id = self::generateId();
@@ -99,11 +96,9 @@ public static function createRequestForQuery(Query $query)
9996
/**
10097
* Creates a new response message for the given query with the given answer records
10198
*
102-
* @param Query $query
103-
* @param Record[] $answers
104-
* @return self
99+
* @param array<Record> $answers
105100
*/
106-
public static function createResponseWithAnswersForQuery(Query $query, array $answers)
101+
public static function createResponseWithAnswersForQuery(Query $query, array $answers): self
107102
{
108103
$response = new Message();
109104
$response->id = self::generateId();
@@ -126,11 +121,10 @@ public static function createResponseWithAnswersForQuery(Query $query, array $an
126121
* DNS response messages can not guess the message ID to avoid possible
127122
* cache poisoning attacks.
128123
*
129-
* @return int
130124
* @see self::getId()
131125
* @codeCoverageIgnore
132126
*/
133-
private static function generateId()
127+
private static function generateId(): int
134128
{
135129
return random_int(0, 0xffff);
136130
}
@@ -199,22 +193,22 @@ private static function generateId()
199193
* ];
200194
* ```
201195
*
202-
* @var Query[]
196+
* @var array<Query>
203197
*/
204198
public $questions = [];
205199

206200
/**
207-
* @var Record[]
201+
* @var array<Record>
208202
*/
209203
public $answers = [];
210204

211205
/**
212-
* @var Record[]
206+
* @var array<Record>
213207
*/
214208
public $authority = [];
215209

216210
/**
217-
* @var Record[]
211+
* @var array<Record>
218212
*/
219213
public $additional = [];
220214
}

‎src/Model/Record.php‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -131,18 +131,14 @@ final class Record
131131
* considered a BC break. See the format definition of known types above
132132
* for more details.
133133
*
134-
* @var string|string[]|array
134+
* @var string|array<string>
135135
*/
136136
public $data;
137137

138138
/**
139-
* @param string $name
140-
* @param int $type
141-
* @param int $class
142-
* @param int $ttl
143-
* @param string|string[]|array $data
139+
* @param string|array<string> $data
144140
*/
145-
public function __construct($name, $type, $class, $ttl, $data)
141+
public function __construct(string $name, int $type, int $class, int $ttl, $data)
146142
{
147143
$this->name = $name;
148144
$this->type = $type;

‎src/Protocol/BinaryDumper.php‎

Lines changed: 9 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,7 @@
88

99
final class BinaryDumper
1010
{
11-
/**
12-
* @param Message $message
13-
* @return string
14-
*/
15-
public function toBinary(Message $message)
11+
public function toBinary(Message $message): string
1612
{
1713
$data = '';
1814

@@ -25,11 +21,7 @@ public function toBinary(Message $message)
2521
return $data;
2622
}
2723

28-
/**
29-
* @param Message $message
30-
* @return string
31-
*/
32-
private function headerToBinary(Message $message)
24+
private function headerToBinary(Message $message): string
3325
{
3426
$data = '';
3527

@@ -56,10 +48,9 @@ private function headerToBinary(Message $message)
5648
}
5749

5850
/**
59-
* @param Query[] $questions
60-
* @return string
51+
* @param array<Query> $questions
6152
*/
62-
private function questionToBinary(array $questions)
53+
private function questionToBinary(array $questions): string
6354
{
6455
$data = '';
6556

@@ -72,10 +63,10 @@ private function questionToBinary(array $questions)
7263
}
7364

7465
/**
75-
* @param Record[] $records
66+
* @param array<Record> $records
7667
* @return string
7768
*/
78-
private function recordsToBinary(array $records)
69+
private function recordsToBinary(array $records): string
7970
{
8071
$data = '';
8172

@@ -163,10 +154,9 @@ private function recordsToBinary(array $records)
163154
}
164155

165156
/**
166-
* @param string[] $texts
167-
* @return string
157+
* @param array<string> $texts
168158
*/
169-
private function textsToBinary(array $texts)
159+
private function textsToBinary(array $texts): string
170160
{
171161
$data = '';
172162
foreach ($texts as $text) {
@@ -175,11 +165,7 @@ private function textsToBinary(array $texts)
175165
return $data;
176166
}
177167

178-
/**
179-
* @param string $host
180-
* @return string
181-
*/
182-
private function domainNameToBinary($host)
168+
private function domainNameToBinary(string $host): string
183169
{
184170
if ($host === '') {
185171
return "\0";

‎src/Protocol/Parser.php‎

Lines changed: 13 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,9 @@ final class Parser
1717
/**
1818
* Parses the given raw binary message into a Message object
1919
*
20-
* @param string $data
2120
* @throws InvalidArgumentException
22-
* @return Message
2321
*/
24-
public function parseMessage($data)
22+
public function parseMessage(string $data): Message
2523
{
2624
$message = $this->parse($data, 0);
2725
if ($message === null) {
@@ -32,11 +30,9 @@ public function parseMessage($data)
3230
}
3331

3432
/**
35-
* @param string $data
36-
* @param int $consumed
3733
* @return ?Message
3834
*/
39-
private function parse($data, $consumed)
35+
private function parse(string $data, int $consumed)
4036
{
4137
if (!isset($data[12 - 1])) {
4238
return null;
@@ -99,11 +95,9 @@ private function parse($data, $consumed)
9995
}
10096

10197
/**
102-
* @param string $data
103-
* @param int $consumed
104-
* @return array
98+
* @return array{Query, int}|array{null, null}
10599
*/
106-
private function parseQuestion($data, $consumed)
100+
private function parseQuestion(string $data, int $consumed): array
107101
{
108102
list($labels, $consumed) = $this->readLabels($data, $consumed);
109103

@@ -125,11 +119,9 @@ private function parseQuestion($data, $consumed)
125119
}
126120

127121
/**
128-
* @param string $data
129-
* @param int $consumed
130-
* @return array An array with a parsed Record on success or array with null if data is invalid/incomplete
122+
* @return array{Record, int}|array{null, null} An array with a parsed Record on success or array with null if data is invalid/incomplete
131123
*/
132-
private function parseRecord($data, $consumed)
124+
private function parseRecord(string $data, int $consumed): array
133125
{
134126
list($name, $consumed) = $this->readDomain($data, $consumed);
135127

@@ -278,7 +270,10 @@ private function parseRecord($data, $consumed)
278270
];
279271
}
280272

281-
private function readDomain($data, $consumed)
273+
/**
274+
* @return array{string, int}|array{null, null}
275+
*/
276+
private function readDomain(string $data, int $consumed): array
282277
{
283278
list ($labels, $consumed) = $this->readLabels($data, $consumed);
284279

@@ -302,12 +297,10 @@ function ($label) {
302297
}
303298

304299
/**
305-
* @param string $data
306-
* @param int $consumed
307-
* @param int $compressionDepth maximum depth for compressed labels to avoid unreasonable recursion
308-
* @return array
300+
* @param int $compressionDepth maximum depth for compressed labels to avoid unreasonable recursion
301+
* @return array{array<string>, int}|array{null, null}
309302
*/
310-
private function readLabels($data, $consumed, $compressionDepth = 127)
303+
private function readLabels(string $data, int $consumed, int $compressionDepth = 127): array
311304
{
312305
$labels = [];
313306

‎src/Query/CachingExecutor.php‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
use React\Cache\CacheInterface;
66
use React\Dns\Model\Message;
77
use React\Promise\Promise;
8+
use React\Promise\PromiseInterface;
89

910
final class CachingExecutor implements ExecutorInterface
1011
{
@@ -24,7 +25,7 @@ public function __construct(ExecutorInterface $executor, CacheInterface $cache)
2425
$this->cache = $cache;
2526
}
2627

27-
public function query(Query $query)
28+
public function query(Query $query): PromiseInterface
2829
{
2930
$id = $query->name . ':' . $query->type . ':' . $query->class;
3031

‎src/Query/CoopExecutor.php‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
namespace React\Dns\Query;
44

55
use React\Promise\Promise;
6+
use React\Promise\PromiseInterface;
67

78
/**
89
* 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)
4546
$this->executor = $base;
4647
}
4748

48-
public function query(Query $query)
49+
public function query(Query $query): PromiseInterface
4950
{
5051
$key = $this->serializeQueryToIdentity($query);
5152
if (isset($this->pending[$key])) {

‎src/Query/ExecutorInterface.php‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
namespace React\Dns\Query;
44

5+
use React\Dns\Model\Message;
6+
use React\Promise\PromiseInterface;
7+
58
interface ExecutorInterface
69
{
710
/**
@@ -36,8 +39,8 @@ interface ExecutorInterface
3639
* ```
3740
*
3841
* @param Query $query
39-
* @return \React\Promise\PromiseInterface<\React\Dns\Model\Message>
42+
* @return PromiseInterface<Message>
4043
* resolves with response message on success or rejects with an Exception on error
4144
*/
42-
public function query(Query $query);
45+
public function query(Query $query): PromiseInterface;
4346
}

0 commit comments

Comments
 (0)