Allow configuring behavior via the DOCTRINE_DEPRECATIONS env var

Author: nicolas-grekas

README.md

@@ -19,13 +19,16 @@ Enable Doctrine deprecations to be sent to a PSR3 logger:
 ```
 
 Enable Doctrine deprecations to be sent as `@trigger_error($message, E_USER_DEPRECATED)`
-messages.
+messages by setting the `DOCTRINE_DEPRECATIONS` environment variable to `trigger`.
+Alternatively, call:
 
 ```php
 \Doctrine\Deprecations\Deprecation::enableWithTriggerError();
 ```
 
-If you only want to enable deprecation tracking, without logging or calling `trigger_error` then call:
+If you only want to enable deprecation tracking, without logging or calling `trigger_error`
+then set the `DOCTRINE_DEPRECATIONS` environment variable to `track`.
+Alternatively, call:
 
 ```php
 \Doctrine\Deprecations\Deprecation::enableTrackingDeprecations();

lib/Doctrine/Deprecations/Deprecation.php

@@ -46,8 +46,8 @@ class Deprecation
     private const TYPE_TRIGGER_ERROR      = 2;
     private const TYPE_PSR_LOGGER         = 4;
 
-    /** @var int */
-    private static $type = self::TYPE_NONE;
+    /** @var self::TYPE_*|null */
+    private static $type;
 
     /** @var LoggerInterface|null */
     private static $logger;
@@ -72,7 +72,9 @@ class Deprecation
      */
     public static function trigger(string $package, string $link, string $message, ...$args): void
     {
-        if (self::$type === self::TYPE_NONE) {
+        $type = self::$type ?? self::getTypeFromEnv();
+
+        if ($type === self::TYPE_NONE) {
             return;
         }
 
@@ -118,7 +120,9 @@ public static function trigger(string $package, string $link, string $message, .
      */
     public static function triggerIfCalledFromOutside(string $package, string $link, string $message, ...$args): void
     {
-        if (self::$type === self::TYPE_NONE) {
+        $type = self::$type ?? self::getTypeFromEnv();
+
+        if ($type === self::TYPE_NONE) {
             return;
         }
 
@@ -161,7 +165,9 @@ public static function triggerIfCalledFromOutside(string $package, string $link,
      */
     private static function delegateTriggerToBackend(string $message, array $backtrace, string $link, string $package): void
     {
-        if ((self::$type & self::TYPE_PSR_LOGGER) > 0) {
+        $type = self::$type ?? self::getTypeFromEnv();
+
+        if (($type & self::TYPE_PSR_LOGGER) > 0) {
             $context = [
                 'file' => $backtrace[0]['file'],
                 'line' => $backtrace[0]['line'],
@@ -172,7 +178,7 @@ private static function delegateTriggerToBackend(string $message, array $backtra
             self::$logger->notice($message, $context);
         }
 
-        if (! ((self::$type & self::TYPE_TRIGGER_ERROR) > 0)) {
+        if (! (($type & self::TYPE_TRIGGER_ERROR) > 0)) {
             return;
         }
 
@@ -263,4 +269,26 @@ public static function getTriggeredDeprecations(): array
     {
         return self::$ignoredLinks;
     }
+
+    /**
+     * @return self::TYPE_*
+     */
+    private static function getTypeFromEnv(): int
+    {
+        switch ($_SERVER['DOCTRINE_DEPRECATIONS'] ?? $_ENV['DOCTRINE_DEPRECATIONS'] ?? null) {
+            case 'trigger':
+                self::$type = self::TYPE_TRIGGER_ERROR;
+                break;
+
+            case 'track':
+                self::$type = self::TYPE_TRACK_DEPRECATIONS;
+                break;
+
+            default:
+                self::$type = self::TYPE_NONE;
+                break;
+        }
+
+        return self::$type;
+    }
 }

tests/Doctrine/Deprecations/DeprecationTest.php

@@ -248,4 +248,36 @@ public function testDeprecationCalledFromOutsideInRoot(): void
 
         $this->assertEquals(1, Deprecation::getUniqueTriggeredDeprecationsCount());
     }
+
+    public function testDeprecationTrackByEnv(): void
+    {
+        $reflectionProperty = new ReflectionProperty(Deprecation::class, 'type');
+        $reflectionProperty->setAccessible(true);
+        $reflectionProperty->setValue(null);
+
+        Deprecation::trigger('Foo', 'link', 'message');
+        $this->assertSame(0, Deprecation::getUniqueTriggeredDeprecationsCount());
+
+        $reflectionProperty->setValue(null);
+        $_SERVER['DOCTRINE_DEPRECATIONS'] = 'track';
+
+        Deprecation::trigger('Foo', __METHOD__, 'message');
+        $this->assertSame(1, Deprecation::getUniqueTriggeredDeprecationsCount());
+    }
+
+    public function testDeprecationTriggerByEnv(): void
+    {
+        $reflectionProperty = new ReflectionProperty(Deprecation::class, 'type');
+        $reflectionProperty->setAccessible(true);
+        $reflectionProperty->setValue(null);
+        $_ENV['DOCTRINE_DEPRECATIONS'] = 'trigger';
+
+        $this->expectErrorHandler(
+            'message (DeprecationTest.php:%d called by TestCase.php:%d, ' . __METHOD__ . ', package Foo)',
+            __METHOD__
+        );
+
+        Deprecation::trigger('Foo', __METHOD__, 'message');
+        $this->assertSame(1, Deprecation::getUniqueTriggeredDeprecationsCount());
+    }
 }