From a8a2989fe266d9b4af8c889ca8c379f75d2bed20 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= <postmaster@greg0ire.fr>
Date: Sat, 30 Nov 2024 15:25:36 +0100
Subject: [PATCH] Document how to integrate with PHPUnit

Right now, it is possible to display Doctrine deprecations with a bit of
PHPUnit configuration.
Note that this does not seem to clash with triggering self-deprecations,
provided you use the VerifyDeprecations trait in tests that call the
deprecated pieces of code.
---
 README.md           | 61 +++++++++++++++++++++++++++++++++++++++++++++
 src/Deprecation.php |  6 ++---
 tests/EnvTest.php   | 22 ++++++++++++++++
 3 files changed, 86 insertions(+), 3 deletions(-)
 create mode 100644 tests/EnvTest.php

diff --git a/README.md b/README.md
index 93caf83..8b806d1 100644
--- a/README.md
+++ b/README.md
@@ -150,6 +150,67 @@ class MyTest extends TestCase
 }
 ```
 
+## Displaying deprecations after running a PHPUnit test suite
+
+It is possible to integrate this library with PHPUnit to display all
+deprecations triggered during the test suite execution.
+
+```xml
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         colors="true"
+         bootstrap="vendor/autoload.php"
+         displayDetailsOnTestsThatTriggerDeprecations="true"
+         failOnDeprecation="true"
+    >
+    <!-- one attribute to display the deprecations, the other to fail the test suite -->
+
+    <php>
+        <!-- ensures native PHP deprecations are used -->
+        <server name="DOCTRINE_DEPRECATIONS" value="trigger"/>
+    </php>
+
+    <!-- ensures the @ operator in @trigger_error is ignored -->
+    <source ignoreSuppressionOfDeprecations="true">
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+</phpunit>
+```
+
+Note that you can still trigger Deprecations in your code, provided you use the
+`#[WithoutErrorHandler]` attribute to disable PHPUnit's error handler for tests
+that call it. Be wary that this will disable all error handling, meaning it
+will mask any warnings or errors that would otherwise be caught by PHPUnit.
+
+At the moment, it is not possible to disable deduplication with an environment
+variable, but you can use a bootstrap file to achieve that:
+
+```php
+// tests/bootstrap.php
+<?php
+
+declare(strict_types=1);
+
+require dirname(__DIR__) . '/vendor/autoload.php';
+
+use Doctrine\Deprecations\Deprecation;
+
+Deprecation::withoutDeduplication();
+```
+
+Then, reference that file in your PHPUnit configuration:
+
+```xml
+<phpunit …
+        bootstrap="tests/bootstrap.php"
+        …
+    >
+    …
+</phpunit>
+```
+
 ## What is a deprecation identifier?
 
 An identifier for deprecations is just a link to any resource, most often a
diff --git a/src/Deprecation.php b/src/Deprecation.php
index bad5070..9797e34 100644
--- a/src/Deprecation.php
+++ b/src/Deprecation.php
@@ -226,19 +226,19 @@ private static function basename(string $filename): string
 
     public static function enableTrackingDeprecations(): void
     {
-        self::$type  = self::$type ?? 0;
+        self::$type  = self::$type ?? self::getTypeFromEnv();
         self::$type |= self::TYPE_TRACK_DEPRECATIONS;
     }
 
     public static function enableWithTriggerError(): void
     {
-        self::$type  = self::$type ?? 0;
+        self::$type  = self::$type ?? self::getTypeFromEnv();
         self::$type |= self::TYPE_TRIGGER_ERROR;
     }
 
     public static function enableWithPsrLogger(LoggerInterface $logger): void
     {
-        self::$type   = self::$type ?? 0;
+        self::$type   = self::$type ?? self::getTypeFromEnv();
         self::$type  |= self::TYPE_PSR_LOGGER;
         self::$logger = $logger;
     }
diff --git a/tests/EnvTest.php b/tests/EnvTest.php
new file mode 100644
index 0000000..fa994d0
--- /dev/null
+++ b/tests/EnvTest.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Deprecations;
+
+use PHPUnit\Framework\TestCase;
+use ReflectionProperty;
+
+class EnvTest extends TestCase
+{
+    public function testEnvIsTakenIntoAccountWhenCallingEnableTrackingDeprecations(): void
+    {
+        $_ENV['DOCTRINE_DEPRECATIONS'] = 'trigger';
+        Deprecation::enableTrackingDeprecations();
+        $reflectionProperty = new ReflectionProperty(Deprecation::class, 'type');
+        $reflectionProperty->setAccessible(true);
+        self::assertSame(1 | 2, $reflectionProperty->getValue());
+        unset($_ENV['DOCTRINE_DEPRECATIONS']);
+        $reflectionProperty->setValue(null, null);
+    }
+}