Deprecator::$throwExceptions

Resolves #3972

CHANGELOG-v3.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Added
+- Added `craft\services\Deprecator::$throwExceptions`. ([#3972](https://github.com/craftcms/cms/pull/3972))
+
 ### Changed
 - `Craft::parseEnv()` will now boolean values for environment variables set to `true` or `false`. ([#3975](https://github.com/craftcms/cms/issues/3975))
 - Craft now requires Twig ^2.7.2.

src/errors/DeprecationException.php

@@ -0,0 +1,55 @@
+<?php
+/**
+ * @link https://craftcms.com/
+ * @copyright Copyright (c) Pixel & Tonic, Inc.
+ * @license https://craftcms.github.io/license/
+ */
+
+namespace craft\errors;
+
+use Throwable;
+use yii\base\Exception;
+
+/**
+ * Deprecation Error Exception
+ *
+ * @author Pixel & Tonic, Inc. <[email protected]>
+ * @since 3.1.18
+ */
+class DeprecationException extends Exception
+{
+    /**
+     * @var string|null The file the deprecation warning occurred in
+     */
+    public $file;
+
+    /**
+     * @var int|null The line number the deprecation warning occurred on
+     */
+    public $line;
+
+    /**
+     * Constructor
+     *
+     * @param string|null $message
+     * @param string|null $file
+     * @param int|null $line
+     * @param int $code
+     * @param Throwable|null $previous
+     */
+    public function __construct(string $message = null, string $file = null, int $line = null, int $code = 0, Throwable $previous = null)
+    {
+        $this->file = $file;
+        $this->line = $line;
+
+        parent::__construct($message, $code, $previous);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getName()
+    {
+        return 'Deprecation Error';
+    }
+}

src/services/Deprecator.php

@@ -11,6 +11,7 @@
 use craft\db\Query;
 use craft\db\Table;
 use craft\elements\db\ElementQuery;
+use craft\errors\DeprecationException;
 use craft\helpers\Db;
 use craft\helpers\Json;
 use craft\helpers\StringHelper;
@@ -33,6 +34,11 @@ class Deprecator extends Component
     // Properties
     // =========================================================================
 
+    /**
+     * @var bool Whether deprecation warnings should throw exceptions rather than being logged.
+     */
+    public $throwExceptions = false;
+
     /**
      * @var string|false Whether deprecation errors should be logged in the database ('db'),
      * error logs ('logs'), or not at all (false).
@@ -62,6 +68,7 @@ class Deprecator extends Component
      * @param string $message
      * @param string|null $file
      * @param int|null $line
+     * @throws DeprecationException
      */
     public function log(string $key, string $message, string $file = null, int $line = null)
     {
@@ -87,6 +94,10 @@ public function log(string $key, string $message, string $file = null, int $line
             list($file, $line) = $this->_findOrigin($traces);
         }
 
+        if ($this->throwExceptions) {
+            throw new DeprecationException($message, $file, $line);
+        }
+
         $fingerprint = $file . ($line ? ':' . $line : '');
         $index = $key . '-' . $fingerprint;