You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+83-47Lines changed: 83 additions & 47 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,7 +28,6 @@ System Requirements
28
28
You need:
29
29
30
30
-**PHP >= 7.0** but the latest stable version of PHP is recommended
31
-
- the `mbstring` extension
32
31
- the `intl` extension
33
32
34
33
Dependencies
@@ -48,27 +47,7 @@ Documentation
48
47
49
48
### Domain name resolution
50
49
51
-
In order to resolve a domain name one we must:
52
-
53
-
- Convert the Public Suffix List (PSL) into a structure usable in PHP
54
-
- Resolve the domain name against the PSL rules
55
-
56
-
PSL Conversion is done using the `Pdp\Converter` class.
57
-
58
-
~~~php
59
-
<?php
60
-
61
-
namespace Pdp;
62
-
63
-
final class Converter
64
-
{
65
-
public function convert(string $content): array
66
-
}
67
-
~~~
68
-
69
-
The `Pdp\Converter::convert` method expects the raw content of a PSL and returns its `array` representation.
70
-
71
-
Once the PSL has been converted we can used the returned `array` to instantiate a `Pdp\Rules` object which is responsable for resolving a given domain name.
50
+
The `Pdp\Rules` object is responsible for domain name resolution.
72
51
73
52
~~~php
74
53
<?php
@@ -84,21 +63,26 @@ final class Rules
84
63
public static function createFromPath(string $path, $context = null): self
85
64
public static function createFromString(string $content): self
86
65
public function __construct(array $rules)
66
+
public function getPublicSuffix(string $domain = null, string $section = self::ALL_DOMAINS): PublicSuffix
87
67
public function resolve(string $domain = null, string $section = self::ALL_DOMAINS): Domain
88
68
}
89
69
~~~
90
70
91
-
Starting with version 5.1.0, the following named constructors arre added to ease `Rules` instantiation.
71
+
**NEW IN VERSION 5.2:**
92
72
93
-
-`Rules::createFromString` expects a string content which follows [the PSL format](https://publicsuffix.org/list/#list-format);
73
+
-`Rules::getPublicSuffix` returns a `PublicSuffix` object determined from the `Rules` object;
74
+
75
+
**NEW IN VERSION 5.1:**
94
76
77
+
-`Rules::createFromString` expects a string content which follows [the PSL format](https://publicsuffix.org/list/#list-format);
95
78
-`Rules::createFromPath` expects a valid path to a readable PSL. You can optionnally submit a context resource as defined in PHP's `fopen` function;
96
79
97
80
Both named constructors:
98
81
99
82
- uses internally a `Pdp\Converter` object to convert the raw content into a suitable array to instantiate a valid `Pdp\Rules`;
100
83
- do not have any cache functionnality;
101
84
85
+
#### Usage
102
86
103
87
Domain name resolution is done using the `Pdp\Rules::resolve` method which expects at most two parameters:
104
88
@@ -108,9 +92,7 @@ Domain name resolution is done using the `Pdp\Rules::resolve` method which expec
108
92
-`Rules::ICANN_DOMAINS`, to validate against the PSL ICANN DOMAINS section only.
109
93
-`Rules::PRIVATE_DOMAINS`, to validate against the PSL PRIVATE DOMAINS section only.
110
94
111
-
By default, the `$section` argument is equal to `Rules::ALL_DOMAINS`. If an unsupported section is submitted a `Pdp\Exception` exception will be thrown.
112
-
113
-
**WARNING: The `Pdp\Rules::resolve` does not validate the submitted host. You are require to use a host validator prior to using this library.**
95
+
By default, the `$section` argument is equal to `Rules::ALL_DOMAINS`. If an unsupported section is submitted a `Pdp\Exception` exception will be thrown.
114
96
115
97
The `Pdp\Rules::resolve` returns a `Pdp\Domain` object.
116
98
@@ -126,34 +108,29 @@ final class Domain implements JsonSerializable
126
108
public function isKnown(): bool;
127
109
public function isICANN(): bool;
128
110
public function isPrivate(): bool;
111
+
public function toUnicode(): self;
112
+
public function toAscii(): self;
129
113
}
130
114
~~~
131
115
132
-
The `Pdp\Domain` getter methods returns:
133
-
134
-
- the submitted domain name using `Pdp\Domain::getDomain`
135
-
- the public suffix part normalized according to the domain using `Pdp\Domain::getPublicSuffix`
136
-
- the registrable domain part using `Pdp\Domain::getRegistrableDomain`
137
-
- the subdomain part using `Pdp\Domain::getSubDomain`.
138
-
139
-
If the domain name or some of its part are seriously malformed or unrecognized, the getter methods will return `null`.
116
+
**NEW IN VERSION 5.2:**
140
117
141
-
**The Domain name status depends on the PSL section used to resolve it:**
142
-
143
-
-`Pdp\Domain::isKnown` returns `true` if the public suffix is found in the selected PSL;
144
-
-`Pdp\Domain::isICANN` returns `true` if the public suffix is found in a selected PSL which includes the ICANN DOMAINS section;
145
-
-`Pdp\Domain::isPrivate` returns `true` if the public suffix is found in a selected PSL which includes the PRIVATE DOMAINS section;
118
+
-`Domain::toUnicode` returns an instance with the domain converted to its unicode representation;
119
+
-`Domain::toAscii` returns an instance with the domain converted to its ascii representation;
120
+
-`Domain::getDomain` will lowercase the domain name to normalize its content;
146
121
147
-
**THIS EXAMPLE ILLUSTRATES HOW EACH OBJECT IS USED BUT SHOULD BE AVOID IN PRODUCTON**
122
+
**THIS EXAMPLE ILLUSTRATES HOW THE OBJECT WORK BUT SHOULD BE AVOIDED IN PRODUCTON**
- the submitted domain name using `Pdp\Domain::getDomain`
172
+
- the public suffix part normalized according to the domain using `Pdp\Domain::getPublicSuffix`
173
+
- the registrable domain part using `Pdp\Domain::getRegistrableDomain`
174
+
- the subdomain part using `Pdp\Domain::getSubDomain`.
175
+
176
+
If the domain name or some of its part are seriously malformed or unrecognized, the getter methods will return `null`.
177
+
178
+
**The Domain name status depends on the PSL section used to resolve it:**
179
+
180
+
-`Pdp\Domain::isKnown` returns `true` if the public suffix is found in the selected PSL;
181
+
-`Pdp\Domain::isICANN` returns `true` if the public suffix is found using a PSL which includes the ICANN DOMAINS section;
182
+
-`Pdp\Domain::isPrivate` returns `true` if the public suffix is found using a PSL which includes the PRIVATE DOMAINS section;
183
+
184
+
The `Rules::getPublicSuffix` method expects the same arguments as `Rules::resolve` but returns a `Pdp\PublicSuffix` object instead.
185
+
186
+
~~~php
187
+
<?php
188
+
189
+
final class PublicSuffix implements Countable, JsonSerializable
190
+
{
191
+
public function getContent(): ?string
192
+
public function isKnown(): bool;
193
+
public function isICANN(): bool;
194
+
public function isPrivate(): bool;
195
+
public function toUnicode(): self;
196
+
public function toAscii(): self;
197
+
}
198
+
~~~
199
+
200
+
While `Rules::resolve` will only throws an exception if the section value is invalid, the `Rules::getPublicSuffix` is more restrictive and will additionnally throw if:
201
+
202
+
- The domain name is invalid or seriously malformed
203
+
- The public suffix can not be normalized and converted using the domain encoding.
204
+
192
205
**WARNING:**
193
206
207
+
**The `Pdp\Rules::resolve` does not validate the submitted host. You are require to use a host validator prior to using this library.**
208
+
194
209
**You should never use the library this way in production, without, at least, a caching mechanism to reduce PSL downloads.**
195
210
196
-
**Some people use the PSL to determine what is a valid domain name and what isn't. This is dangerous, particularly in these days where new gTLDs are arriving at a rapid pace, if your software does not regularly receive PSL updates, it may erroneously think new gTLDs are not known. The DNS is the proper source for this information. If you must use it for this purpose, please do not bake static copies of the PSL into your software with no update mechanism.**
211
+
**Using the PSL to determine what is a valid domain name and what isn'tis dangerous, particularly in these days where new gTLDs are arriving at a rapid pace. The DNS is the proper source for this information. If you must use this library for this purpose, please consider integrating a PSL update mechanism into your software.**
197
212
198
213
### Public Suffix List Maintenance
199
214
@@ -221,8 +236,9 @@ To work as intended, the `Pdp\Manager` constructor requires:
221
236
222
237
- a [PSR-16](http://www.php-fig.org/psr/psr-16/) Cache object to store the rules locally.
223
238
224
-
- a `Pdp\HttpClient` object to retrieve the PSL.
225
-
the `Pdp\HttpClient` is a simple interface which exposes the `HttpClient::getContent` method. This method expects a string URL representation has its sole argument and returns the body from the given URL resource as a string.
239
+
- a `Pdp\HttpClient` object to retrieve the PSL.
240
+
241
+
The `Pdp\HttpClient` is a simple interface which exposes the `HttpClient::getContent` method. This method expects a string URL representation has its sole argument and returns the body from the given URL resource as a string.
226
242
If an error occurs while retrieving such body a `HttpClientException` exception is thrown.
227
243
228
244
~~~php
@@ -411,6 +427,26 @@ Contributing
411
427
412
428
Contributions are welcome and will be fully credited. Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
413
429
430
+
Testing
431
+
-------
432
+
433
+
`pdp-domain-parser` has:
434
+
435
+
- a [PHPUnit](https://phpunit.de) test suite
436
+
- a coding style compliance test suite using [PHP CS Fixer](http://cs.sensiolabs.org/).
437
+
- a code analysis compliance test suite using [PHPStan](https://github.com/phpstan/phpstan).
438
+
439
+
To run the tests, run the following command from the project folder.
440
+
441
+
```bash
442
+
$ composer test
443
+
```
444
+
445
+
Security
446
+
-------
447
+
448
+
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
0 commit comments