Skip to content

Commit a98441f

Browse files
nyamsprodnyamsprod
committed
Improve documentation
1 parent 67f49de commit a98441f

File tree

1 file changed

+62
-67
lines changed

1 file changed

+62
-67
lines changed

‎README.md

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

48-
### Domain
48+
### Public suffix resolution.
4949

5050
~~~php
5151
<?php
5252

53-
use Pdp\Domain;
53+
use Pdp\Cache;
54+
use Pdp\CurlHttpClient;
55+
use Pdp\Manager;
5456

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
57+
$manager = new Manager(new Cache(), new CurlHttpClient());
58+
$rules = $manager->getRules(); //$rules is a Pdp\Rules object
59+
60+
$domain = $rules->resolve('www.ulb.ac.be'); //$domain is a Pdp\Domain object
61+
echo $domain->getContent(); // 'www.ulb.ac.be'
62+
echo $domain->getPublicSuffix(); // 'ac.be'
63+
echo $domain->getRegistrableDomain(); // 'ulb.ac.be'
64+
echo $domain->getSubDomain(); // 'www'
65+
$domain->isResolvable(); // returns true
66+
$domain->isKnown(); // returns true
67+
$domain->isICANN(); // returns true
68+
$domain->isPrivate(); // returns false
69+
70+
71+
$altDomain = $rules->getPublicSuffix('thephpleague.github.io'); //$altDomain is a Pdp\PublicSuffix object
72+
echo $altDomain->getContent(); // 'github.io'
73+
$altDomain->isKnown(); // returns true
74+
$altDomain->isICANN(); // returns false
75+
$altDomain->isPrivate(); // returns true
6276
~~~
6377

64-
The `Pdp\Domain` object is an immutable value object representing a valid domain name. This object let's you access the domain properties.
78+
Using the above code you have parse, validate and resolve a domain name and its public suffix status against the Public Suffix list.
79+
80+
Documentation
81+
--------
82+
83+
### Domain objects
6584

6685
~~~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[]
86+
<?php
87+
88+
use Pdp\Domain;
89+
use Pdp\PublicSuffix;
90+
91+
$publicSuffix = new PublicSuffix('com');
92+
$domain = new Domain('www.bébé.ExAmple.com', $publicSuffix);
93+
$domain->getContent(); // www.bébé.example.com
94+
echo $domain; // www.bébé.example.com
95+
echo $domain->getLabel(0); // 'com'
96+
echo $domain->getLabel(-1); // 'www'
97+
$domain->keys('example'); // array(1)
98+
count($domain); //returns 4
99+
$domain->getPublicSuffix(); // 'com'
100+
$domain->getRegistrableDomain(); // 'example.com'
101+
$domain->getSubDomain(); // 'www.bébé'
102+
$domain->isKnown(); // returns false
103+
$domain->isICANN(); // returns false
104+
$domain->isPrivate(); // returns false
105+
iterator_to_array($domain, false); // ['com', 'example', 'bébé', 'www']
106+
$domain->toAscii()->getContent(); // www.xn--bb-bjab.example.com
107+
echo (new Domain('www.xn--bb-bjab.example.com'))->toAscii() // www.bébé.example.com
71108
~~~
72109

110+
The `Pdp\Domain` and `Pdp\PublicSuffix` objects are an immutable value object representing a valid domain name. These objects let's you access the domain properties.
111+
73112
*The getter methods return normalized and lowercased domain labels or `null` if no value was found for a particular domain part.*
74113

75-
The `Pdp\Domain` object also implements PHP's `Countable`, `IteratorAggregate` and `JsonSerializable` interfaces to ease retrieving the domain labels and properties.
114+
Theses objects also implements PHP's `Countable`, `IteratorAggregate` and `JsonSerializable` interfaces to ease retrieving the domain labels and properties.
76115

77-
Once you have a `Pdp\Domain` object you can also modify its content using the following methods:
116+
Modify the domain content is only possible for the `Pdp\Domain` object using the following methods:
78117

