Skip to content

Commit b8ce97a

Browse files
nyamsprodnyamsprod
committed
Improving the package documentation
1 parent 9e91376 commit b8ce97a

File tree

4 files changed

+103
-25
lines changed

4 files changed

+103
-25
lines changed

‎CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@ All Notable changes to `PHP Domain Parser` **5.x** series will be documented in
99
- `Rules::resolveCookieDomain`
1010
- `Rules::resolveICANNDomain`
1111
- `Rules::resolvePrivateDomain`
12+
- `Rules::getCookieEffectiveTLD`
13+
- `Rules::getICANNEffectiveTLD`
14+
- `Rules::getPrivateeEffectiveTLD`
1215
- `CouldNotResolvePublicSuffix::dueToUnresolvableDomain`
1316

1417
### Fixed
@@ -23,6 +26,7 @@ All Notable changes to `PHP Domain Parser` **5.x** series will be documented in
2326
### Removed
2427

2528
- Support for PHP7.0 and PHP7.1
29+
- The external data from IANA and mozilla is no longer part of the package and will be downloaded only on demand on composer update/install.
2630

2731
## 5.6.0 - 2019-12-29
2832

‎README.md

Lines changed: 92 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -46,18 +46,92 @@ $ composer require jeremykendall/php-domain-parser
4646
Usage
4747
--------
4848

