Skip to content

Commit fac367f

Browse files
nyamsprodnyamsprod
committed
Improve Domain::withLabel method
1 parent 79b0500 commit fac367f

File tree

4 files changed

+99
-28
lines changed

4 files changed

+99
-28
lines changed

‎README.md

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

48-
### Domain name parsing.
48+
### Domain
49+
50+
~~~php
51+
<?php
52+
53+
use Pdp\Domain;
54+
55+
$domain = new Domain('www.ExAmple.com');
56+
$domain->getContent(); // www.example.com
57+
echo $domain; // www.example.com
58+
echo $domain->getLabel(0); // 'com'
59+
echo $domain->getLabel(-1); // 'www'
60+
$domain->keys('example'); // array(1)
61+
count($domain); //returns 3
62+
~~~
63+
64+
The `Pdp\Domain` object is an immutable value object representing a valid domain name. This object let's you access the domain properties.
65+
66+
~~~php
67+
public function Domain::__toString(): string
68+
public function Domain::getContent(): ?string
69+
public function Domain::getLabel(int $key): ?string
70+
public function Domain::keys(?string $label): int[]
71+
~~~
72+
73+
*The getter methods return normalized and lowercased domain labels or `null` if no value was found for a particular domain part.*
74+
75+
The `Pdp\Domain` object also implements PHP's `Countable`, `IteratorAggregate` and `JsonSerializable` interfaces to ease retrieving the domain labels and properties.
76+
77+
Once you have a `Pdp\Domain` object you can also modify its content using the following methods:
78+
79+
~~~php
80+
public function Domain::toAscii(): Domain
81+
public function Domain::toUnicode(): Domain
82+
public function Domain::withLabel(int $key, $label): Domain
83+
public function Domain::withoutLabel(int $key, int ...$keys): Domain
84+
~~~
85+
86+
~~~php
87+
<?php
88+
89+
use Pdp\Domain;
90+
91+
$domain = new Domain('www.bébé.be');
92+
$domain->getContent(); // 'www.bébé.be'
93+
echo $domain->toAscii(); // 'www.xn--bb-bjab.be'
94+
echo $domain->toUnicode(); // 'www.bébé.be'
95+
$newDomain = $domain
96+
->withLabel(-1, 'shop')
97+
->withLabel(0, 'com')
98+
->withoutLabel(1)
99+
;
100+
echo $domain; // 'www.bébé.be'
101+
echo $newDomain // 'shop.com'
102+
~~~
103+
104+
Because the `Pdp\Domain` object is immutable:
105+
106+
- If the method change any of the current object property, a new object is returned.
107+
- If a modification is not possible a `Pdp\Exception` exception is thrown.
108+
109+
**WARNING: URI and URL accept registered name which encompass domain name. Therefore, some URI host are invalid domain name and will trigger an exception if you try to instantiate a `Pdp\Domain` with them.**
110+
111+
112+
### Public suffix resolution.
49113

50114
~~~php
51115
<?php
@@ -71,21 +135,23 @@ echo json_encode($domain, JSON_PRETTY_PRINT);
71135
// }
72136
~~~
73137

74-
Using the above code you can parse any valid domain name.
138+
Using the above code you can parse, validate and resolve a domain name and its public suffix status against a Public suffix list.
75139

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.
140+
The `Pdp\Domain` object can tell whether a public suffix can be attached to it using the `Pdp\Domain::isResolvable` method.
77141

78142
~~~php
79-
public function Domain::__toString(): string
80-
public function Domain::getContent(): ?string
81-
public function Domain::getLabel(int $key): ?string
82-
public function Domain::keys(?string $label): int[]
83-
public function Domain::toAscii(): self
84-
public function Domain::toUnicode(): self
85-
public function Domain::isResolvable(): bool;
143+
<?php
144+
145+
use Pdp\Domain;
146+
147+
$domain = new Domain('www.ExAmple.com');
148+
$domain->isResolvable(); //returns true;
149+
150+
$altDomain = new Domain('localhost');
151+
$altDomain->isResolvable(); //returns false;
86152
~~~
87153

