Add Deprecated attribute with GUID tracking and structured metadata

DEPRECATED.md

@@ -2,8 +2,55 @@
 
 This file lists documentation that has been consolidated, superseded, or is no longer maintained.
 
-**Last Updated**: 2026-01-27  
-**Status**: Phases 1, 2, and 3 completed. Code cleanup for deprecated methods completed.
+**Last Updated**: 2026-01-31  
+**Status**: Phases 1, 2, and 3 completed. Code cleanup for deprecated methods completed. New Deprecated attribute available.
+
+---
+
+## 🆕 New in v3.3: Deprecated Attribute
+
+### PHP Attribute for Marking Deprecated Code
+
+A new `#[Deprecated]` attribute is now available for marking deprecated code elements with structured metadata:
+
+**Location**: `App\Attributes\Deprecated`
+
+**Features**:
+- **GUID Tracking**: Unique identifier for each deprecated element (e.g., `DEP-2024-001`)
+- **Documentation**: Clear message explaining why something is deprecated
+- **Version Info**: Track when deprecation occurred (`since`)
+- **Migration Path**: Suggest alternatives (`alternative`)
+- **Removal Planning**: Indicate when removal is planned (`removeIn`)
+
+**Usage Example**:
+```php
+use App\Attributes\Deprecated;
+
+#[Deprecated(
+    guid: 'DEP-2024-001',
+    message: 'Use the new implementation instead',
+    since: 'v1.0.0',
+    alternative: 'NewClass::newMethod()',
+    removeIn: 'v2.0.0'
+)]
+public function oldMethod(): void
+{
+    // deprecated implementation
+}
+```
+
+**Supported Targets**:
+- Classes
+- Methods
+- Properties
+- Class Constants
+
+**Benefits over `@deprecated` DocBlock**:
+- Structured data that can be programmatically analyzed
+- GUID-based tracking across codebase
+- Type-safe with PHP 8 attributes
+- Consistent deprecation metadata format
+- Can be queried via reflection API
 
 ---
 
@@ -166,6 +213,43 @@ Update code comments referencing old documentation:
 // See ROLE_SYSTEM.md for role hierarchy
 ```
 
+### Migrating from @deprecated to #[Deprecated] Attribute
+
+**Old Style** (DocBlock annotation):
+```php
+/**
+ * @deprecated since version 1.0 (2026-01-30). Use is_subscriber flag instead.
+ *             Will be removed in version 2.0.
+ */
+public const OPERATOR_LEVEL_CUSTOMER = 100;
+```
+
+**New Style** (PHP 8 Attribute):
+```php
+use App\Attributes\Deprecated;
+
+#[Deprecated(
+    guid: 'DEP-2026-001',
+    message: 'Use is_subscriber flag instead',
+    since: 'v1.0.0 (2026-01-30)',
+    removeIn: 'v2.0.0'
+)]
+public const OPERATOR_LEVEL_CUSTOMER = 100;
+```
+
+**Benefits of Migration**:
+- Searchable by GUID for tracking
+- Programmatic access via Reflection API
+- Type-safe and validated at parse time
+- Consistent structure across codebase
+- Can generate deprecation reports
+
+**Migration Strategy**:
+1. New deprecations should use `#[Deprecated]` attribute
+2. Existing `@deprecated` can be migrated gradually
+3. Both styles are acceptable during transition period
+4. Update `@deprecated` to attribute when touching that code
+
 ---
 
 ## Removed Files

app/Attributes/Deprecated.php

@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Attributes;
+
+use Attribute;
+
+/**
+ * Deprecated Attribute
+ * 
+ * Marks classes, methods, properties, or constants as deprecated.
+ * Provides structured deprecation information including GUID tracking,
+ * version information, and migration guidance.
+ * 
+ * @see https://www.php.net/manual/en/language.attributes.overview.php
+ * 
+ * Example usage:
+ * ```php
+ * #[Deprecated(
+ *     guid: 'DEP-2024-001',
+ *     message: 'Use the new implementation instead',
+ *     since: 'v1.0.0',
+ *     alternative: 'NewClass::newMethod()'
+ * )]
+ * public function oldMethod(): void
+ * {
+ *     // deprecated implementation
+ * }
+ * ```
+ */
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::TARGET_PROPERTY | Attribute::TARGET_CLASS_CONSTANT)]
+class Deprecated
+{
+    /**
+     * Create a new Deprecated attribute instance.
+     *
+     * @param string $guid Unique identifier for tracking this deprecation (e.g., 'DEP-2024-001')
+     * @param string $message Description of why this is deprecated
+     * @param string|null $since Version or date when this was deprecated (e.g., 'v1.0.0', '2024-01-30')
+     * @param string|null $alternative Recommended alternative to use instead
+     * @param string|null $removeIn Version when this will be removed (e.g., 'v2.0.0')
+     */
+    public function __construct(
+        public readonly string $guid,
+        public readonly string $message,
+        public readonly ?string $since = null,
+        public readonly ?string $alternative = null,
+        public readonly ?string $removeIn = null,
+    ) {
+    }
+
+    /**
+     * Get a formatted deprecation message.
+     *
+     * @return string
+     */
+    public function getFormattedMessage(): string
+    {
+        $parts = [];
+
+        $parts[] = "DEPRECATED [{$this->guid}]";
+
+        if ($this->since) {
+            $parts[] = "since {$this->since}";
+        }
+
+        $parts[] = "- {$this->message}";
+
+        if ($this->alternative) {
+            $parts[] = "Use {$this->alternative} instead.";
+        }
+
+        if ($this->removeIn) {
+            $parts[] = "Will be removed in {$this->removeIn}.";
+        }
+
+        return implode(' ', $parts);
+    }
+
+    /**
+     * Convert to array representation.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        return [
+            'guid' => $this->guid,
+            'message' => $this->message,
+            'since' => $this->since,
+            'alternative' => $this->alternative,
+            'removeIn' => $this->removeIn,
+            'formattedMessage' => $this->getFormattedMessage(),
+        ];
+    }
+}