diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index c3a7bf266..5eaa6c909 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.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 diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml index f257360c6..8e256db33 100644 --- a/.github/workflows/cd.yml +++ b/.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 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 88eacf309..424e53a1f 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/CLAUDE.md b/CLAUDE.md index 68bd96ae8..8f8a0bf86 100644 --- a/CLAUDE.md +++ b/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 -- 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. diff --git a/README.md b/README.md index 96b27a825..5e7a13049 100644 --- a/README.md +++ b/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) diff --git a/UPGRADE_GUIDE.md b/UPGRADE_GUIDE.md index 2305e8bba..ed045381f 100644 --- a/UPGRADE_GUIDE.md +++ b/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); -$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 @@ -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()` diff --git a/composer.json b/composer.json index 85ef6217d..1f3dce449 100644 --- a/composer.json +++ b/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", diff --git a/composer.lock b/composer.lock index 095574af1..0bbb016c8 100644 --- a/composer.lock +++ b/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" diff --git a/install.php b/install.php index b04535eda..0d1516ce5 100644 --- a/install.php +++ b/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', diff --git a/src/Cache/README.md b/src/Cache/README.md index 17bdc5aee..e2151819b 100644 --- a/src/Cache/README.md +++ b/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 -- **Maintaining** 100% backward compatibility with existing code +- **Modernizing** the caching layer with Nette's advanced features and breaking changes for better architecture - **Reducing** complexity and maintenance overhead - **Improving** performance with efficient singleton pattern and advanced features diff --git a/src/Database/README.md b/src/Database/README.md index a5f47bfe2..b7cc5b05b 100644 --- a/src/Database/README.md +++ b/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 diff --git a/src/Whoops/DatabaseErrorHandler.php b/src/Whoops/DatabaseErrorHandler.php index 8b0aa8392..7668c28c1 100644 --- a/src/Whoops/DatabaseErrorHandler.php +++ b/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 - // This will appear in the Whoops error page + // Use Whoops' built-in method if available - this is the proper way 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 */ diff --git a/src/Whoops/README.md b/src/Whoops/README.md index 90f96f8df..572b42980 100644 --- a/src/Whoops/README.md +++ b/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 \ No newline at end of file +- **Safe** - no security implications for production use diff --git a/tests/README.md b/tests/README.md index 07347ae46..3d048af23 100644 --- a/tests/README.md +++ b/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. \ No newline at end of file +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.