79118
~~~php
80-
public function Domain::toAscii(): Domain
81-
public function Domain::toUnicode(): Domain
119+
public function Domain::isResolvable();
82120
public function Domain::withLabel(int $key, $label): Domain
83121
public function Domain::withoutLabel(int $key, int ...$keys): Domain
122+
public function Domain::append($label): Domain
123+
public function Domain::prepend($label): Domain
124+
public function Domain::withPublicSuffix($publicSuffix): Domain
125+
public function Domain::withSubDomain($subDomain): Domain
84126
~~~
85127

86128
~~~php
@@ -109,34 +151,6 @@ Because the `Pdp\Domain` object is immutable:
109151
**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.**
110152

111153

112-
### Public suffix resolution.
113-
114-
~~~php
115-
<?php
116-
117-
use Pdp\Cache;
118-
use Pdp\CurlHttpClient;
119-
use Pdp\Manager;
120-
121-
$manager = new Manager(new Cache(), new CurlHttpClient());
122-
$rules = $manager->getRules(); //$rules is a Pdp\Rules object
123-
124-
$domain = $rules->resolve('www.ulb.ac.be'); //$domain is a Pdp\Domain object
125-
echo json_encode($domain, JSON_PRETTY_PRINT);
126-
// returns
127-
// {
128-
// "domain": "www.ulb.ac.be",
129-
// "registrableDomain": "ulb.ac.be",
130-
// "subDomain": "www",
131-
// "publicSuffix": "ac.be",
132-
// "isKnown": true,
133-
// "isICANN": true,
134-
// "isPrivate": false
135-
// }
136-
~~~
137-
138-
Using the above code you can parse, validate and resolve a domain name and its public suffix status against a Public suffix list.
139-
140154
The `Pdp\Domain` object can tell whether a public suffix can be attached to it using the `Pdp\Domain::isResolvable` method.
141155

142156
~~~php
@@ -151,20 +165,6 @@ $altDomain = new Domain('localhost');
151165
$altDomain->isResolvable(); //returns false;
152166
~~~
153167

154-
Furthermore, the `Pdp\Domain` object let's you access and modify its related public suffix properties using the following methods:
155-
156-
~~~php
157-
public function Domain::getPublicSuffix(): ?string
158-
public function Domain::getRegistrableDomain(): ?string
159-
public function Domain::getSubDomain(); ?string
160-
public function Domain::isKnown(): bool;
161-
public function Domain::isICANN(): bool;
162-
public function Domain::isPrivate(): bool;
163-
public function Domain::resolve($publicSuffix): Domain
164-
public function Domain::withPublicSuffix($publicSuffix): Domain
165-
public function Domain::withSubDomain($subDomain): Domain
166-
~~~
167-
168168
Here's a more complex example:
169169

170170
~~~php
@@ -201,12 +201,7 @@ $newDomain->getPublicSuffix(); //returns 'com';
201201
$newDomain->isKnown(); //return true;
202202
~~~
203203

204-
The `Pdp\PublicSuffix` is an immutable value object which exposes the same methods as the `Pdp\Domain` object minus
205-
206-
- all the modifying methods, **`toAscii` and `toUnicode` excluded**.
207-
- `getPublicSuffix`, `getRegistrableDomain`, `getSubDomain`, `isResolvable`
208-
209-
### Public suffix resolution rules.
204+
### Pdp\Rules object.
210205

211206
~~~php
212207
<?php
@@ -286,7 +281,7 @@ echo json_encode($domain, JSON_PRETTY_PRINT);
286281

287282
**Using the PSL to determine what is a valid domain name and what isn't is 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.**
288283

289-
### Public Suffix List Maintenance
284+
### Managing the Public Suffix List
290285

291286
The library comes bundle with a service which enables resolving domain name without the constant network overhead of continously downloading the PSL. The `Pdp\Manager` class retrieves, converts and caches the PSL as well as creates the corresponding `Pdp\Rules` object on demand. It internally uses a `Pdp\Converter` object to convert the fetched PSL into its `array` representation when required.
292287

0 commit comments

Comments
 (0)