Merge pull request #314 from jeremykendall/develop

Release 6.1.0

Author: nyamsprod

.gitattributes

@@ -5,9 +5,10 @@
 /.github             export-ignore
 /.gitignore          export-ignore
 /.php_cs             export-ignore
-/phpstan.neon       export-ignore
-/.travis.yml         export-ignore
-/README.md           export-ignore
+/phpstan.neon        export-ignore
 /phpunit.xml.dist    export-ignore
+/psalm.xml           export-ignore
 /CHANGELOG.md        export-ignore
+/UPGRADING.md        export-ignore
+/README.md           export-ignore
 /**/*Test.php        export-ignore

.github/workflows/build.yaml

@@ -23,8 +23,8 @@ jobs:
             - run: composer update --no-progress ${{ matrix.composer-flags }}
             - run: composer phpunit
             - run: composer phpstan
-              if: ${{ matrix.php == '7.4' }}
+              if: ${{ matrix.php == '8.0' }}
             - run: composer psalm
-              if: ${{ matrix.php == '7.4' }}
+              if: ${{ matrix.php == '8.0' }}
             - run: composer phpcs
-              if: ${{ matrix.php == '7.4' }}
+              if: ${{ matrix.php == '8.0' }}

.php_cs renamed to .php-cs-fixer.php

@@ -4,7 +4,9 @@
     ->in(__DIR__.'/src')
 ;
 
