fix: update compatibility notes for Nette Database wrapper in documentation

- Updated CLAUDE.md and UPGRADE_GUIDE.md to specify that the Nette Database wrapper provides temporary backward compatibility.
- Enhanced DatabaseErrorHandler to utilize Whoops' built-in methods for adding database information, ensuring compatibility with PHP 8.2+ by avoiding dynamic properties.

CLAUDE.md

@@ -10,7 +10,7 @@ TorrentPier is a BitTorrent tracker engine written in PHP, designed for hosting
 
 - **PHP 8.3+** with modern features
 - **MySQL/MariaDB/Percona** database
-- **Nette Database** with backward-compatible wrapper
+- **Nette Database** with temporary backward-compatible wrapper
 - **Composer** for dependency management
 - **Custom BitTorrent tracker** implementation
 

UPGRADE_GUIDE.md

@@ -474,7 +474,7 @@ The following legacy files have been removed from the codebase:
 
 These were completely replaced by:
 - `src/Database/Database.php` - Modern database class with Nette Database (renamed from `DB.php`)
-- `src/Database/DatabaseFactory.php` - Modern factory with backward compatibility (renamed from `DbFactory.php`)
+- `src/Database/DatabaseFactory.php` - Modern factory with temporary backward compatibility (renamed from `DbFactory.php`)
 - `src/Database/DatabaseDebugger.php` - Dedicated debug functionality extracted from Database class
 - `src/Database/DebugSelection.php` - Debug-enabled wrapper for Nette Database Selection
 

src/Whoops/DatabaseErrorHandler.php

@@ -115,15 +115,14 @@ class DatabaseErrorHandler extends Handler implements HandlerInterface
         try {
             $databaseInfo = $this->collectDatabaseInformation();
 
-            // Use reflection to add custom data to the exception
+            // Use Whoops' built-in method if available - this is the proper way
-            // This will appear in the Whoops error page
             if (method_exists($exception, 'setAdditionalInfo')) {
                 $exception->setAdditionalInfo('Database Information', $databaseInfo);
-            } else {
-                // Fallback: store in a property that Whoops can access
-                if (!isset($exception->databaseInfo)) {
-                    $exception->databaseInfo = $databaseInfo;
             }
+            // For PHP 8.2+ compatibility: Avoid dynamic properties completely
+            // Instead, we'll add the info as frame comments on the first database-related frame
+            else {
+                $this->addDatabaseInfoAsFrameComments($databaseInfo);
             }
         } catch (\Exception $e) {
             // Don't let database info collection break error handling
@@ -133,6 +132,29 @@ class DatabaseErrorHandler extends Handler implements HandlerInterface
         }
     }
 
+    /**
+     * Add database info as frame comments when setAdditionalInfo is not available
+     */
+    private function addDatabaseInfoAsFrameComments(array $databaseInfo): void
+    {
+        $inspector = $this->getInspector();
+        $frames = $inspector->getFrames();
+
+        // Find the first frame and add database info as comments
+        if (!empty($frames)) {
+            $firstFrame = $frames[0];
+            $firstFrame->addComment('=== Database Information ===', '');
+
+            foreach ($databaseInfo as $key => $value) {
+                if (is_string($value) || is_numeric($value)) {
+                    $firstFrame->addComment("DB Info - $key", $value);
+                } elseif (is_array($value) && !empty($value)) {
+                    $firstFrame->addComment("DB Info - $key", json_encode($value, JSON_PRETTY_PRINT));
+                }
+            }
+        }
+    }
+
     /**
      * Check if a frame is related to database operations
      */