Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit aa1f9bf

Browse files
authoredNov 10, 2024··
Prepare PHP8.4 compatible release (#359)
Add support for PHP8.3+ and clean up documentation
1 parent 34c7177 commit aa1f9bf

17 files changed

+208
-112
lines changed
 

‎.github/workflows/build.yaml

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,13 @@ jobs:
1010
runs-on: ubuntu-20.04
1111
strategy:
1212
matrix:
13-
php: ['8.1', '8.2']
13+
php: ['8.1', '8.2', '8.3']
1414
stability: [prefer-lowest, prefer-stable]
15+
include:
16+
- php: '8.4'
17+
flags: "--ignore-platform-req=php"
18+
phpunit-flags: '--no-coverage'
19+
stability: prefer-stable
1520
steps:
1621
- name: Checkout code
1722
uses: actions/checkout@v3
@@ -45,11 +50,16 @@ jobs:
4550

4651
- name: Run Unit tests with coverage
4752
run: composer phpunit -- ${{ matrix.phpunit-flags }}
53+
if: ${{ matrix.php == '8.3' || matrix.php == '8.2' || matrix.php == '8.1'}}
54+
55+
- name: Run Unit tests without coverage
56+
run: composer phpunit:min
57+
if: ${{ matrix.php == '8.4'}}
4858

4959
- name: Run static analysis
5060
run: composer phpstan
51-
if: ${{ matrix.php == '8.2' && matrix.stability == 'prefer-stable'}}
61+
if: ${{ matrix.php == '8.3' && matrix.stability == 'prefer-stable'}}
5262

5363
- name: Run Coding style rules
5464
run: composer phpcs:fix
55-
if: ${{ matrix.php == '8.1' && matrix.stability == 'prefer-stable'}}
65+
if: ${{ matrix.php == '8.3' && matrix.stability == 'prefer-stable'}}

‎.php-cs-fixer.php

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
'import_functions' => true,
1818
],
1919
'list_syntax' => ['syntax' => 'short'],
20-
'new_with_braces' => true,
20+
'new_with_parentheses' => true,
2121
'no_blank_lines_after_phpdoc' => true,
2222
'no_empty_phpdoc' => true,
2323
'no_empty_comment' => true,
@@ -29,6 +29,7 @@
2929
],
3030
'no_trailing_comma_in_singleline' => true,
3131
'no_unused_imports' => true,
32+
'nullable_type_declaration_for_default_null_value' => true,
3233
'ordered_imports' => ['imports_order' => ['class', 'function', 'const'], 'sort_algorithm' => 'alpha'],
3334
'phpdoc_add_missing_param_annotation' => ['only_untyped' => true],
3435
'phpdoc_align' => true,
@@ -39,7 +40,7 @@
3940
'phpdoc_summary' => true,
4041
'psr_autoloading' => true,
4142
'return_type_declaration' => ['space_before' => 'none'],
42-
'single_blank_line_before_namespace' => true,
43+
'blank_lines_before_namespace' => true,
4344
'single_quote' => true,
4445
'space_after_semicolon' => true,
4546
'ternary_operator_spaces' => true,

‎README.md

Lines changed: 37 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,12 @@ You need:
3838

