Skip to content

Commit 7e2855d

Browse files
nyamsprodnyamsprod
committed
Improve Library Exceptions
1 parent 139f0d0 commit 7e2855d

13 files changed

+280
-202
lines changed

‎README.md

Lines changed: 40 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ $ composer require jeremykendall/php-domain-parser
4545
Usage
4646
--------
4747

48-
### Parsing a domain name.
48+
### Domain name parsing.
4949

5050
~~~php
5151
<?php
@@ -57,7 +57,7 @@ use Pdp\Manager;
5757
$manager = new Manager(new Cache(), new CurlHttpClient());
5858
$rules = $manager->getRules(); //$rules is a Pdp\Rules object
5959

60-
$domain = $rules->resolve('www.ulb.ac.be');
60+
$domain = $rules->resolve('www.ulb.ac.be'); //$domain is a Pdp\Domain object
6161
echo json_encode($domain, JSON_PRETTY_PRINT);
6262
// returns
6363
// {
@@ -69,52 +69,45 @@ echo json_encode($domain, JSON_PRETTY_PRINT);
6969
// "isICANN": true,
7070
// "isPrivate": false
7171
// }
72-
73-
$publicSuffix = $rules->getPublicSuffix('www.ulb.ac.be');
74-
echo json_encode($publicSuffix, JSON_PRETTY_PRINT);
75-
// returns
76-
// {
77-
// "publicSuffix": "ac.be",
78-
// "isKnown": true,
79-
// "isICANN": true,
80-
// "isPrivate": false
81-
// }
8272
~~~
8373

84-
Using the above code you can parse and get public suffix informations about any valid domain name.
74+
Using the above code you can parse any valid domain name.
8575

86-
### Manipulating the domain name
87-
88-
The `Pdp\Domain` returned by the `Pdp\Rules::resolve` method is an immutable value object representing a valid domain name. This object let's you access all the domain name properties as well as the public suffix informations attached to it using the following methods.
76+
The returned `Pdp\Domain` object is an immutable value object representing a valid domain name. This object let's you access the domain properties.
8977

9078
~~~php
9179
public function Domain::__toString(): string
9280
public function Domain::getContent(): ?string
93-
public function Domain::getPublicSuffix(): ?string
94-
public function Domain::getRegistrableDomain(): ?string
95-
public function Domain::getSubDomain(); ?string
9681
public function Domain::getLabel(int $key): ?string
9782
public function Domain::keys(?string $label): int[]
83+
public function Domain::toAscii(): self
84+
public function Domain::toUnicode(): self
9885
public function Domain::isResolvable(): bool;
86+
~~~
87+
88+
as well as its public suffix informations attached to it by the `Pdp\Rules::resolve` method.
89+
90+
~~~php
91+
public function Domain::getPublicSuffix(): ?string
92+
public function Domain::getRegistrableDomain(): ?string
93+
public function Domain::getSubDomain(); ?string
9994
public function Domain::isKnown(): bool;
10095
public function Domain::isICANN(): bool;
10196
public function Domain::isPrivate(): bool;
10297
~~~
10398

104-
*The getter methods returns normalized and lowercased domain labels or `null` if no value was found for a particular domain part.*
99+
*The getter methods return normalized and lowercased domain labels or `null` if no value was found for a particular domain part.*
105100

106-
The `Pdp\Domain` object also implements PHP's `Countable` and `IteratorAggregate` interfaces to ease counting and iterating over the domain labels as well as PHP's `JsonSerializable` interfaces to output a JSON array with all the useful informations regarding the domain name.
101+
The `Pdp\Domain` object also implements PHP's `Countable`, `IteratorAggregate` and `JsonSerializable` interfaces to ease retrieving the object properties.
107102

108-
Once you have a `Pdp\Domain` object can also modify its content using the following methods:
103+
Once you have a `Pdp\Domain` object you can also modify its content using the following methods:
109104

