Refactor to attribute

Author: vjik

CHANGELOG.md

@@ -4,7 +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: Add `UserExceptionInterface` to mark user exceptions (@vjik)
+- New #153: Introduce `UserException` attribute to mark user exceptions (@vjik)
 
 ## 4.1.0 April 18, 2025
 

src/Exception/UserException.php

@@ -4,13 +4,34 @@
 
 namespace Yiisoft\ErrorHandler\Exception;
 
+use Attribute;
 use Exception;
+use ReflectionClass;
+use Throwable;
+
+use function count;
 
 /**
- * `UserException` represents an exception that is meant to be shown to end users.
+ * `UserException` is an exception anв 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
  */
-class UserException extends Exception implements UserExceptionInterface
+#[Attribute(Attribute::TARGET_CLASS)]
+class UserException extends Exception
 {
+    public static function is(Throwable $throwable): bool
+    {
+        if ($throwable instanceof self) {
+            return true;
+        }
+
+        $attributes = (new ReflectionClass($throwable))->getAttributes(self::class);
+        return count($attributes) > 0;
+    }
 }

src/Exception/UserExceptionInterface.php

@@ -1,6 +1,6 @@
 <?php
 
-use Yiisoft\ErrorHandler\Exception\UserExceptionInterface;
+use Yiisoft\ErrorHandler\Exception\UserException;
 use Yiisoft\ErrorHandler\Renderer\HtmlRenderer;
 use Yiisoft\ErrorHandler\ThrowableRendererInterface;
 
@@ -9,7 +9,7 @@
  * @var HtmlRenderer $this
  */
 
-if ($throwable instanceof UserExceptionInterface) {
+if (UserException::is($throwable)) {
     $name = $this->getThrowableName($throwable);
     $message = $throwable->getMessage();
 } else {

templates/production.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/NotFoundException.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 dataIs(): iterable
+    {
+        yield [true, new UserException()];
+        yield [false, new Exception()];
+        yield [true, new NotFoundException()];
+    }
+
+    #[DataProvider('dataIs')]
+    public function testIs(bool $expected, Throwable $exception): void
+    {
+        assertSame($expected, UserException::is($exception));
+    }
+}