Be strict about deprecations

The original implementation was causing issues with deprecations
triggered in the wrong conditions. By introducing controlled deprecations
using doctrine/deprecation we are able to handle this more properly.

The tests are updated to test the correct behavior, a new deprecation
issue is created to track the deprecations.

Author: jaapio

Diff for: composer.json

@@ -12,7 +12,8 @@
     "require": {
         "php": "^7.4 || ^8.0",
         "phpdocumentor/reflection-common": "^2.0",
-        "phpstan/phpdoc-parser": "^1.13"
+        "phpstan/phpdoc-parser": "^1.13",
+        "doctrine/deprecations": "^1.0"
     },
     "require-dev": {
         "ext-tokenizer": "*",

Diff for: composer.lock

@@ -13,6 +13,7 @@
 
 namespace phpDocumentor\Reflection;
 
+use Doctrine\Deprecations\Deprecation;
 use InvalidArgumentException;
 use phpDocumentor\Reflection\PseudoTypes\ArrayShape;
 use phpDocumentor\Reflection\PseudoTypes\ArrayShapeItem;
@@ -103,11 +104,8 @@
 use function sprintf;
 use function strpos;
 use function strtolower;
-use function trigger_error;
 use function trim;
 
-use const E_USER_DEPRECATED;
-
 final class TypeResolver
 {
     /** @var string Definition of the NAMESPACE operator in PHP */
@@ -579,11 +577,18 @@ private function parse(TokenIterator $tokenIterator): TypeNode
      */
     private function tryParseRemainingCompoundTypes(TokenIterator $tokenIterator, Context $context, Type $type): Type
     {
-        trigger_error(
-            'Legacy nullable type detected, please update your code as
-         you are using nullable types in a docblock. support will be removed in v2.0.0',
-            E_USER_DEPRECATED
-        );
+        if (
+            $tokenIterator->isCurrentTokenType(Lexer::TOKEN_UNION) ||
+            $tokenIterator->isCurrentTokenType(Lexer::TOKEN_INTERSECTION)
+        ) {
+            Deprecation::trigger(
+                'phpdocumentor/type-resolver',
+                'https://github.com/phpDocumentor/TypeResolver/issues/184',
+                'Legacy nullable type detected, please update your code as
+                you are using nullable types in a docblock. support will be removed in v2.0.0',
+            );
+        }
+
         $continue = true;
         while ($continue) {
             $continue = false;

Diff for: src/TypeResolver.php

@@ -13,6 +13,7 @@
 
 namespace phpDocumentor\Reflection;
 
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use InvalidArgumentException;
 use phpDocumentor\Reflection\PseudoTypes\CallableString;
 use phpDocumentor\Reflection\PseudoTypes\ConstExpression;
@@ -73,6 +74,8 @@
  */
 class TypeResolverTest extends TestCase
 {
+    use VerifyDeprecations;
+
     /**
      * @uses         \phpDocumentor\Reflection\Types\Context
      * @uses         \phpDocumentor\Reflection\Types\Array_
@@ -855,8 +858,14 @@ public function testArrayKeyValueSpecification(): void
      * @dataProvider illegalLegacyFormatProvider
      * @testdox create type from $type
      */
-    public function testTypeBuilding(string $type, Type $expected): void
+    public function testTypeBuilding(string $type, Type $expected, bool $deprecation = false): void
     {
+        if ($deprecation) {
+            $this->expectDeprecationWithIdentifier('https://github.com/phpDocumentor/TypeResolver/issues/184');
+        } else {
+            $this->expectNoDeprecationWithIdentifier('https://github.com/phpDocumentor/TypeResolver/issues/184');
+        }
+
         $fixture = new TypeResolver();
         $actual = $fixture->resolve($type, new Context('phpDocumentor'));
 
@@ -1090,16 +1099,19 @@ public function illegalLegacyFormatProvider(): array
     {
         return [
             [
-                '?string|bool',
+                '?string |bool',
                 new Compound([new Nullable(new String_()), new Boolean()]),
+                true,
             ],
             [
                 '?string|?bool',
                 new Compound([new Nullable(new String_()), new Nullable(new Boolean())]),
+                true,
             ],
             [
                 '?string|?bool|null',
                 new Compound([new Nullable(new String_()), new Nullable(new Boolean()), new Null_()]),
+                true,
             ],
             [
                 '?string|bool|Foo',
@@ -1108,10 +1120,12 @@ public function illegalLegacyFormatProvider(): array
                     new Boolean(),
                     new Object_(new Fqsen('\\phpDocumentor\\Foo')),
                 ]),
+                true,
             ],
             [
                 '?string&bool',
                 new Intersection([new Nullable(new String_()), new Boolean()]),
+                true,
             ],
             [
                 '?string&bool|Foo',
@@ -1121,6 +1135,7 @@ public function illegalLegacyFormatProvider(): array
                         new Compound([new Boolean(), new Object_(new Fqsen('\\phpDocumentor\\Foo'))]),
                     ]
                 ),
+                true,
             ],
             [
                 '?string&?bool|null',
@@ -1130,6 +1145,7 @@ public function illegalLegacyFormatProvider(): array
                         new Null_(),
                     ]
                 ),
+                true,
             ],
         ];
     }