Introduce UserException attribute

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Enh #150: Cleanup templates, remove legacy code (@vjik)
 - New #151: Add `$traceLink` parameter to `HtmlRenderer` to allow linking to trace files (@vjik)
+- New #153: Introduce `UserException` attribute to mark user exceptions (@vjik)
 
 ## 4.1.0 April 18, 2025
 

src/Exception/UserException.php

@@ -4,14 +4,34 @@
 
 namespace Yiisoft\ErrorHandler\Exception;
 
+use Attribute;
 use Exception;
+use ReflectionClass;
+use Throwable;
+
+use function count;
 
 /**
- * UserException is the base class for exceptions that are meant to be shown to end users.
- * Such exceptions are often caused by mistakes of end users.
+ * `UserException` is an exception and a class attribute that indicates
+ * the exception message is safe to display to end users.
+ *
+ * Usage:
+ * - throw directly (`throw new UserException(...)`) for explicit user-facing errors;
+ * - annotate any exception class with the `#[UserException]` attribute
+ *   to mark its messages as user-facing without extending this class.
  *
  * @final
  */
+#[Attribute(Attribute::TARGET_CLASS)]
 class UserException extends Exception
 {
+    public static function isUserException(Throwable $throwable): bool
+    {
+        if ($throwable instanceof self) {
+            return true;
+        }
+
+        $attributes = (new ReflectionClass($throwable))->getAttributes(self::class);
+        return count($attributes) > 0;
+    }
 }

templates/production.php

@@ -9,7 +9,7 @@
  * @var HtmlRenderer $this
  */
 
-if ($throwable instanceof UserException) {
+if (UserException::isUserException($throwable)) {
     $name = $this->getThrowableName($throwable);
     $message = $throwable->getMessage();
 } else {

tests/Exception/UserException/NotFoundException.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ErrorHandler\Tests\Exception\UserException;
+
+use Exception;
+use Yiisoft\ErrorHandler\Exception\UserException;
+
+#[UserException]
+final class NotFoundException extends Exception
+{
+}

tests/Exception/UserException/UserExceptionTest.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ErrorHandler\Tests\Exception\UserException;
+
+use Exception;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+use Throwable;
+use Yiisoft\ErrorHandler\Exception\UserException;
+
+use function PHPUnit\Framework\assertInstanceOf;
+use function PHPUnit\Framework\assertSame;
+
+final class UserExceptionTest extends TestCase
+{
+    public function testUserExceptionInstance(): void
+    {
+        $exception = new UserException('User error message');
+
+        assertSame('User error message', $exception->getMessage());
+        assertInstanceOf(Exception::class, $exception);
+    }
+
+    public static function dataIsUserException(): iterable
+    {
+        yield [true, new UserException()];
+        yield [false, new Exception()];
+        yield [true, new NotFoundException()];
+    }
+
+    #[DataProvider('dataIsUserException')]
+    public function testIsUserException(bool $expected, Throwable $exception): void
+    {
+        assertSame($expected, UserException::isUserException($exception));
+    }
+}

tests/Factory/ThrowableResponseFactoryTest.php

@@ -32,12 +32,8 @@ public function testHandleWithHeadRequestMethod(): void
                 $this->createThrowable(),
                 $this->createServerRequest('HEAD', ['Accept' => ['test/html']])
             );
-        $response
-            ->getBody()
-            ->rewind();
-        $content = $response
-            ->getBody()
-            ->getContents();
+        $response->getBody()->rewind();
+        $content = $response->getBody()->getContents();
 
         $this->assertEmpty($content);
         $this->assertSame([HeaderRenderer::DEFAULT_ERROR_MESSAGE], $response->getHeader('X-Error-Message'));