110105
~~~php
111-
public function Domain::toAscii(): self
112-
public function Domain::toUnicode(): self
113-
public function Domain::withPublicSuffix($publicSuffix): self
114-
public function Domain::withSubDomain($subDomain): self
115106
public function Domain::withLabel(int $key, $label): self
116107
public function Domain::withoutLabel(int $key, int ...$keys): self
117108
public function Domain::resolve($publicSuffix): self
109+
public function Domain::withPublicSuffix($publicSuffix): self
110+
public function Domain::withSubDomain($subDomain): self
118111
~~~
119112

120113
Because the `Pdp\Domain` object is immutable:
@@ -123,37 +116,40 @@ Because the `Pdp\Domain` object is immutable:
123116
- If a modification is not possible a `Pdp\Exception` exception is thrown.
124117

125118
~~~php
126-
$manager = new Manager(new Cache(), new CurlHttpClient());
127-
$rules = $manager->getRules();
128119
$domain = $rules->resolve('www.bbc.co.uk');
129120
$newDomain = $domain
130121
->withPublicSuffix('com')
131122
->withSubDomain('shop')
132123
->withLabel(-2, 'example')
133124
;
134-
$newDomain->getContent(); //returns shop.example.com;
135-
$newDomain->isKnown(); //return false;
125+
$newDomain->getContent(); //returns 'shop.example.com';
126+
$newDomain->getPublicSuffix(); //returns 'com';
127+
$newDomain->isKnown(); //return false;
136128
~~~
137129

138-
**WARNING: in the example above the PSL info are lost because the newly attached public suffix had none.**
130+
**WARNING: in the example above the public suffix informations are lost because the newly attached public suffix had none.**
139131

140132
To avoid this data loss you should use an already resolved public suffix.
141133

142134
~~~php
143-
$manager = new Manager(new Cache(), new CurlHttpClient());
144-
$rules = $manager->getRules();
145135
$domain = $rules->resolve('www.bbc.co.uk');
146-
$newPublicSuffix = $rules->getPublicSuffix('example.com');
136+
$newPublicSuffix = $rules->getPublicSuffix('example.com'); //$newPublicSuffix is a Pdp\PublicSuffix object
147137
$newDomain = $domain
148138
->withPublicSuffix($newPublicSuffix)
149139
->withSubDomain('shop')
150140
->withLabel(-2, 'example')
151141
;
152-
$newDomain->getContent(); //returns shop.example.com;
153-
$newDomain->isKnown(); //return true;
142+
$newDomain->getContent(); //returns 'shop.example.com';
143+
$newDomain->getPublicSuffix(); //returns 'com';
144+
$newDomain->isKnown(); //return true;
154145
~~~
155146

156-
### Getting the domain public suffix information.
147+
The `Pdp\PublicSuffix` is an immutable value object which exposes the same methods as the `Pdp\Domain` object minus
148+
149+
- all the modifying methods, **`toAscii` and `toUnicode` excluded**.
150+
- `getPublicSuffix`, `getRegistrableDomain`, `getSubDomain`, `isResolvable`
151+
152+
### Public suffix information resolution.
157153

158154
~~~php
159155
<?php
@@ -185,15 +181,12 @@ Both methods expect the same arguments:
185181

186182
By default, the `$section` argument is equal to the empty string. If an unsupported section is submitted a `Pdp\Exception` exception will be thrown.
187183

188-
The `Pdp\PublicSuffix` object exposes the same methods as the `Pdp\Domain` object minus all the modifying methods, `toAscii` and `toUnicode` excluded.
189-
190184
**THIS EXAMPLE ILLUSTRATES HOW THE OBJECT WORK BUT SHOULD BE AVOIDED IN PRODUCTON**
191185

192186
~~~php
193187
<?php
194188

195189
use Pdp\Rules;
196-
use Pdp\Converter;
197190

198191
$pdp_url = 'https://raw.githubusercontent.com/publicsuffix/list/master/public_suffix_list.dat';
199192
$rules = Rules::createFromPath($pdp_url);
@@ -212,9 +205,9 @@ echo json_encode($domain, JSON_PRETTY_PRINT);
212205
// "isPrivate": false
213206
// }
214207