49+
### Public suffix resolution.
50+
51+
The first objective of the library is using the [Public Suffix List](http://publicsuffix.org/) to easily return the ICANN, the Cookie or
52+
the Private Effective TLD as a `Pdp\PublicSuffix` object using the following methods:
53+
54+
~~~php
55+
use Pdp\Rules;
56+
57+
$rules = Rules::createFromPath('/path/to/mozilla/public-suffix.dat');
58+
59+
echo $rules->getICANNEffectiveTLD('www.ulb.ac.be'); //display 'ac.be';
60+
echo $rules->getCookieEffectiveTLD('www.ulb.ac.be'); //display 'ac.be';
61+
echo $rules->getPrivateEffectiveTLD('www.ulb.ac.be'); //display 'be';
62+
~~~
63+
64+
The methods are available since version `5.7.0` to ease the package usage. Prior to this version you could use the
65+
`Rules::getPublicSuffix` method with an optional `$section` argument to get the same results:
66+
67+
~~~php
68+
use Pdp\Rules;
69+
70+
$rules = Rules::createFromPath('/path/to/mozilla/public-suffix.dat');
71+
72+
echo $rules->getPublicSuffix('www.ulb.ac.be'); // get the cookie effective TLD, display 'ac.be';
73+
echo $rules->getPublicSuffix('www.ulb.ac.be', Rules::ICANN_DOMAINS); //get the ICANN effective TLD, display 'ac.be';
74+
echo $rules->getPublicSuffix('www.ulb.ac.be', Rules::PRIVATE_DOMAINS); //get the Private effective TLD, display 'be';
75+
~~~
76+
77+
78+
If the Public Suffix is not found or in case of error an exception which extends `Pdp\Exception` is thrown.
79+
80+
### Domain resolution.
81+
82+
Apart the Public Suffix the package can resolve domain and their information also using Mozilla's [Public Suffix List](http://publicsuffix.org/)
83+
84+
~~~php
85+
use Pdp\Rules;
86+
87+
$rules = Rules::createFromPath('/path/to/mozilla/public-suffix.dat');
88+
89+
echo $rules->resolveCookieDomain('www.ulb.ac.be'); // returns a Pdp\Domain object whose Public Suffix is 'ac.be';
90+
echo $rules->resolveICANNDomain('www.ulb.ac.be'); // returns a Pdp\Domain object whose Public Suffix is 'ac.be';
91+
echo $rules->resolvePrivateDomain('www.ulb.ac.be'); // returns a Pdp\Domain object whose Public Suffix is 'be';
92+
~~~
93+
94+
The methods are available since version `5.7.0` to ease the package usage. Prior to this version you could use the
95+
`Rules::resolve` method with an optional `$section` argument to get the same results:
96+
97+
~~~php
98+
use Pdp\Rules;
99+
100+
$rules = Rules::createFromPath('/path/to/mozilla/public-suffix.dat');
101+
102+
echo $rules->resolve('www.ulb.ac.be'); // returns a Pdp\Domain object whose Public Suffix is 'ac.be';
103+
echo $rules->resolve('www.ulb.ac.be', Rules::ICANN_DOMAINS); // returns a Pdp\Domain object whose Public Suffix is 'ac.be';
104+
echo $rules->resolve('www.ulb.ac.be', Rules::PRIVATE_DOMAINS); // returns a Pdp\Domain object whose Public Suffix is 'be';
105+
~~~
106+
107+
If the Domain is not resolved or in case of error a null `Pdp\Domain` is returned.
108+
109+
### Top Level Domains resolution
110+
111+
While the [Public Suffix List](http://publicsuffix.org/) is a community based list. We can parse the Top Level domain
112+
information given by the [IANA website](https://data.iana.org/TLD/tlds-alpha-by-domain.txt) to always resolve
113+
top domain against the newly registered TLD.
114+
115+
~~~php
116+
use Pdp\TopLevelDomains;
117+
118+
$rules = TopLevelDomains::createFromPath('/path/to/iana/tlds-alpha-by-domain.txt');
119+
120+
echo $rules->resolve('www.UlB.Ac.bE'); //display 'be';
121+
~~~
122+
123+
If the Domain is not resolved or in case of error a null `Pdp\Domain` is returned.
124+
125+
### The Domain and Public Suffix objects.
126+
49127
~~~php
50128
<?php
51129

52-
use Pdp\Cache;
53-
use Pdp\CurlHttpClient;
54-
use Pdp\Manager;
55130
use Pdp\Rules;
56131

57-
$manager = new Manager(new Cache(), new CurlHttpClient());
58-
$rules = $manager->getRules(); //$rules is a Pdp\Rules object
132+
$rules = Rules::createFromPath('/path/to/mozilla/public-suffix.dat'); //$rules is a Pdp\Rules object
59133

60-
$domain = $rules->resolve('www.ulb.ac.be'); //$domain is a Pdp\Domain object
134+
$domain = $rules->resolveICANNDomain('www.ulb.ac.be'); //$domain is a Pdp\Domain object
61135
echo $domain->getContent(); // 'www.ulb.ac.be'
62136
echo $domain->getPublicSuffix(); // 'ac.be'
63137
echo $domain->getRegistrableDomain(); // 'ulb.ac.be'
@@ -67,14 +141,15 @@ $domain->isKnown(); // returns true
67141
$domain->isICANN(); // returns true
68142
$domain->isPrivate(); // returns false
69143
$domain->labels(); // returns ['be', 'ac', 'ulb', 'www']
70-
$publicSuffix = $rules->getPublicSuffix('mydomain.github.io', Rules::PRIVATE_DOMAINS); //$publicSuffix is a Pdp\PublicSuffix object
144+
145+
$publicSuffix = $rules->getPrivateEffectiveTLD('mydomain.github.io'); //$publicSuffix is a Pdp\PublicSuffix object
71146
echo $publicSuffix->getContent(); // 'github.io'
72147
$publicSuffix->isKnown(); // returns true
73148
$publicSuffix->isICANN(); // returns false
74149
$publicSuffix->isPrivate(); // returns true
75150
$publicSuffix->labels(); // returns ['io', 'github']
76151

77-
$altSuffix = $rules->getPublicSuffix('mydomain.github.io', Rules::ICANN_DOMAINS);
152+
$altSuffix = $rules->getICANNEffectiveTLD('mydomain.github.io');
78153
echo $altSuffix->getContent(); // 'io'
79154
$altSuffix->isKnown(); // returns true
80155
$altSuffix->isICANN(); // returns true
@@ -84,7 +159,7 @@ $tldList = $manager->getTLDs(); //$tldList is a Pdp\TopLevelDomains object
84159
$domain = $tldList->resolve('www.ulb.ac.be'); //$domain is a Pdp\Domain object
85160
$tldList->contains('be'); //returns true
86161
$tldList->contains('localhost'); //return false
87-
foreach($tldList as $tld) {
162+
foreach ($tldList as $tld) {
88163
//$tld is a Pdp\PublisSuffix object
89164
}
90165
~~~
@@ -96,8 +171,7 @@ Using the above code you have parse, validate and resolve a domain name and its
96171
**Before**
97172

98173
~~~php
99-
$manager = new Manager(new Cache(), new CurlHttpClient());
100-
$rules = $manager->getRules();
174+
$rules = Rules::createFromPath('/path/to/mozilla/public-suffix.dat'); //$rules is a Pdp\Rules object
101175

102176
$domain = $rules->resolve('faß.test.de');
103177
echo $domain->toAscii()->getContent(); // 'fass.test.de'
@@ -106,19 +180,12 @@ echo $domain->toAscii()->getContent(); // 'fass.test.de'
106180
**After**
107181

108182
~~~php
109-
$manager = new Manager(new Cache(), new CurlHttpClient());
110-
$rules = $manager->getRules()
111-
->withAsciiIDNAOption(IDNA_NONTRANSITIONAL_TO_ASCII)
112-
->withUnicodeIDNAOption(IDNA_NONTRANSITIONAL_TO_UNICODE);
113-
114-
// or
115-
//
116-
// $rules = $manager->getRules(
117-
// Manager::PSL_URL,
118-
// null,
119-
// IDNA_NONTRANSITIONAL_TO_ASCII,
120-
// IDNA_NONTRANSITIONAL_TO_UNICODE
121-
// );
183+
$rules = Rules::createFromPath(
184+
'/path/to/mozilla/public-suffix.dat',
185+
null, // PHP resource context (see fopen context argument)
186+
IDNA_NONTRANSITIONAL_TO_ASCII,
187+
IDNA_NONTRANSITIONAL_TO_UNICODE
188+
); //$rules is a Pdp\Rules object
122189

123190
$domain = $rules->resolve('faß.test.de');
124191
echo $domain->toAscii()->getContent(); // 'xn--fa-hia.test.de'
@@ -514,7 +581,7 @@ public Manager::getTLDs(
514581
): TopLevelDomains
515582
~~~
516583

517-
These methods returns a `Pdp\Rules` or `Pdp\TopLevelDomains` objects seeded with their corresponding data fetch from the cache or from the external resources depending on the submitted `$ttl` argument.
584+
These methods return a `Pdp\Rules` or `Pdp\TopLevelDomains` objects seeded with their corresponding data fetch from the cache or from the external resources depending on the submitted `$ttl` argument.
518585

519586
These methods take an optional `$url` argument which specifies the PSL source URL. If no local cache exists for the submitted source URL, the method will:
520587

‎src/TopLevelDomains.php

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,9 @@ final class TopLevelDomains implements Countable, IteratorAggregate
6262

6363
/**
6464
* New instance.
65+
*
66+
* @internal
67+
*
6568
* @param array $records
6669
* @param string $version
6770
* @param DateTimeInterface $modifiedDate

‎tests/RulesTest.php

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -714,6 +714,10 @@ public function testResolveWithIDNAOptions(): void
714714
* @covers ::getICANNEffectiveTLD
715715
* @covers ::getPrivateEffectiveTLD
716716
* @dataProvider effectiveTLDProvider
717+
* @param string $host
718+
* @param string $cookieETLD
719+
* @param string $icannETLD
720+
* @param string $privateETLD
717721
*/
718722
public function testEffectiveTLDResolution(string $host, string $cookieETLD, string $icannETLD, string $privateETLD): void
719723
{

0 commit comments

Comments
 (0)