From f30afe7a37884390bc88cedfa4e4cc356af12db8 Mon Sep 17 00:00:00 2001 From: Yury Pikhtarev Date: Sat, 21 Jun 2025 13:15:14 +0400 Subject: [PATCH] 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. --- CLAUDE.md | 2 +- UPGRADE_GUIDE.md | 4 ++-- src/Cache/README.md | 5 ++--- src/Database/README.md | 2 +- src/Whoops/DatabaseErrorHandler.php | 20 +++++++++++++++++++- src/Whoops/README.md | 3 ++- 6 files changed, 27 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 546cabba1..8f8a0bf86 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ 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 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. +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 diff --git a/UPGRADE_GUIDE.md b/UPGRADE_GUIDE.md index 8e8dcdd45..ed045381f 100644 --- a/UPGRADE_GUIDE.md +++ b/UPGRADE_GUIDE.md @@ -368,7 +368,7 @@ php vendor/bin/phinx status ## 🗄️ Database Layer Migration -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. +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. ### Code Changes Required @@ -498,7 +498,7 @@ if (!$result) { ## 💾 Unified Cache System Migration -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. +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. ### Code Changes Required diff --git a/src/Cache/README.md b/src/Cache/README.md index 3e339d420..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 3.0 that uses **Nette Caching** internally. **Breaking Change**: This replaces the legacy Cache and Datastore APIs and requires code migration. +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 breaking changes for better architecture +- **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 cc58c6941..b7cc5b05b 100644 --- a/src/Database/README.md +++ b/src/Database/README.md @@ -1,6 +1,6 @@ # TorrentPier Database Layer -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. +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 diff --git a/src/Whoops/DatabaseErrorHandler.php b/src/Whoops/DatabaseErrorHandler.php index 7e8d20303..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 = []; @@ -138,10 +151,15 @@ class DatabaseErrorHandler extends Handler implements HandlerInterface 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)) { + if (!empty($frames) && is_array($frames) && isset($frames[0])) { $firstFrame = $frames[0]; $firstFrame->addComment('=== Database Information ===', ''); diff --git a/src/Whoops/README.md b/src/Whoops/README.md index ebb06a045..572b42980 100644 --- a/src/Whoops/README.md +++ b/src/Whoops/README.md @@ -125,7 +125,8 @@ The enhanced handlers maintain security by: ## Integration with TorrentPier 3.0 All enhancements are: + - **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