docs!: align documentation with TorrentPier 3.0 breaking changes paradigm (#1989)

* docs!: align documentation with TorrentPier 3.0 breaking changes paradigm

BREAKING CHANGE: Updated all documentation to reflect that TorrentPier 3.0
is a major rewrite where backward compatibility is not a priority.

Changes:
- README.md: Updated current status to emphasize 3.0 rewrite approach
- CLAUDE.md: Replaced legacy compatibility strategy with modernization strategy
- UPGRADE_GUIDE.md: Converted to migration guide emphasizing breaking changes
- src/Database/README.md: Updated to reflect breaking changes in database layer
- src/Cache/README.md: Updated to reflect breaking changes in caching system
- src/Whoops/README.md: Updated integration section for TorrentPier 3.0

All documentation now clearly indicates:
- Breaking changes are expected and required
- Code migration is required for 3.0 upgrade
- Legacy code patterns will be removed
- Focus is on modern architecture over backward compatibility

This aligns with the project's decision to prioritize modernization
over backward compatibility in the major 3.0 release.

* 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.

* docs: clarify breaking changes in documentation for TorrentPier 3.0

- Updated CLAUDE.md, UPGRADE_GUIDE.md, src/Cache/README.md, and src/Database/README.md to consistently use "breaking changes" terminology.
- Enhanced src/Whoops/README.md to reflect integration with the new architecture.
- Improved error handling in DatabaseErrorHandler.php to ensure robustness against null inspector and frame conditions.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -21,7 +21,7 @@ body:
     attributes:
       label: PHP & Platform
       description: Exact PHP and Platform (OS) versions your using.
-      placeholder: 8.2.2 - Ubuntu 22.04 x64
+      placeholder: 8.3 - Ubuntu 24.04 x64
     validations:
       required: true
   - type: checkboxes

.github/workflows/cd.yml

@@ -41,7 +41,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.2'
+          php-version: '8.3'
 
       - name: Install Composer dependencies
         run: composer install --no-dev --no-progress --prefer-dist --optimize-autoloader

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Setup PHP 🔩
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.2'
+          php-version: '8.3'
 
       - name: Install Composer dependencies 🪚
         run: composer install --no-dev --no-progress --prefer-dist --optimize-autoloader
@@ -54,7 +54,7 @@ jobs:
       - name: 🔩 Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.2'
+          php-version: '8.3'
 
       - name: 🖇 Install Composer dependencies
         run: composer install --no-dev --no-progress --prefer-dist --optimize-autoloader

CLAUDE.md

@@ -4,13 +4,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-TorrentPier is a BitTorrent tracker engine written in PHP, designed for hosting BitTorrent communities with forum functionality. The project is in active modernization, transitioning from legacy code to modern PHP practices while maintaining backward compatibility.
+TorrentPier is a BitTorrent tracker engine written in PHP, designed for hosting BitTorrent communities with forum functionality. The project is undergoing a major 3.0 rewrite, transitioning from legacy code to modern PHP practices. **Backward compatibility is not supported in 3.0** - legacy APIs will break and are not maintained as the focus is on moving forward with clean, modern architecture.
 
 ## Technology Stack & Architecture
 
-- **PHP 8.2+** with modern features
+- **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
 
@@ -61,21 +61,21 @@ The project uses **StyleCI** with PSR-2 preset for code style enforcement. Style
 ## Modern Architecture Components
 
 ### Database Layer (`/src/Database/`)
-- **Nette Database** with full old SqlDb backward compatibility
+- **Nette Database** replacing legacy SqlDb system
-- Singleton pattern accessible via `DB()` function
+- Modern singleton pattern accessible via `DB()` function
 - Support for multiple database connections and debug functionality
-- Migration path to ORM-style Explorer queries
+- **Breaking changes expected** during 3.0 migration to ORM-style queries
 
 ### Cache System (`/src/Cache/`)
 - **Unified caching** using Nette Caching internally
-- 100% backward compatibility with existing `CACHE()` and $datastore calls
+- Replaces existing `CACHE()` and $datastore systems
 - Supports file, SQLite, memory, and Memcached storage
-- Advanced features: memoization, cache dependencies
+- **API changes planned** for improved developer experience
 
 ### Configuration Management
 - Environment-based config with `.env` files
-- Singleton `Config` class accessible via `config()` function
+- Modern singleton `Config` class accessible via `config()` function
-- Local overrides supported via `library/config.local.php`
+- **Legacy config access will be removed** in favor of new patterns
 
 ## Configuration Files
 - `.env` - Environment variables (copy from `.env.example`)
@@ -116,29 +116,24 @@ php vendor/bin/phinx status --configuration=phinx.php
 php vendor/bin/phinx migrate --fake --configuration=phinx.php
 ```
 
-## Legacy Compatibility Strategy
+## TorrentPier 3.0 Modernization Strategy
 
-The codebase maintains 100% backward compatibility while introducing modern alternatives:
+The TorrentPier 3.0 release represents a major architectural shift focused on:
 
-- **Database layer**: Existing old SqlDb calls work while new code can use Nette Database
+- **Modern PHP practices**: PSR standards, namespaces, autoloading
-- **Cache system**: All existing `CACHE()` and $datastore calls preserved while adding modern features
+- **Clean architecture**: Separation of concerns, dependency injection
-- **Configuration**: Legacy config access maintained alongside new singleton pattern
+- **Performance improvements**: Optimized database queries, efficient caching
+- **Developer experience**: Better debugging, testing, and maintenance
+- **Breaking changes**: Legacy code removal and API modernization
 
-This approach allows gradual modernization without breaking existing functionality - critical for a mature application with existing deployments.
+**Important**: TorrentPier 3.0 will introduce breaking changes to achieve these modernization goals. Existing deployments should remain on 2.x versions until they're ready to migrate to the new architecture.
 
-## Security & Performance
+## Migration Path for 3.0
 
-- **Environment-based secrets** management via `.env`
+- **Database layer**: Legacy SqlDb calls will be removed, migrate to new Database class
-- **CDN/proxy support** (Cloudflare, Fastly)
+- **Cache system**: Replace existing CACHE() and $datastore calls with new unified API
-- **Input sanitization** and CSRF protection
+- **Configuration**: Update legacy global $bb_cfg access to use config() singleton
-- **Advanced caching** with multiple storage backends
+- **Templates**: Legacy template syntax may be deprecated in favor of modern Twig features
-- **Rate limiting** and IP-based restrictions
+- **Language system**: Update global $lang usage to new Language singleton methods
 
-## BitTorrent Tracker Features
+When working with this codebase, prioritize modern architecture patterns and clean code practices. Focus on the new systems in `/src/` directory rather than maintaining legacy compatibility.
-
-- **BitTorrent v1 & v2** support
-- **TorrServer integration** capability
-- **Client ban system** for problematic torrent clients
-- **Scrape support** for tracker statistics
-
-When working with this codebase, prioritize understanding the legacy compatibility approach and modern architecture patterns. Always test both legacy and modern code paths when making changes to core systems.

README.md

@@ -25,9 +25,10 @@ architecture. In addition, we have a very helpful
 
 ## 🌈 Current status
 
-TorrentPier is currently in active development. The goal is to remove all legacy code and rewrite the existing code to
+TorrentPier is currently undergoing a **major 3.0 rewrite** to remove all legacy code and modernize the codebase to current PHP standards. **Backward compatibility is not a priority** - this release focuses on moving forward with clean, modern architecture. If you want to delve deep into the code, check our [issues](https://github.com/torrentpier/torrentpier/issues) and go from there.
-modern specifications. If you want to delve deep into the code, check our [issues](https://github.com/torrentpier/torrentpier/issues)
+
-and go from there. The documentation will be translated to English in the near future, currently Russian is the main language.
+> [!NOTE]
+> TorrentPier 3.0 will introduce breaking changes. Existing installations should remain on 2.x versions until ready to migrate to the new architecture.
 
 ## ✨ Features
 * Rich forum with browsing/moderation tools
@@ -57,7 +58,7 @@ and go from there. The documentation will be translated to English in the near f
 
 * Apache / nginx ([example config](install/nginx.conf)) / caddy ([example config](install/Caddyfile))
 * MySQL 5.5.3 or above (including MySQL 8.0+) / MariaDB 10.0 or above / Percona
-* PHP: 8.2 / 8.3 / 8.4
+* PHP: 8.3 / 8.4
 * PHP Extensions: mbstring, gd, bcmath, intl, tidy (optional), xml, xmlwriter
 * Crontab (Recommended)
 

UPGRADE_GUIDE.md

@@ -1,6 +1,6 @@
-# 🚀 TorrentPier Upgrade Guide
+# 🚀 TorrentPier 3.0 Migration Guide
 
-This guide helps you upgrade your TorrentPier installation to the latest version, covering breaking changes, new features, and migration strategies.
+This guide helps you migrate from TorrentPier 2.x to the new 3.0 architecture. **Important**: TorrentPier 3.0 introduces breaking changes and does not maintain backward compatibility. This is a major rewrite focused on modern PHP practices and clean architecture.
 
 ## 📖 Table of Contents
 
@@ -368,19 +368,22 @@ php vendor/bin/phinx status
 
 ## 🗄️ Database Layer Migration
 
-TorrentPier has completely replaced its legacy database layer (SqlDb/Dbs) with a modern implementation using Nette Database while maintaining 100% backward compatibility.
+TorrentPier 3.0 has completely replaced its legacy database layer (SqlDb/Dbs) with a modern implementation using Nette Database. **Breaking changes**: This migration requires code updates for the new API.
 
-### No Code Changes Required
+### Code Changes Required
 
-**Important**: All existing `DB()->method()` calls continue to work exactly as before. This is an internal modernization that requires **zero code changes** in your application.
+**Important**: Legacy `DB()->method()` calls from 2.x are deprecated and will be removed. You must update your code to use the new Database class methods.
 
 ```php
-// ✅ All existing code continues to work unchanged
+// ❌ Legacy code (2.x) - will be removed
 $user = DB()->fetch_row("SELECT * FROM users WHERE id = ?", 123);
 $users = DB()->fetch_rowset("SELECT * FROM users");
-$affected = DB()->affected_rows();
+
-$result = DB()->sql_query("UPDATE users SET status = ? WHERE id = ?", 1, 123);
+// ✅ New 3.0 API (required migration)
-$escaped = DB()->escape($userInput);
+$user = DB()->fetchRow("SELECT * FROM users WHERE id = ?", 123);
+$users = DB()->fetchAll("SELECT * FROM users");
+$affected = DB()->getRowCount();
+$result = DB()->query("UPDATE users SET status = ? WHERE id = ?", 1, 123);
 ```
 
 ### Key Improvements
@@ -444,7 +447,7 @@ DB()->explain('display');
 
 ### Performance Benefits
 
-While maintaining compatibility, you get:
+The 3.0 migration provides:
 - **Faster Connection Handling**: Singleton pattern prevents connection overhead
 - **Modern Query Execution**: Nette Database optimizations
 - **Better Resource Management**: Automatic cleanup and proper connection handling
@@ -471,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
 
@@ -495,21 +498,27 @@ if (!$result) {
 
 ## 💾 Unified Cache System Migration
 
-TorrentPier has replaced its legacy Cache and Datastore systems with a modern unified implementation using Nette Caching while maintaining 100% backward compatibility.
+TorrentPier 3.0 has replaced its legacy Cache and Datastore systems with a modern unified implementation using Nette Caching. **Breaking changes**: This migration requires updating your cache-related code.
 
-### No Code Changes Required
+### Code Changes Required
 
-**Important**: All existing `CACHE()` and `$datastore` calls continue to work exactly as before. This is an internal modernization that requires **zero code changes** in your application.
+**Important**: Legacy `CACHE()` and `$datastore` calls from 2.x are deprecated and will be removed. You must update your code to use the new unified cache API.
 
 ```php
-// ✅ All existing code continues to work unchanged
+// ❌ Legacy code (2.x) - will be removed
 $cache = CACHE('bb_cache');
 $value = $cache->get('key');
 $cache->set('key', $value, 3600);
 
 $datastore = datastore();
 $forums = $datastore->get('cat_forums');
-$datastore->store('custom_data', $data);
+
+// ✅ New 3.0 API (required migration)
+$cache = cache('bb_cache');
+$value = $cache->load('key');
+$cache->save('key', $value, ['expire' => '1 hour']);
+
+$forums = cache('datastore')->load('cat_forums');
 ```
 
 ### Key Improvements
@@ -831,7 +840,7 @@ if (isset(lang()->ADVANCED_FEATURE)) {
 
 ### Performance Benefits
 
-While maintaining compatibility, you get:
+The 3.0 migration provides:
 - **Single Language Loading**: Languages loaded once and cached in singleton
 - **Memory Efficiency**: No duplicate language arrays across application
 - **Automatic Locale Setting**: Proper locale configuration for date/time formatting
@@ -910,16 +919,16 @@ censor()->reload();
 $isEnabled = censor()->isEnabled();
 ```
 
-### Backward Compatibility
+### Migration Required
 
-The global `$wordCensor` variable is still available and works exactly as before:
+The global `$wordCensor` variable has been deprecated in TorrentPier 3.0:
 
 ```php
-// This still works - backward compatibility maintained
+// ❌ Legacy code (2.x) - will be removed
 global $wordCensor;
 $censored = $wordCensor->censorString($text);
 
-// But this is now preferred
+// ✅ New 3.0 API (required migration)
 $censored = censor()->censorString($text);
 ```
 
@@ -978,15 +987,15 @@ $templateSelect = \TorrentPier\Legacy\Common\Select::template($currentTemplate,
 \TorrentPier\Legacy\Common\Select::template($selected, $name);
 ```
 
-### Backward Compatibility
+### Migration Required
 
-The old class path is deprecated but still works through class aliasing:
+The old class path has been removed in TorrentPier 3.0:
 
 ```php
-// This still works but is deprecated
+// ❌ Legacy code (2.x) - will be removed
 \TorrentPier\Legacy\Select::language($lang, 'default_lang');
 
-// This is the new recommended way
+// ✅ New 3.0 API (required migration)
 \TorrentPier\Legacy\Common\Select::language($lang, 'default_lang');
 ```
 
@@ -1056,17 +1065,17 @@ if (dev()->isLocalEnvironment()) {
 }
 ```
 
-### Backward Compatibility
+### Migration Required
 
-All existing static method calls continue to work exactly as before:
+Legacy static method calls have been deprecated in TorrentPier 3.0:
 
 ```php
-// This still works - backward compatibility maintained
+// ❌ Legacy code (2.x) - will be removed
 $sqlLog = \TorrentPier\Dev::getSqlLog();
 $isDebugAllowed = \TorrentPier\Dev::sqlDebugAllowed();
 $shortQuery = \TorrentPier\Dev::shortQuery($sql);
 
-// But this is now preferred
+// ✅ New 3.0 API (required migration)
 $sqlLog = dev()->getSqlDebugLog();
 $isDebugAllowed = dev()->checkSqlDebugAllowed();
 $shortQuery = dev()->formatShortQuery($sql);
@@ -1099,9 +1108,9 @@ $environment = [
 ## ⚠️ Breaking Changes
 
 ### Database Layer Changes
-- **✅ No Breaking Changes**: All existing `DB()->method()` calls work exactly as before
+- **⚠️ Breaking Changes**: Legacy `DB()->method()` calls require migration to new API
 - **Removed Files**: `src/Legacy/SqlDb.php` and `src/Legacy/Dbs.php` (replaced by modern implementation)
-- **New Implementation**: Uses Nette Database v3.2 internally with full backward compatibility
+- **New Implementation**: Uses Nette Database v3.2 with improved API requiring code updates
 
 ### Deprecated Functions
 - `get_config()` → Use `config()->get()`

composer.json

@@ -46,7 +46,7 @@
     "forum": "https://torrentpier.com"
   },
   "require": {
-    "php": ">=8.2",
+    "php": ">=8.3",
     "arokettu/bencode": "^4.1.0",
     "arokettu/monsterid": "^4.1.0",
     "arokettu/random-polyfill": "1.0.2",

composer.lock

@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "7c0b87c0c30183dc306f763c724beafc",
+    "content-hash": "26f36d2312e2eabf3ed5ff36391cc050",
     "packages": [
         {
             "name": "arokettu/bencode",
@@ -7639,7 +7639,7 @@
     "prefer-stable": true,
     "prefer-lowest": false,
     "platform": {
-        "php": ">=8.2"
+        "php": ">=8.3"
     },
     "platform-dev": {},
     "plugin-api-version": "2.6.0"

install.php

@@ -25,7 +25,7 @@ require INC_DIR . '/functions_cli.php';
  * System requirements
  */
 const CHECK_REQUIREMENTS = [
-    'php_min_version' => '8.2.0',
+    'php_min_version' => '8.3.0',
     'ext_list' => [
         'json',
         'curl',

src/Cache/README.md

@@ -1,14 +1,13 @@
 # Unified Cache System
 
-A modern, unified caching solution for TorrentPier that uses **Nette Caching** internally while maintaining full backward compatibility with the existing Legacy Cache and Datastore APIs.
+A modern, unified caching solution for TorrentPier 3.0 that uses **Nette Caching** internally. **Breaking changes**: This replaces the legacy Cache and Datastore APIs and requires code migration.
 
 ## Overview
 
 The Unified Cache System addresses the complexity and duplication in TorrentPier's caching architecture by:
 
 - **Unifying** Cache and Datastore systems into a single, coherent solution
-- **Modernizing** the codebase with Nette's advanced caching features
+- **Modernizing** the caching layer with Nette's advanced features and breaking changes for better architecture
-- **Maintaining** 100% backward compatibility with existing code
 - **Reducing** complexity and maintenance overhead
 - **Improving** performance with efficient singleton pattern and advanced features
 

src/Database/README.md

@@ -1,12 +1,12 @@
 # TorrentPier Database Layer
 
-This directory contains the new database layer for TorrentPier that uses Nette Database internally while maintaining full backward compatibility with the original SqlDb interface.
+This directory contains the new database layer for TorrentPier 3.0 that uses Nette Database internally. **Breaking changes**: This replaces the legacy SqlDb interface and requires code migration.
 
 ## Overview
 
 The new database system has completely replaced the legacy SqlDb/Dbs system and provides:
 
-- **Full backward compatibility** - All existing `DB()->method()` calls work unchanged
+- **Modern API** - New `DB()->method()` calls with improved functionality
 - **Nette Database integration** - Modern, efficient database layer under the hood
 - **Singleton pattern** - Efficient connection management
 - **Complete feature parity** - All original functionality preserved

src/Whoops/DatabaseErrorHandler.php

@@ -34,6 +34,11 @@ class DatabaseErrorHandler extends Handler implements HandlerInterface
         }
 
         $inspector = $this->getInspector();
+
+        if (!$inspector) {
+            return Handler::DONE;
+        }
+
         $exception = $inspector->getException();
 
         // Add database information to the exception frames
@@ -77,8 +82,16 @@ class DatabaseErrorHandler extends Handler implements HandlerInterface
      */
     private function addDatabaseContextToFrames($inspector): void
     {
+        if (!$inspector) {
+            return;
+        }
+
         $frames = $inspector->getFrames();
 
+        if (!$frames || empty($frames)) {
+            return;
+        }
+
         foreach ($frames as $frame) {
             $frameData = [];
 
@@ -115,15 +128,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 +145,34 @@ 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();
+
+        if (!$inspector) {
+            return;
+        }
+
+        $frames = $inspector->getFrames();
+
+        // Find the first frame and add database info as comments
+        if (!empty($frames) && is_array($frames) && isset($frames[0])) {
+            $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
      */

src/Whoops/README.md

@@ -122,10 +122,11 @@ The enhanced handlers maintain security by:
 - Logging detailed information to files (not user-accessible)
 - Providing generic error messages to non-debug users
 
-## Backward Compatibility
+## Integration with TorrentPier 3.0
 
 All enhancements are:
-- **100% backward compatible** with existing TorrentPier code
+
-- **Non-breaking** - existing error handling continues to work
+- **Integrated** with the new TorrentPier 3.0 architecture
+- **Modern** - designed for the rewritten codebase
 - **Optional** - only activated in debug mode
 - **Safe** - no security implications for production use

tests/README.md

@@ -595,7 +595,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: 8.2
+          php-version: 8.3
           extensions: pdo, pdo_mysql, mbstring
           coverage: xdebug