diff --git a/.gitattributes b/.gitattributes index 9cdfca08c..a4a7cabc6 100644 --- a/.gitattributes +++ b/.gitattributes @@ -2,13 +2,14 @@ .github/ export-ignore .gitignore export-ignore AGENTS.md export-ignore -ncs.* export-ignore +dresscode.neon export-ignore phpstan*.neon export-ignore src/**/*.latte export-ignore docs/ export-ignore tests/ export-ignore tools/latte-convert/ export-ignore +* text=auto *.php* diff=php *.sh text eol=lf tools/latte-convert/tests/fixtures/*.latte text eol=lf diff --git a/.github/workflows/coding-style.yml b/.github/workflows/coding-style.yml index 4ab0aee40..78db7e2fc 100644 --- a/.github/workflows/coding-style.yml +++ b/.github/workflows/coding-style.yml @@ -17,18 +17,18 @@ jobs: - run: php temp/code-checker/code-checker --strict-types --no-progress -i tests/Tracy/fixtures -i examples/assets -i *.latte - nette_cs: - name: Nette Coding Standard + dresscode: + name: DressCode runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: shivammathur/setup-php@v2 with: - php-version: 8.3 + php-version: 8.4 coverage: none - - run: composer create-project nette/coding-standard temp/coding-standard ^3 --no-progress - - run: php temp/coding-standard/ecs check src tests tools + - run: composer create-project dresscode/dresscode temp/dresscode ^1.0 --no-progress + - run: php temp/dresscode/bin/dresscode check js: diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index bb13517de..4700272c2 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -11,7 +11,7 @@ jobs: strategy: matrix: os: [ubuntu-latest, windows-latest] - php: ['8.2', '8.3', '8.4', '8.5'] + php: ['8.2', '8.3', '8.4', '8.5', '8.6'] sapi: ['php', 'php-cgi'] fail-fast: false @@ -43,10 +43,10 @@ jobs: with: php-version: 8.2 extensions: ds - coverage: none + coverage: pcov - run: composer install --no-progress --prefer-dist - - run: composer tester -- -p phpdbg ${{ env.php-options }} --coverage ./coverage.xml --coverage-src ./src + - run: composer tester -- ${{ env.php-options }} --coverage ./coverage.xml --coverage-src ./src continue-on-error: true - uses: coverallsapp/github-action@v2 with: diff --git a/AGENTS.md b/AGENTS.md index dd94fbd15..5f60c6377 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,12 @@ deferred content, the dumper, BlueScreen, the Bar, the logger). Read the relevan `docs/internals/` seam before editing one - especially `deferred-content.md`, the most counterintuitive part. +`docs/upgrading.md` records, per released version, every change visible to +users of the package (renames, removals, deprecations, signatures, behavior, +configuration), each with its commit hash; internal changes are not in it. It +is the place to look up the history of a public symbol. Do not write to it; it +is extended at release time from the git history. + ## Project Overview Tracy is a debugging and error-visualization library for PHP: BlueScreen error @@ -21,7 +27,7 @@ Dumper, and a production error Logger. It auto-detects development vs production emits **markdown for agents** (automated browsers via `navigator.webdriver`, or any client sending an `X-Tracy-Agent` header) instead of HTML. -- **PHP Version**: 8.2 - 8.5 +- **PHP Version**: 8.2 - 8.6 - **Package**: `tracy/tracy` (currently v2.12) ## Essential Commands @@ -45,8 +51,8 @@ composer compile-templates ## Conventions - Every PHP file starts with `declare(strict_types=1);`; **tabs**; return type and - opening brace on separate lines; Nette Coding Standard (`ncs.php`). JS is linted - with `@nette/eslint-plugin`. + opening brace on separate lines; the Nette coding standard, which + `dresscode.neon` applies. JS is linted with `@nette/eslint-plugin`. - Tests are Nette Tester `.phpt` using `test()` and `getTempDir()`. **CI runs both `php` and `php-cgi`**; UI-rendering tests need `php-cgi`. - Templates are `.latte` (HTML-escaping) / `*.agent.latte` (text/markdown, no diff --git a/composer.json b/composer.json index a4f2e7530..9d0ba4f58 100644 --- a/composer.json +++ b/composer.json @@ -15,7 +15,7 @@ } ], "require": { - "php": "8.2 - 8.5", + "php": "8.2 - 8.6", "ext-session": "*", "ext-json": "*" }, @@ -27,7 +27,7 @@ "nette/tester": "^2.6", "latte/latte": "^2.5 || ^3.0", "psr/log": "^1.0 || ^2.0 || ^3.0", - "phpstan/phpstan": "^2.1@stable", + "phpstan/phpstan": "^2.3@stable", "phpstan/extension-installer": "^1.4@stable", "nette/phpstan-rules": "^1.0" }, @@ -49,7 +49,7 @@ }, "extra": { "branch-alias": { - "dev-master": "2.12-dev" + "dev-master": "3.0-dev" } }, "config": { diff --git a/docs/internals/bluescreen.md b/docs/internals/bluescreen.md index 26f758e2c..e540c474b 100644 --- a/docs/internals/bluescreen.md +++ b/docs/internals/bluescreen.md @@ -47,7 +47,10 @@ template by comparing against that index. `CodeHighlighter` tokenizes PHP, shows `DisplayLines` (15) lines around the error — the public `$lines` parameters of the `highlight*` methods are ignored — highlights the line and column, and replaces `/*sensitive{*/…/*}*/` regions with `*****` (`Describer::HiddenValue`) before -highlighting (PHP path only, not the plain-text one). +highlighting (not for the `php: false` path). The markdown variant does +not highlight, but its source snippets go through the same +`CodeHighlighter::hideSensitive()`; any new place printing PHP source must too. +The masking keeps the newlines of a multi-line region, so line numbers stay true. Two dumpers exist: `getDumper()` renders **HTML** (`BlueScreen::$maxDepth` etc., `LOCATION_CLASS`, the shared `SNAPSHOT`, scrubber, `keysToHide`) and feeds the page diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 000000000..21a212d08 --- /dev/null +++ b/docs/upgrading.md @@ -0,0 +1,128 @@ +# Upgrading tracy/tracy + +## 2.12.1 + +- **Changed** `Tracy\Debugger::dump()` called with `return: true` now applies `Tracy\Debugger::$keysToHide` and, in CLI, also `$maxDepth`, `$maxLength` and `$maxItems`; previously it ignored them (69f595b0) +- **Changed** `Tracy\Debugger::enable()` called again after output has already started is now a silent no-op; previously it threw `LogicException` (1ddaa887) +- **Changed** `Tracy\Dumper` now checks properties coming from `__debugInfo()` or from a custom object exporter against `Tracy\Debugger::$keysToHide` and the scrubber; previously such properties were always shown unmasked (e726c8f0) +- **Changed** `Tracy\Logger::$emailSnooze` now throws `InvalidArgumentException` when its value cannot be parsed by `strtotime()`; previously throttling was silently disabled and an email was sent for every error (ed5e3a48) +- **Changed** `Tracy\Bridges\Psr\TracyToPsrLoggerAdapter::log()` now logs an exception passed in the PSR-3 context only once when the message is empty or equal to the exception message; previously the message was logged a second time (6ccd6e55) + +## 2.12.0 + +- **Deprecated** `Tracy\BlueScreen::$collapsePaths`: use `Tracy\Debugger::$transparentPaths`, a static property filled when the class is loaded; the old name is silently deprecated and its value is still merged in (0deea90e) +- **Changed** `Tracy\BlueScreen::renderToFile()` now writes a Markdown companion file with the same basename next to the HTML file (1dbb02d7) +- **Changed** `Tracy\Logger::getExceptionFile()` now reuses an existing log file only when its name ends with the exception hash and `.html`; previously the hash could appear anywhere in the name (1dbb02d7) + +## 2.11.1 + +- **Signature** `Tracy\Bridges\Psr\PsrToTracyLoggerAdapter::log()` now declares the return type `void`; affects subclasses overriding it (2f4c7df4) +- **Config** `tracy.keysToHide` now fills `Tracy\Debugger::$keysToHide` as well, not only `Tracy\BlueScreen::$keysToHide`, so the listed keys are masked in all dumps (ebd29547) + +## 2.11.0 + +- **Renamed** the Tracy Bar panel id `Tracy:errors` → `Tracy:warnings`; the old id was removed (0dda9390) + +## 2.10.5 + +- **Renamed** `Tracy\Debugger::VERSION` → `Tracy\Debugger::Version`; the old name is silently deprecated (3a6fb902) +- **Deprecated** `Tracy\Debugger::PRODUCTION`: use `Tracy\Debugger::Production`; the old name is silently deprecated (alias since 2.9.6) (3a6fb902) +- **Deprecated** `Tracy\Debugger::DEVELOPMENT`: use `Tracy\Debugger::Development`; the old name is silently deprecated (alias since 2.9.6) (3a6fb902) +- **Deprecated** `Tracy\Debugger::DETECT`: use `Tracy\Debugger::Detect`; the old name is silently deprecated (alias since 2.9.6) (3a6fb902) +- **Deprecated** `Tracy\Debugger::COOKIE_SECRET`: use `Tracy\Debugger::CookieSecret`; the old name is silently deprecated (alias since 2.9.6) (3a6fb902) + +## 2.10.0 + +- **Removed** `Tracy\FireLogger`; FireLogger support was dropped without replacement (8eaf4f25) +- **Removed** `Tracy\Debugger::fireLog()`; FireLogger support was dropped without replacement (8eaf4f25) +- **Removed** `Tracy\Debugger::getFireLogger()`; FireLogger support was dropped without replacement (8eaf4f25) +- **Removed** `Tracy\Debugger::$showFireLogger`; FireLogger support was dropped without replacement (8eaf4f25) +- **Signature** `Tracy\ILogger::log()` is now `log(mixed $value, string $level = self::INFO)`; a custom implementation must declare the same types or PHP reports an incompatible signature (9cf27348) +- **Signature** native types were added to parameters, return values and properties; notably `Tracy\Debugger::enable(bool|string|array|null $mode = null, ?string $logDirectory = null, string|array|null $email = null)`, `Tracy\Debugger::$email`, `Tracy\Debugger::$logDirectory`, `Tracy\Debugger::$browser`, `Tracy\Debugger::$errorTemplate`, `Tracy\Debugger::$productionMode`, `Tracy\Debugger::$showLocation`, `Tracy\Debugger::$scream`, `Tracy\Debugger::$logSeverity`, `Tracy\Logger::__construct()` and `Tracy\BlueScreen::addFiber()`. Assigning a value of another type to a now typed static property throws `TypeError` (9cf27348) + +## 2.9.8 + +- **Changed** `Tracy\BlueScreen::highlightLine()` no longer appends the closing `` tag, which `Tracy\BlueScreen::highlightPhp()` adds instead; also in 2.10.5 (ba708e94) + +## 2.9.6 + +- **Renamed** `Tracy\Debugger::PRODUCTION` → `Tracy\Debugger::Production`; the old name still works as an alias (b6cd4a42) +- **Renamed** `Tracy\Debugger::DEVELOPMENT` → `Tracy\Debugger::Development`; the old name still works as an alias (b6cd4a42) +- **Renamed** `Tracy\Debugger::DETECT` → `Tracy\Debugger::Detect`; the old name still works as an alias (b6cd4a42) +- **Renamed** `Tracy\Debugger::COOKIE_SECRET` → `Tracy\Debugger::CookieSecret`; the old name still works as an alias (b6cd4a42) + +## 2.9.2 + +- **Changed** `Tracy\Dumper::dump()` with the option `Tracy\Dumper::HASH => false` now renders a repeated array or object in full; previously it was collapsed to "see above" / "see below" (d9c2e36b) + +## 2.9.1 + +- **Changed** `Tracy\Debugger::$maxDepth` now defaults to 15; previously 7. Set it to 7 explicitly to keep the previous depth (d6d21012) + +## 2.9.0 + +- **Changed** `Tracy\Debugger::$scream` no longer changes `error_reporting()` globally; it now only controls whether `Tracy\Debugger::errorHandler()` processes a silenced error (52a9cc0c) +- **Config** `tracy.logSeverity` accepts as list items only strings naming `E_*` constants; a raw integer or an arbitrary string is rejected, pass a single int bitmask instead of a list (74a9fbee) + +## 2.8.4 + +- **Changed** `Tracy\Dumper::ITEMS` with the value `0` now means no limit; previously it truncated the output to zero items (0bc1b627) +- **Changed** the scrubber callback (`Tracy\Dumper::SCRUBBER`, `Tracy\BlueScreen::$scrubber`) is now called for non-string keys as well, cast to string; previously it was not called for them (c2f56c43) + +## 2.8.2 + +- **Changed** `Tracy\Debugger::$maxDepth` now defaults to 7; previously 3 (845130ec) +- **Changed** `Tracy\BlueScreen::$collapsePaths` now defaults to the `tracy/`, `nette/` and `latte/` directories; previously to the whole `vendor` directory, so stack frames of other packages are no longer collapsed (8c7bdf03) +- **Changed** `Tracy\Debugger::dump()` with `$return = true` now returns plain text in CLI; previously the captured HTML output (34ed4467) + +## 2.8.1 + +- **Changed** `Tracy\BlueScreen::$maxDepth` now defaults to 5; previously 3 (e23800ff) +- **Changed** `Tracy\BlueScreen::$keysToHide` is no longer matched against virtual (computed) properties, so such a property is dumped in full (47cab47b) +- **Changed** `Tracy\BlueScreen::$scrubber` is no longer called for virtual (computed) properties (47cab47b) + +## 2.8.0 + +- **Renamed** `Tracy\Dumper::LOCATION_LINK` → `Tracy\Dumper::LOCATION_SOURCE`; the old name still works as an alias (67e9e791) +- **Signature** `Tracy\BlueScreen::highlightFile()` and `Tracy\BlueScreen::highlightPhp()` lost the `$vars` and `$keysToHide` parameters together with the feature of inlining dumped variables into the source; drop them from calls (7d2862e9) +- **Changed** `Tracy\Dumper::LOCATION_SOURCE` now implies `Tracy\Dumper::LOCATION_CLASS`, whose bit value changed from `0b0100` to `0b0001` (67e9e791) +- **Changed** `Tracy\Debugger::$showLocation` now defaults to `null` and HTML dumps show the source location by default; previously the default was `false` and the location was hidden (2deb1d2d) +- **Changed** `Tracy\Dumper::DEPTH` now defaults to 7; previously 4 (5f275f6c) +- **Changed** `Tracy\Dumper::dump()`, `Tracy\Dumper::toHtml()` and `Tracy\Dumper::toText()` now truncate arrays and objects to 100 items; pass `Tracy\Dumper::ITEMS` to change or lift the limit (1c4dc56c) +- **Changed** `Tracy\Dumper::dump()` now emits inline `

@@ -20,26 +21,26 @@ echo ' '; -echo Tracy\Helpers::escapeHtml($title) /* pos 22:9 */; +echo Tracy\Helpers::escapeHtml($title) /* pos 23:9 */; echo ': '; -echo Tracy\Helpers::escapeHtml($exception->getMessage()) /* pos 22:19 */; -echo Tracy\Helpers::escapeHtml($code) /* pos 22:45 */; +echo Tracy\Helpers::escapeHtml($exception->getMessage()) /* pos 23:19 */; +echo Tracy\Helpers::escapeHtml($code) /* pos 23:45 */; echo ' '; -if (count($chain) > 1) /* pos 24:2 */ { +if (count($chain) > 1) /* pos 25:2 */ { echo ' @@ -63,21 +64,21 @@ echo ' require __DIR__ . '/content.phtml'; echo ' \'use strict\'; '; -echo str_replace(['