Skip to content

Commit bd920e9

Browse files
nyamsprodnyamsprod
committed
adding Converter to documentation
1 parent 1202939 commit bd920e9

File tree

3 files changed

+125
-98
lines changed

3 files changed

+125
-98
lines changed

‎README.md

Lines changed: 122 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,127 @@ $ composer require jeremykendall/php-domain-parser
4444
Documentation
4545
--------
4646

47+
### Public Suffix List conversion
48+
49+
~~~php
50+
<?php
51+
52+
namespace Pdp;
53+
54+
final class Converter
55+
{
56+
public function convert(string $content): array
57+
}
58+
~~~
59+
60+
To resolve the submitted domain name we must first convert the Public Suffix List into a structure consommable by the library. This is done using the `Pdp\Converter` class which converts the list into an `array` representation that can be then used by the `Pdp\Rules` object.
61+
62+
~~~php
63+
<?php
64+
65+
use Pdp\Converter;
66+
use Pdp\Rules;
67+
68+
$content = file_get_contents('https://raw.githubusercontent.com/publicsuffix/list/master/public_suffix_list.dat');
69+
$converter = new Converter();
70+
$arr_rules = $converter->convert($raw);
71+
$rules = new Rules($arr_rules);
72+
~~~
73+
74+
### Domain name resolution
75+
76+
~~~php
77+
<?php
78+
79+
namespace Pdp;
80+
81+
final class Rules
82+
{
83+
const ALL_DOMAINS = 'ALL_DOMAINS';
84+
const ICANN_DOMAINS = 'ICANN_DOMAINS';
85+
const PRIVATE_DOMAINS = 'PRIVATE_DOMAINS';
86+
87+
public function __construct(array $rules)
88+
public function resolve(string $domain = null, string $type = self::ALL_DOMAINS): Domain
89+
}
90+
~~~
91+
92+
The `Rules` constructor expects a `array` representation of the Public Suffix List. This `array` representation is constructed using the `Pdp\Converter` class.
93+
94+
The `Rules` class resolves the submitted domain against the parsed rules from the PSL. This is done using the `Rules::resolve` method which returns a `Pdp\Domain` object. The method expects
95+
96+
- a valid domain name as a string
97+
- a string to optionnally specify which section of the PSL you want to validate the given domain against.
98+
By default all sections are used `Rules::ALL_DOMAINS` but you can validate your domain against the ICANN only section (`Rules::ICANN_DOMAINS` or the private section (`Rules::PRIVATE_DOMAINS`) of the PSL.
99+
100+
~~~php
101+
<?php
102+
103+
final class Domain implements JsonSerializable
104+
{
105+
public function getDomain(): ?string
106+
public function getPublicSuffix(): ?string
107+
public function getRegistrableDomain(): ?string
108+
public function getSubDomain(); ?string
109+
public function isKnown(): bool;
110+
public function isICANN(): bool;
111+
public function isPrivate(): bool;
112+
}
113+
~~~
114+
115+
The `Domain` getters method always return normalized value according to the domain status against the PSL rules.
116+
117+
<p class="message-notice"><code>Domain::isKnown</code> status depends on the PSL rules used. For the same domain, depending on the rules used a domain public suffix may be known or not.</p>
118+
119+
~~~php
120+
<?php
121+
122+
use Pdp\Converter;
123+
use Pdp\Rules;
124+
125+
$content = file_get_contents('https://raw.githubusercontent.com/publicsuffix/list/master/public_suffix_list.dat');
126+
$arr = (new Converter())->convert($raw);
127+
$rules = new Rules($arr);
128+
129+
$domain = $rules->resolve('www.ulb.ac.be');
130+
$domain->getDomain(); //returns 'www.ulb.ac.be'
131+
$domain->getPublicSuffix(); //returns 'ac.be'
132+
$domain->getRegistrableDomain(); //returns 'ulb.ac.be'
133+
$domain->getSubDomain(); //returns 'www'
134+
$domain->isKnown(); //returns true
135+
$domain->isICANN(); //returns true
136+
$domain->isPrivate(); //returns false
137+
echo json_encode($domain, JSON_PRETTY_PRINT);
138+
// returns
139+
// {
140+
// "domain": "www.ulb.ac.be",
141+
// "registrableDomain": "ulb.ac.be",
142+
// "subDomain": "www",
143+
// "publicSuffix": "ac.be",
144+
// "isKnown": true,
145+
// "isICANN": true,
146+
// "isPrivate": false
147+
// }
148+
149+
//let's resolve the same domain against the PRIVATE DOMAIN SECTION
150+
151+
$domain = $rules->resolve('www.ulb.ac.be', Rules::PRIVATE_DOMAINS);
152+
$domain->getDomain(); //returns 'www.ulb.ac.be'
153+
$domain->getPublicSuffix(); //returns 'be'
154+
$domain->getRegistrableDomain(); //returns 'ac.be'
155+
$domain->getSubDomain(); //returns 'www.ulb'
156+
$domain->isKnown(); //returns false
157+
$domain->isICANN(); //returns false
158+
$domain->isPrivate(); //returns false
159+
~~~
160+
161+
<p class="message-warning"><strong>Warning:</strong> 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.</p>
162+
47163
### Public Suffix List Maintenance
48164

165+
**Directly fetching the Public Suffix List without caching the result is not recommend** . For that reason, the package comes bundle with a `Pdp\Manager` class which retrieves, convert and cache the Public Suffix List for you.
166+
167+
49168
~~~php
50169
<?php
51170

@@ -62,8 +181,6 @@ final class Manager
62181
}
63182
~~~
64183