3939
- **PHP >= 7.4** but the latest stable version of PHP is recommended
4040
- the `intl` extension
41+
- a copy of the [Public Suffix List](https://publicsuffix.org/) data and/or a copy of the [IANA Top Level Domain List](https://www.iana.org/domains/root/files). Please refer to the [Managing external data source section](#managing-the-package-external-resources) for more information when using this package in production.
4142

4243
## Usage
4344

44-
**If you are upgrading from version 5 please check the [upgrading guide](UPGRADING.md) for known issues.**
45+
> [!WARNING]
46+
> If you are upgrading from version 5 please check the [upgrading guide](UPGRADING.md) for known issues.
4547
4648
### Resolving Domains
4749

@@ -115,9 +117,10 @@ These methods resolve the domain against their respective data source using
115117
the same rules as the `resolve` method but will instead throw an exception
116118
if no valid effective TLD is found or if the submitted domain is invalid.
117119

118-
**All these methods expect as their sole argument a `Pdp\Host` implementing
120+
> [!CAUTION]
121+
> All these methods expect as their sole argument a `Pdp\Host` implementing
119122
object, but other types (ie: `string`, `null` and stringable objects) are
120-
supported with predefined conditions as explained in the remaining document.**
123+
supported with predefined conditions as explained in the remaining document.
121124

122125
~~~php
123126
<?php
@@ -157,23 +160,18 @@ To instantiate each domain resolver you can use the following named constructor:
157160

158161
**If the instantiation does not work an exception will be thrown.**
159162

160-
**WARNING:**
161-
162-
**You should never resolve domain name this way in production, without, at
163-
least, a caching mechanism to reduce PSL downloads.**
164-
165-
**Using the Public Suffix List to determine what is a valid domain name and what
166-
isn't is dangerous, particularly in these days when new gTLDs are arriving at a
167-
rapid pace.**
168-
169-
**If you are looking to know the validity of a Top Level Domain, the
170-
IANA Top Level Domain List is the proper source for this information or
171-
alternatively consider using directly the DNS.**
172-
173-
**If you must use this library for any of the above purposes, please consider
174-
integrating an updating mechanism into your software.**
175-
176-
**For more information go to the [Managing external data source section](#managing-the-package-external-resources)**
163+
> [!WARNING]
164+
> You SHOULD never resolve domain name this way in production, without, at
165+
least, a caching mechanism to reduce external resource downloads.
166+
> Using the Public Suffix List to determine what is a valid domain name and what
167+
isn't is dangerous, and MAY lead to errors because of new gTLDs being registered
168+
on a regular basis.
169+
> If you are looking to know the validity of a Top Level Domain, you MUST use
170+
the IANA Top Level Domain List as the proper source for this information or
171+
alternatively the DNS.
172+
> If you MUST use this library for any of the above purposes, you SHOULD consider
173+
integrating an updating mechanism into your software.
174+
> For more information go to the [Managing external data source section](#managing-the-package-external-resources)**
177175
178176
### Resolved domain information.
179177

@@ -220,10 +218,11 @@ echo $altResult->domain()->toString(); //display 'foo.bar.test.example';
220218
$altResult->suffix()->isKnown(); //return false;
221219
~~~
222220

223-
**TIP: Always favor submitting a `Pdp\Suffix` object rather that any other
221+
> [!TIP]
222+
> Always favor submitting a `Pdp\Suffix` object rather that any other
224223
supported type to avoid unexpected results. By default, if the input is not a
225224
`Pdp\Suffix` instance, the resulting public suffix will be labelled as
226-
being unknown. For more information go to the [Public Suffix section](#public-suffix)**
225+
being unknown. For more information go to the [Public Suffix section](#public-suffix)
227226

228227
### Domain Suffix
229228

@@ -339,7 +338,8 @@ $newDomain->clear()->labels(); //return []
339338
echo $domain->slice(2)->toString(); //display 'www'
340339
~~~
341340

342-
**WARNING: Because of its definition, a domain name can be `null` or a string.**
341+
> [!WARNING]
342+
> Because of its definition, a domain name can be `null` or a string.
343343
344344
To distinguish this possibility the object exposes two (2) formatting methods
345345
`Domain::value` which can be `null` or a `string` and `Domain::toString` which
@@ -396,8 +396,9 @@ is done via two (2) named constructors:
396396
At any given moment the `Pdp\Domain` instance can tell you whether it is in
397397
`ASCII` mode or not.
398398

399-
**Once instantiated there's no way to tell which algorithm is used to convert
400-
the object from ascii to unicode and vice-versa**
399+
> [!WARNING]
400+
> Once instantiated there's no way to tell which algorithm is used to convert
401+
the object from ascii to unicode and vice-versa
401402

402403
~~~php
403404
use Pdp\Domain;
@@ -419,10 +420,11 @@ echo $asciiDomain->value(); // display 'fass.de'
419420
$asciiDomain->isAscii(); // returns true
420421
~~~
421422

422-
**TIP: Always favor submitting a `Pdp\Domain` object for resolution rather that a
423+
> [!TIP]
424+
> Always favor submitting a `Pdp\Domain` object for resolution rather that a
423425
string or an object that can be cast to a string to avoid unexpected format
424426
conversion errors/results. By default, and with lack of information conversion
425-
is done using IDNA 2008 rules.**
427+
is done using IDNA 2008 rules.
426428

427429
### Managing the package external resources
428430

@@ -469,7 +471,8 @@ on packagist.
469471

470472
#### Refreshing the resource using the provided factories
471473

472-
**THIS IS THE RECOMMENDED WAY OF USING THE LIBRARY**
474+
> [!NOTE]
475+
> THIS IS THE RECOMMENDED WAY OF USING THE LIBRARY
473476
474477
For the purpose of this example we will use our PSR powered solution with:
475478

@@ -526,12 +529,14 @@ $publicSuffixList = $pslStorage->get(PsrStorageFactory::PUBLIC_SUFFIX_LIST_URI);
526529
$topLevelDomains = $rzdStorage->get(PsrStorageFactory::TOP_LEVEL_DOMAIN_LIST_URI);
527530
~~~
528531

529-
**Be sure to adapt the following code to your own application.
532+
> [!NOTE]
533+
> Be sure to adapt the following code to your own application.
530534
The following code is an example given without warranty of it working
531-
out of the box.**
535+
out of the box.
532536

533-
**You should use your dependency injection container to avoid repeating this
534-
code in your application.**
537+
> [!WARNING]
538+
> You should use your dependency injection container to avoid repeating this
539+
code in your application.
535540

536541
### Automatic Updates
537542

@@ -560,7 +565,6 @@ Testing
560565

561566
- a [PHPUnit](https://phpunit.de) test suite
562567
- a code analysis compliance test suite using [PHPStan](https://phpstan.org).
563-
- a code analysis compliance test suite using [Psalm](https://psalm.dev).
564568
- a coding style compliance test suite using [PHP CS Fixer](https://cs.symfony.com).
565569

566570
To run the tests, run the following command from the project folder.

‎composer.json

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -46,16 +46,16 @@
4646
"ext-json": "*"
4747
},
4848
"require-dev": {
49-
"friendsofphp/php-cs-fixer": "^v3.13.2",
50-
"guzzlehttp/guzzle": "^7.5",
51-
"guzzlehttp/psr7": "^1.6 || ^2.4.3",
52-
"phpstan/phpstan": "^1.10.3",
53-
"phpstan/phpstan-phpunit": "^1.3.8",
54-
"phpstan/phpstan-strict-rules": "^1.5.0",
55-
"phpunit/phpunit": "^10.0.12",
56-
"psr/http-factory": "^1.0.1",
49+
"friendsofphp/php-cs-fixer": "^3.53.0",
50+
"guzzlehttp/guzzle": "^7.8.1",
51+
"guzzlehttp/psr7": "^1.6 || ^2.6.2",
52+
"phpstan/phpstan": "^1.10.66",
53+
"phpstan/phpstan-phpunit": "^1.3.16",
54+
"phpstan/phpstan-strict-rules": "^1.5.3",
55+
"phpunit/phpunit": "^10.5.15 || ^11.1.1",
56+
"psr/http-factory": "^1.0.2",
5757
"psr/simple-cache": "^1.0.1",
58-
"symfony/cache": "^v5.0.0 || ^v6.0.0"
58+
"symfony/cache": "^v5.0.0 || ^6.4.6"
5959
},
6060
"suggest": {
6161
"psr/http-client-implementation": "To use the storage functionnality which depends on PSR-18",
@@ -71,8 +71,9 @@
7171
"scripts": {
7272
"phpcs": "PHP_CS_FIXER_IGNORE_ENV=1 php-cs-fixer fix -vvv --diff --dry-run --allow-risky=yes --ansi",
7373
"phpcs:fix": "php-cs-fixer fix -vvv --allow-risky=yes --ansi",
74-
"phpstan": "phpstan analyse -l max -c phpstan.neon src --xdebug --memory-limit=256M --ansi",
74+
"phpstan": "phpstan analyse -c phpstan.neon --ansi --memory-limit=192M",
7575
"phpunit": "XDEBUG_MODE=coverage phpunit --coverage-text",
76+
"phpunit:min": "phpunit --no-coverage",
7677
"test": [
7778
"@phpunit",
7879
"@phpstan",

‎phpstan.neon

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@ includes:
33
- vendor/phpstan/phpstan-phpunit/extension.neon
44
- vendor/phpstan/phpstan-phpunit/rules.neon
55
parameters:
6+
level: max
7+
paths:
8+
- src
69
ignoreErrors:
710
- message: '#has no value type specified in iterable type array.#'
811
path: src/Rules.php
@@ -12,4 +15,5 @@ parameters:
1215
path: src/Rules.php
1316
- message: '#Variable \$line on left side of \?\? always exists and is not nullable.#'
1417
path: src/Rules.php
18+
- '#^Parameter \#1 \$callback of function set_error_handler expects#'
1519
reportUnmatchedIgnoredErrors: true

‎phpunit.xml.dist

Lines changed: 9 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,6 @@
11
<?xml version="1.0" encoding="UTF-8"?>
2-
<phpunit
3-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4-
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.0/phpunit.xsd"
5-
bootstrap="vendor/autoload.php"
6-
backupGlobals="false"
7-
colors="true"
8-
processIsolation="false"
9-
stopOnFailure="false"
10-
cacheDirectory=".phpunit.cache"
11-
backupStaticProperties="false"
12-
>
2+
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.4/phpunit.xsd" bootstrap="vendor/autoload.php" backupGlobals="false" colors="true" processIsolation="false" stopOnFailure="false" cacheDirectory=".phpunit.cache" backupStaticProperties="false">
133
<coverage>
14-
<include>
15-
<directory suffix=".php">src</directory>
16-
</include>
17-
<exclude>
18-
<directory suffix="Test.php">src</directory>
19-
</exclude>
204
<report>
215
<clover outputFile="build/clover.xml"/>
226
<html outputDirectory="build/coverage"/>
@@ -31,4 +15,12 @@
3115
<logging>
3216
<junit outputFile="build/junit.xml"/>
3317
</logging>
18+
<source>
19+
<include>
20+
<directory suffix=".php">src</directory>
21+
</include>
22+
<exclude>
23+
<directory suffix="Test.php">src</directory>
24+
</exclude>
25+
</source>
3426
</phpunit>

‎src/Domain.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ public function label(int $key): ?string
8686
/**
8787
* @return list<int>
8888
*/
89-
public function keys(string $label = null): array
89+
public function keys(?string $label = null): array
9090
{
9191
return $this->registeredName->keys($label);
9292
}
@@ -155,7 +155,7 @@ public function clear(): self
155155
/**
156156
* @throws CannotProcessHost
157157
*/
158-
public function slice(int $offset, int $length = null): self
158+
public function slice(int $offset, ?int $length = null): self
159159
{
160160
return $this->newInstance($this->registeredName->slice($offset, $length));
161161
}

‎src/DomainName.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ public function labels(): array;
4949
*
5050
* @return list<int>
5151
*/
52-
public function keys(string $label = null): array;
52+
public function keys(?string $label = null): array;
5353

5454
/**
5555
* The external iterator iterates over the DomainInterface labels
@@ -119,5 +119,5 @@ public function clear(): self;
119119
*
120120
* If $length is null it returns all elements from $offset to the end of the Domain.
121121
*/
122-
public function slice(int $offset, int $length = null): self;
122+
public function slice(int $offset, ?int $length = null): self;
123123
}

‎src/DomainTest.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -168,14 +168,14 @@ public static function toUnicodeProvider(): iterable
168168
public function testToAscii(
169169
?string $domain,
170170
?string $expectedDomain,
171-
?string $expectedAsciiDomain
171+
?string $expectedIDNDomain
172172
): void {
173173
$domain = Domain::fromIDNA2008($domain);
174174
self::assertSame($expectedDomain, $domain->value());
175175

176176
/** @var Domain $domainIDN */
177177
$domainIDN = $domain->toAscii();
178-
self::assertSame($expectedAsciiDomain, $domainIDN->value());
178+
self::assertSame($expectedIDNDomain, $domainIDN->value());
179179
}
180180

181181
/**

‎src/RegisteredName.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ public function label(int $key): ?string
190190
/**
191191
* @return list<int>
192192
*/
193-
public function keys(string $label = null): array
193+
public function keys(?string $label = null): array
194194
{
195195
if (null === $label) {
196196
return array_keys($this->labels);
@@ -345,7 +345,7 @@ public function clear(): self
345345
/**
346346
* @throws CannotProcessHost
347347
*/
348-
public function slice(int $offset, int $length = null): self
348+
public function slice(int $offset, ?int $length = null): self
349349
{
350350
$nbLabels = count($this->labels);
351351
if ($offset < - $nbLabels || $offset > $nbLabels) {

‎src/ResolvedDomainTest.php

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -173,17 +173,17 @@ public function testItCanBeConvertedToAscii(
173173
?string $publicSuffix,
174174
?string $expectedDomain,
175175
?string $expectedSuffix,
176-
?string $expectedAsciiDomain,
177-
?string $expectedAsciiSuffix
176+
?string $expectedIDNDomain,
177+
?string $expectedIDNSuffix
178178
): void {
179179
$domain = ResolvedDomain::fromUnknown(Domain::fromIDNA2003($domain), count(Domain::fromIDNA2003($publicSuffix)));
180180
self::assertSame($expectedDomain, $domain->value());
181181
self::assertSame($expectedSuffix, $domain->suffix()->value());
182182

183183
/** @var ResolvedDomain $domainIDN */
184184
$domainIDN = $domain->toAscii();
185-
self::assertSame($expectedAsciiDomain, $domainIDN->value());
186-
self::assertSame($expectedAsciiSuffix, $domainIDN->suffix()->value());
185+
self::assertSame($expectedIDNDomain, $domainIDN->value());
186+
self::assertSame($expectedIDNSuffix, $domainIDN->suffix()->value());
187187
}
188188

189189
/**
@@ -236,7 +236,7 @@ public static function toAsciiProvider(): iterable
236236
}
237237

238238
#[DataProvider('withSubDomainWorksProvider')]
239-
public function testItCanHaveItsSubDomainChanged(ResolvedDomain $domain, DomainName|string|null $subdomain, string $expected = null): void
239+
public function testItCanHaveItsSubDomainChanged(ResolvedDomain $domain, DomainName|string|null $subdomain, ?string $expected = null): void
240240
{
241241
$result = $domain->withSubDomain($subdomain);
242242

There was a problem loading the remainder of the diff.

0 commit comments

Comments
 (0)
Please sign in to comment.