215-
//The same domain will yield a different result using the PSL ICANN DOMAIN SECTION only
208+
//The same domain will return a different result using the PSL PRIVATE DOMAIN SECTION only
216209

217-
$domain = $rules->resolve('www.Ulb.AC.be', Rules::ICANN_DOMAINS);
210+
$domain = $rules->resolve('www.Ulb.AC.be', Rules::PRIVATE_DOMAINS);
218211
echo json_encode($domain, JSON_PRETTY_PRINT);
219212
// returns
220213
// {
@@ -352,17 +345,7 @@ use Pdp\Manager;
352345
$manager = new Manager(new Cache(), new CurlHttpClient());
353346
$rules = $manager->getRules('https://raw.githubusercontent.com/publicsuffix/list/master/public_suffix_list.dat');
354347
$domain = $rules->resolve('www.ulb.ac.be');
355-
echo json_encode($domain, JSON_PRETTY_PRINT);
356-
// returns
357-
// {
358-
// "domain": "www.ulb.ac.be",
359-
// "registrableDomain": "ulb.ac.be",
360-
// "subDomain": "www",
361-
// "publicSuffix": "ac.be",
362-
// "isKnown": true,
363-
// "isICANN": true,
364-
// "isPrivate": false
365-
// }
348+
echo $domain->getPublicSuffix(); // print 'ac.be'
366349
~~~
367350

368351
### Automatic Updates
@@ -435,9 +418,10 @@ final class GuzzleHttpClientAdapter implements HttpClient
435418
}
436419

437420
$dbh = new PDO('mysql:dbname=testdb;host=127.0.0.1', 'dbuser', 'dbpass');
438-
$symfonyCache = new PDOCache($dbh, 'psl', 86400);
439-
$guzzleAdapter = new GuzzleHttpClientAdapter(new GuzzleClient());
440-
$manager = new Manager($symfonyCache, $guzzleAdapter);
421+
$manager = new Manager(
422+
new PDOCache($dbh, 'psl', 86400),
423+
new GuzzleHttpClientAdapter(new GuzzleClient())
424+
);
441425
$manager->refreshRules();
442426
//the rules are saved to the database for 1 day
443427
//the rules are fetched using GuzzlClient

‎src/Converter.php

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,25 @@ final class Converter implements PublicSuffixListSection
2929
{
3030
use IDNAConverterTrait;
3131

32+
/**
33+
* @internal
34+
*/
35+
const PSL_SECTION = [
36+
'ICANN' => [
37+
'BEGIN' => self::ICANN_DOMAINS,
38+
'END' => '',
39+
],
40+
'PRIVATE' => [
41+
'BEGIN' => self::PRIVATE_DOMAINS,
42+
'END' => '',
43+
],
44+
];
45+
46+
/**
47+
* @internal
48+
*/
49+
const REGEX_PSL_SECTION = ',^// ===(?<point>BEGIN|END) (?<type>ICANN|PRIVATE) DOMAINS===,';
50+
3251
/**
3352
* Convert the Public Suffix List into
3453
* an associative, multidimensional array.
@@ -64,13 +83,8 @@ public function convert(string $content): array
6483
*/
6584
private function getSection(string $section, string $line): string
6685
{
67-
static $section_list = [
68-
'ICANN' => ['BEGIN' => self::ICANN_DOMAINS, 'END' => ''],
69-
'PRIVATE' => ['BEGIN' => self::PRIVATE_DOMAINS, 'END' => ''],
70-
];
71-
static $pattern = ',^// ===(?<point>BEGIN|END) (?<type>ICANN|PRIVATE) DOMAINS===,';
72-
if (preg_match($pattern, $line, $matches)) {
73-
return $section_list[$matches['type']][$matches['point']];
86+
if (preg_match(self::REGEX_PSL_SECTION, $line, $matches)) {
87+
return self::PSL_SECTION[$matches['type']][$matches['point']];
7488
}
7589

7690
return $section;

0 commit comments

Comments
 (0)