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.

.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,11 +4,11 @@ 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 a priority** - 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
 - **Composer** for dependency management
@@ -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
-- Singleton pattern accessible via `DB()` function
+- **Nette Database** replacing legacy SqlDb system
+- 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
-- Local overrides supported via `library/config.local.php`
+- Modern singleton `Config` class accessible via `config()` function
+- **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
-- **Cache system**: All existing `CACHE()` and $datastore calls preserved while adding modern features
-- **Configuration**: Legacy config access maintained alongside new singleton pattern
+- **Modern PHP practices**: PSR standards, namespaces, autoloading
+- **Clean architecture**: Separation of concerns, dependency injection
+- **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`
-- **CDN/proxy support** (Cloudflare, Fastly)
-- **Input sanitization** and CSRF protection
-- **Advanced caching** with multiple storage backends
-- **Rate limiting** and IP-based restrictions
+- **Database layer**: Legacy SqlDb calls will be removed, migrate to new Database class
+- **Cache system**: Replace existing CACHE() and $datastore calls with new unified API
+- **Configuration**: Update legacy global $bb_cfg access to use config() singleton
+- **Templates**: Legacy template syntax may be deprecated in favor of modern Twig features
+- **Language system**: Update global $lang usage to new Language singleton methods
 
-## BitTorrent Tracker Features
-
-- **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.
+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.

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
-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.
+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.
+
+> [!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 Change**: 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);
-$escaped = DB()->escape($userInput);
+
+// ✅ New 3.0 API (required migration)
+$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
@@ -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 Change**: 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,6 +1,6 @@
 # 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 Change**: This replaces the legacy Cache and Datastore APIs and requires code migration.
 
 ## Overview
 
@@ -8,7 +8,7 @@ The Unified Cache System addresses the complexity and duplication in TorrentPier
 
 - **Unifying** Cache and Datastore systems into a single, coherent solution
 - **Modernizing** the codebase with Nette's advanced caching features
-- **Maintaining** 100% backward compatibility with existing code
+- **Modernizing** the caching layer with breaking changes for better architecture
 - **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 Change**: 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/README.md

@@ -122,10 +122,10 @@ 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
 
@@ -688,4 +688,4 @@ When adding new components to TorrentPier:
 
 **Remember**: Tests are not just validation tools—they're living documentation of your system's behavior. Write tests that clearly express the intended functionality and help future developers understand the codebase.
 
-For questions or suggestions about the testing infrastructure, please refer to the [TorrentPier GitHub repository](https://github.com/torrentpier/torrentpier) or contribute to the discussion in our community forums.
+For questions or suggestions about the testing infrastructure, please refer to the [TorrentPier GitHub repository](https://github.com/torrentpier/torrentpier) or contribute to the discussion in our community forums.