65-
This class obtains, parses, caches, and returns a PHP representation of the PSL rules.
66-
67184
#### Creating a new manager
68185

69186
To work as intended, the `Manager` constructor requires:
@@ -73,6 +190,8 @@ To work as intended, the `Manager` constructor requires:
73190
- a `HttpClient` interface which exposes the `HttpClient::getContent` method which expects a string URL representation has its sole argument and returns the body from the given URL resource as a string.
74191
If an error occurs while retrieving such body a `HttpClientException` is thrown.
75192

193+
**Of note:** the class also uses internally a `Pdp\Converter` object to convert the fetched PSL into its `array` representation when required.
194+
76195
~~~php
77196
<?php
78197

@@ -221,99 +340,7 @@ $domain->getSubDomain(); //returns 'nl.shop'
221340
$domain->isKnown(); //returns false
222341
~~~
223342

224-
In any case, you should setup a cron to regularly update your local cache.
225-
226-
227-
### Domain Resolution
228-
229-
~~~php
230-
<?php
231-
232-
namespace Pdp;
233-
234-
final class Rules
235-
{
236-
const ALL_DOMAINS = 'ALL_DOMAINS';
237-
const ICANN_DOMAINS = 'ICANN_DOMAINS';
238-
const PRIVATE_DOMAINS = 'PRIVATE_DOMAINS';
239-
240-
public function __construct(array $rules)
241-
public function resolve(string $domain = null, string $type = self::ALL_DOMAINS): Domain
242-
}
243-
~~~
244-
245-
The `Rules` constructor expects a `array` representation of the Public Suffix List. This `array` representation is constructed by the `Manager` and stored using a PSR-16 compliant cache.
246-
247-
The `Rules` class resolves the submitted domain against the parsed rules from the PSL. This is done using the `Rules::resolve` method which returns a `Pdp\Domain` object. The method expects
248-
249-
- a valid domain name as a string
250-
- a string to optionnally specify which section of the PSL you want to validate the given domain against.
251-
By default all sections are used `Rules::ALL_DOMAINS` but you can validate your domain against the ICANN only section (`Rules::ICANN_DOMAINS` or the private section (`Rules::PRIVATE_DOMAINS`) of the PSL.
252-
253-
~~~php
254-
<?php
255-
256-
final class Domain implements JsonSerializable
257-
{
258-
public function getDomain(): ?string
259-
public function getPublicSuffix(): ?string
260-
public function getRegistrableDomain(): ?string
261-
public function getSubDomain(); ?string
262-
public function isKnown(): bool;
263-
public function isICANN(): bool;
264-
public function isPrivate(): bool;
265-
}
266-
~~~
267-
268-
The `Domain` getters method always return normalized value according to the domain status against the PSL rules.
269-
270-
<p class="message-notice"><code>Domain::isKnown</code> status depends on the PSL rules used. For the same domain, depending on the rules used a domain public suffix may be known or not.</p>
271-
272-
~~~php
273-
<?php
274-
275-
use Pdp\Cache;
276-
use Pdp\CurlHttpClient;
277-
use Pdp\Domain;
278-
use Pdp\Manager;
279-
280-
$manager = new Manager(new Cache(), new CurlHttpClient());
281-
$rules = $manager->getRules('https://raw.githubusercontent.com/publicsuffix/list/master/public_suffix_list.dat');
282-
//$rules is a Pdp\Rules object
283-
284-
$domain = $rules->resolve('www.ulb.ac.be');
285-
$domain->getDomain(); //returns 'www.ulb.ac.be'
286-
$domain->getPublicSuffix(); //returns 'ac.be'
287-
$domain->getRegistrableDomain(); //returns 'ulb.ac.be'
288-
$domain->getSubDomain(); //returns 'www'
289-
$domain->isKnown(); //returns true
290-
$domain->isICANN(); //returns true
291-
$domain->isPrivate(); //returns false
292-
echo json_encode($domain, JSON_PRETTY_PRINT);
293-
// returns
294-
// {
295-
// "domain": "www.ulb.ac.be",
296-
// "registrableDomain": "ulb.ac.be",
297-
// "subDomain": "www",
298-
// "publicSuffix": "ac.be",
299-
// "isKnown": true,
300-
// "isICANN": true,
301-
// "isPrivate": false
302-
// }
303-
304-
//let's resolve the same domain against the PRIVATE DOMAIN SECTION
305-
306-
$domain = $rules->resolve('www.ulb.ac.be', Rules::PRIVATE_DOMAINS);
307-
$domain->getDomain(); //returns 'www.ulb.ac.be'
308-
$domain->getPublicSuffix(); //returns 'be'
309-
$domain->getRegistrableDomain(); //returns 'ac.be'
310-
$domain->getSubDomain(); //returns 'www.ulb'
311-
$domain->isKnown(); //returns false
312-
$domain->isICANN(); //returns false
313-
$domain->isPrivate(); //returns false
314-
~~~
315-
316-
<p class="message-warning"><strong>Warning:</strong> 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.</p>
343+
In any case, you should setup a reccurent job to regularly update your local cache.
317344

318345
Contributing
319346
-------

‎src/Domain.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,10 +55,10 @@ final class Domain implements JsonSerializable
5555
* @param string|null $domain
5656
* @param PublicSuffix $publicSuffix
5757
*/
58-
public function __construct($domain = null, PublicSuffix $publicSuffix)
58+
public function __construct($domain = null, PublicSuffix $publicSuffix = null)
5959
{
6060
$this->domain = $domain;
61-
$this->publicSuffix = $publicSuffix;
61+
$this->publicSuffix = $publicSuffix ?? new PublicSuffix();
6262
$this->registrableDomain = $this->setRegistrableDomain();
6363
$this->subDomain = $this->setSubDomain();
6464
}

‎src/Rules.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ public function resolve(string $domain = null, string $type = self::ALL_DOMAINS)
5555
}
5656

5757
if (!$this->isMatchable($domain)) {
58-
return new Domain(null, new PublicSuffix());
58+
return new Domain();
5959
}
6060

6161
$publicSuffix = $this->findPublicSuffix($type, $domain);

0 commit comments

Comments
 (0)