88-
as well as its public suffix informations attached to it by the `Pdp\Rules::resolve` method.
154+
Furthermore, the `Pdp\Domain` object let's you access and modify its related public suffix properties using the following methods:
89155

90156
~~~php
91157
public function Domain::getPublicSuffix(): ?string
@@ -94,29 +160,20 @@ public function Domain::getSubDomain(); ?string
94160
public function Domain::isKnown(): bool;
95161
public function Domain::isICANN(): bool;
96162
public function Domain::isPrivate(): bool;
97-
~~~
98-
99-
*The getter methods return normalized and lowercased domain labels or `null` if no value was found for a particular domain part.*
100-
101-
The `Pdp\Domain` object also implements PHP's `Countable`, `IteratorAggregate` and `JsonSerializable` interfaces to ease retrieving the domain labels and properties.
102-
103-
Once you have a `Pdp\Domain` object you can also modify its content using the following methods:
104-
105-
~~~php
106-
public function Domain::withLabel(int $key, $label): self
107-
public function Domain::withoutLabel(int $key, int ...$keys): self
108163
public function Domain::resolve($publicSuffix): self
109164
public function Domain::withPublicSuffix($publicSuffix): self
110165
public function Domain::withSubDomain($subDomain): self
111166
~~~
112167

113-
Because the `Pdp\Domain` object is immutable:
114-
115-
- If the method change any of the current object property, a new object is returned.
116-
- If a modification is not possible a `Pdp\Exception` exception is thrown.
168+
Here's a more complex example:
117169

118170
~~~php
119171
$domain = $rules->resolve('www.bbc.co.uk');
172+
$domain->getContent(); //returns 'www.bbc.co.uk';
173+
$domain->getPublicSuffix(); //returns 'co.uk';
174+
$domain->isKnown(); //return true;
175+
$domain->isICANN(); //return true;
176+
120177
$newDomain = $domain
121178
->withPublicSuffix('com')
122179
->withSubDomain('shop')
@@ -149,7 +206,7 @@ The `Pdp\PublicSuffix` is an immutable value object which exposes the same metho
149206
- all the modifying methods, **`toAscii` and `toUnicode` excluded**.
150207
- `getPublicSuffix`, `getRegistrableDomain`, `getSubDomain`, `isResolvable`
151208

152-
### Public suffix resolution.
209+
### Public suffix resolution rules.
153210

154211
~~~php
155212
<?php

‎data/pdp-PSL_FULL_5a3cc7f81795bb2e48e848af42d287b4.cache

Lines changed: 1 addition & 1 deletion
Large diffs are not rendered by default.

‎src/Domain.php

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -507,6 +507,10 @@ private function normalizeContent($domain)
507507
}
508508

509509
$domain = (string) $domain;
510+
if (null === $this->domain) {
511+
return $domain;
512+
}
513+
510514
if (preg_match(self::REGEXP_IDN_PATTERN, $this->domain)) {
511515
return $this->idnToUnicode($domain);
512516
}

‎tests/DomainTest.php

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -679,6 +679,7 @@ public function testWithPublicSuffixFailsWithNullDomain()
679679

680680
/**
681681
* @covers ::withLabel
682+
* @covers ::normalizeContent
682683
* @dataProvider withLabelWorksProvider
683684
*
684685
* @param Domain $domain
@@ -710,6 +711,15 @@ public function withLabelWorksProvider()
710711
$base_domain = new Domain('www.example.com', new PublicSuffix('com', Rules::ICANN_DOMAINS));
711712

712713
return [
714+
'null domain' => [
715+
'domain' => new Domain(),
716+
'key' => 0,
717+
'label' => 'localhost',
718+
'expected' => 'localhost',
719+
'isKnown' => false,
720+
'isICANN' => false,
721+
'isPrivate' => false,
722+
],
713723
'simple replace positive offset' => [
714724
'domain' => $base_domain,
715725
'key' => 2,

0 commit comments

Comments
 (0)