-return PhpCsFixer\Config::create()
+$config = new PhpCsFixer\Config();
+
+return $config
     ->setRules([
         '@PSR2' => true,
         'array_syntax' => ['syntax' => 'short'],
@@ -16,24 +18,22 @@
         'no_leading_import_slash' => true,
         'no_superfluous_phpdoc_tags' => true,
         'no_trailing_comma_in_singleline_array' => true,
-        'no_superfluous_phpdoc_tags' => true,
         'no_unused_imports' => true,
         'ordered_imports' => ['imports_order' => ['class', 'function', 'const'], 'sort_algorithm' => 'alpha'],
         'phpdoc_add_missing_param_annotation' => ['only_untyped' => false],
         'phpdoc_align' => true,
         'phpdoc_no_empty_return' => true,
         'phpdoc_order' => true,
         'phpdoc_scalar' => true,
-        'phpdoc_to_comment' => true,
+        'phpdoc_to_comment' => false,
         'phpdoc_summary' => true,
-        'psr0' => true,
-        'psr4' => true,
+        'psr_autoloading' => true,
         'return_type_declaration' => ['space_before' => 'none'],
         'single_blank_line_before_namespace' => true,
         'single_quote' => true,
         'space_after_semicolon' => true,
         'ternary_operator_spaces' => true,
-        'trailing_comma_in_multiline_array' => true,
+        'trailing_comma_in_multiline' => true,
         'trim_array_spaces' => true,
         'whitespace_after_comma_in_array' => true,
         'yoda_style' => true,

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All Notable changes to `PHP Domain Parser` starting from the **5.x** series will be documented in this file
 
+## 6.1.0 - 2021-06-19
+
+### Added
+
+- `TimeToLive::until`
+- `TimeToLive::fromDurationString`
+
+### Fixed
+
+- `.gitattributes` files to be filter out.
+- `TimeToLive` marked as internal
+- `Host::toUnicode` method MUST never throw exceptions on conversion according to RFC3490.
+- `UnableToResolveDomain` typo in the exception message
+
+### Deprecated
+
+- `TimeToLive::fromDateTimeInterface` use `TimeToLive::fromNow`
+- `TimeToLive::fromScalar` use `TimeToLive::convert`
+
+### Removed
+
+- None
+
 ## 6.0.0 - 2020-12-13
 
 ### Added

README.md

@@ -60,10 +60,12 @@ For the [Public Suffix List](http://publicsuffix.org/) you need to use the
 ~~~php
 <?php 
 use Pdp\Rules;
+use Pdp\Domain;
 
 $publicSuffixList = Rules::fromPath('/path/to/cache/public-suffix-list.dat');
+$domain = Domain::fromIDNA2008('www.PreF.OkiNawA.jP');
 
-$result = $publicSuffixList->resolve('www.PreF.OkiNawA.jP');
+$result = $publicSuffixList->resolve($domain);
 echo $result->domain()->toString();            //display 'www.pref.okinawa.jp';
 echo $result->subDomain()->toString();         //display 'www';
 echo $result->secondLevelDomain()->toString(); //display 'pref';
@@ -76,11 +78,15 @@ For the [IANA Top Level Domain List](https://www.iana.org/domains/root/files),
 the `Pdp\TopLevelDomains` class is use instead:
 
 ~~~php
+<?php
+
+use Pdp\Domain;
 use Pdp\TopLevelDomains;
 
 $topLevelDomains = TopLevelDomains::fromPath('/path/to/cache/tlds-alpha-by-domain.txt');
+$domain = Domain::fromIDNA2008('www.PreF.OkiNawA.jP');
 
-$result = $topLevelDomains->resolve('www.PreF.OkiNawA.jP');
+$result = $topLevelDomains->resolve($domain);
 echo $result->domain()->toString();            //display 'www.pref.okinawa.jp';
 echo $result->suffix()->toString();            //display 'jp';
 echo $result->secondLevelDomain()->toString(); //display 'okinawa';
@@ -109,31 +115,38 @@ These methods resolve the domain against their respective data source using
 the same rules as the `resolve` method but will instead throw an exception 
 if no valid effective TLD is found or if the submitted domain is invalid.
 
+**All these methods expect as their sole argument a `Pdp\Host` implementing 
+object, but other types (ie: `string`, `null`  and stringable objects) are 
+supported with predefined conditions as explained in the remaining document.**
+
 ~~~php
-<?php 
+<?php
+
+use Pdp\Domain;
 use Pdp\Rules;
 use Pdp\TopLevelDomains;
 
 $publicSuffixList = Rules::fromPath('/path/to/cache/public-suffix-list.dat');
+$domain = Domain::fromIDNA2008('qfdsf.unknownTLD');
 
-$publicSuffixList->getICANNDomain('qfdsf.unknownTLD');
+$publicSuffixList->getICANNDomain($domain);
 // will throw because `.unknownTLD` is not part of the ICANN section
 
-$result = $publicSuffixList->getCookieDomain('qfdsf.unknownTLD');
+$result = $publicSuffixList->getCookieDomain($domain);
 $result->suffix()->value();   // returns 'unknownTLD'
 $result->suffix()->isKnown(); // returns false
 // will not throw because the domain syntax is correct.
 
-$publicSuffixList->getCookieDomain('com');
+$publicSuffixList->getCookieDomain(Domain::fromIDNA2008('com'));
 // will not throw because the domain syntax is invalid (ie: does not support public suffix)
 
-$result = $publicSuffixList->resolve('com');
+$result = $publicSuffixList->resolve(Domain::fromIDNA2008('com'));
 $result->suffix()->value();   // returns null
 $result->suffix()->isKnown(); // returns false
 // will not throw but its public suffix value equal to NULL
 
 $topLevelDomains = TopLevelDomains::fromPath('/path/to/cache/public-suffix-list.dat');
-$topLevelDomains->getIANADomain('com');
+$topLevelDomains->getIANADomain(Domain::fromIDNA2008('com'));
 // will not throw because the domain syntax is invalid (ie: does not support public suffix)
 ~~~
 
@@ -171,10 +184,12 @@ The `Pdp\ResolvedDomain` decorates the `Pdp\Domain` class resolved but also
 gives access as separate methods to the domain different components.
 
 ~~~php
+use Pdp\Domain;
 use Pdp\TopLevelDomains;
 
+$domain = Domain::fromIDNA2008('www.PreF.OkiNawA.jP');
 /** @var TopLevelDomains $topLevelDomains */
-$result = $topLevelDomains->resolve('www.PreF.OkiNawA.jP');
+$result = $topLevelDomains->resolve($domain);
 echo $result->domain()->toString();            //display 'www.pref.okinawa.jp';
 echo $result->suffix()->toString();            //display 'jp';
 echo $result->secondLevelDomain()->toString(); //display 'okinawa';
@@ -188,14 +203,15 @@ You can modify the returned `Pdp\ResolvedDomain` instance using the following me
 ~~~php
 <?php 
 
+use Pdp\Domain;
 use Pdp\Rules;
 
 /** @var Rules $publicSuffixList */
-$result = $publicSuffixList->resolve('shop.example.com');
+$result = $publicSuffixList->resolve(Domain::fromIDNA2008('shop.example.com'));
 $altResult = $result
-    ->withSubDomain('foo.bar')
-    ->withSecondLevelDomain('test')
-    ->withSuffix('example');
+    ->withSubDomain(Domain::fromIDNA2008('foo.bar'))
+    ->withSecondLevelDomain(Domain::fromIDNA2008('test'))
+    ->withSuffix(Domain::fromIDNA2008('example'));
 
 echo $result->domain()->toString(); //display 'shop.example.com';
 $result->suffix()->isKnown();       //return true;
@@ -217,10 +233,11 @@ origin.
 
 ~~~php
 <?php 
+use Pdp\Domain;
 use Pdp\Rules;
 
 /** @var Rules $publicSuffixList */
-$suffix = $publicSuffixList->resolve('example.github.io')->suffix();
+$suffix = $publicSuffixList->resolve(Domain::fromIDNA2008('example.github.io'))->suffix();
 
 echo $suffix->domain()->toString(); //display 'github.io';
 $suffix->isICANN();                 //will return false
@@ -274,11 +291,12 @@ manipulating domain labels. You can access the object using the following method
 `Domain` objects usage are explain in the next section.
 
 ~~~php
-<?php 
+<?php
+use Pdp\Domain;
 use Pdp\Rules;
 
 /** @var Rules $publicSuffixList */
-$result = $publicSuffixList->resolve('www.bbc.co.uk');
+$result = $publicSuffixList->resolve(Domain::from2008('www.bbc.co.uk'));
 $domain = $result->domain();
 echo $domain->toString(); // display 'www.bbc.co.uk'
 count($domain);           // returns 4
@@ -303,10 +321,11 @@ following methods:
 
 ~~~php
 <?php 
+use Pdp\Domain;
 use Pdp\Rules;
 
 /** @var Rules $publicSuffixList */
-$domain = $publicSuffixList->resolve('www.ExAmpLE.cOM')->domain();
+$domain = $publicSuffixList->resolve(Domain::from2008('www.ExAmpLE.cOM'))->domain();
 
 $newDomain = $domain
     ->withLabel(1, 'com')  //replace 'example' by 'com'
@@ -540,8 +559,9 @@ Testing
 `pdp-domain-parser` has:
 
 - a [PHPUnit](https://phpunit.de) test suite
-- a coding style compliance test suite using [PHP CS Fixer](http://cs.sensiolabs.org/).
-- a code analysis compliance test suite using [PHPStan](https://github.com/phpstan/phpstan).
+- a code analysis compliance test suite using [PHPStan](https://phpstan.org).
+- a code analysis compliance test suite using [Psalm](https://psalm.dev).
+- a coding style compliance test suite using [PHP CS Fixer](https://cs.symfony.com).
 
 To run the tests, run the following command from the project folder.
 
@@ -570,10 +590,9 @@ The MIT License (MIT). Please see [License File](LICENSE) for more information.
 Attribution
 -------
 
-Portions of the `Pdp\Converter` and `Pdp\Rules` are derivative works of the PHP
+Portions of the `Pdp\Rules` class are derivative works of the PHP
 [registered-domain-libs](https://github.com/usrflo/registered-domain-libs).
-Those parts of this codebase are heavily commented, and I've included a copy of
-the Apache Software Foundation License 2.0 in this project.
+I've included a copy of the Apache Software Foundation License 2.0 in this project.
 
 [ico-github-actions-build]: https://img.shields.io/github/workflow/status/jeremykendall/php-domain-parser/Build?style=flat-square
 [ico-packagist]: https://img.shields.io/packagist/dt/jeremykendall/php-domain-parser.svg?style=flat-square

composer.json

@@ -41,6 +41,7 @@
     ],
     "require": {
         "php": "^7.4 || ^8.0",
+        "ext-filter": "*",
         "ext-intl": "*",
         "ext-json": "*"
     },
@@ -71,7 +72,8 @@
     },
     "scripts": {
         "phpcs": "php-cs-fixer fix -vvv --diff --dry-run --allow-risky=yes --ansi",
-        "phpstan": "phpstan analyse -l max -c phpstan.neon src --ansi",
+        "phpcs:fix": "php-cs-fixer fix -vvv --allow-risky=yes --ansi",
+        "phpstan": "phpstan analyse -l max -c phpstan.neon src --memory-limit=256M --ansi",
         "psalm": "psalm --show-info=true",
         "phpunit": "phpunit --coverage-text",
         "test": [
@@ -83,6 +85,7 @@
     },
     "scripts-descriptions": {
         "phpcs": "Runs coding style test suite",
+        "phpcs:fix": "Fix the package coding style",
         "phpstan": "Runs complete codebase static analysis",
         "psalm": "Runs complete codebase static analysis",
         "phpunit": "Runs unit and functional testing",

phpstan.neon

@@ -4,5 +4,4 @@ includes:
   - vendor/phpstan/phpstan-phpunit/rules.neon
 parameters:
   ignoreErrors:
-    - '#should be covariant with return type#'
   reportUnmatchedIgnoredErrors: true

psalm.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <psalm
-    errorLevel="3"
+    errorLevel="1"
     resolveFromConfigFile="true"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"

src/Domain.php

@@ -45,7 +45,7 @@ final class Domain implements DomainName
     private const REGEXP_URI_DELIMITERS = '/[:\/?#\[\]@ ]/';
 
     /**
-     * @var array<string>
+     * @var array<int, string>
      */
     private array $labels;
 
@@ -176,7 +176,7 @@ private function domainToUnicode(string $domain): string
      */
     public function getIterator(): Iterator
     {
-        foreach ($this->labels as $offset => $label) {
+        foreach ($this->labels as $label) {
             yield $label;
         }
     }
@@ -216,7 +216,7 @@ public function label(int $key): ?string
     }
 
     /**
-     * @return array<int>
+     * @return list<int>
      */
     public function keys(string $label = null): array
     {
@@ -228,13 +228,17 @@ public function keys(string $label = null): array
     }
 
     /**
-     * @return array<string>
+     * @return array<int, string>
      */
     public function labels(): array
     {
         return $this->labels;
     }
 
+    /**
+     * @psalm-suppress MoreSpecificReturnType
+     * @psalm-suppress LessSpecificReturnStatement
+     */
     public function toAscii(): self
     {
         if (null === $this->domain) {
@@ -249,6 +253,10 @@ public function toAscii(): self
         return new self($this->type, $domain);
     }
 
+    /**
+     * @psalm-suppress MoreSpecificReturnType
+     * @psalm-suppress LessSpecificReturnStatement
+     */
     public function toUnicode(): self
     {
         if (null === $this->domain) {
@@ -266,7 +274,7 @@ public function toUnicode(): self
     /**
      * Filter a subdomain to update the domain part.
      *
-     * @param string|object $domain a domain
+     * @param string|object|null $domain a domain
      *
      * @throws TypeError if the domain can not be converted
      */