Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).

### Changed

- Full responses now report source context as one `{start, end, code}` block with one `code` array element per line.
It covers the reported line ±3, clamped to the file, with blank lines and whitespace preserved.
- Full responses now report source context as a single `source` string: the source line at the reported line,
trimmed of surrounding whitespace.
- Paths embedded in trace closure function names and anonymous class names are now relative to the application root.

### Added
Expand All @@ -24,7 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
- `ExceptionHandler`, which maps a `Throwable` to a `Problem` document.
- `Mode` with full and minimal modes, detected from
`APP_ENV` and `APP_DEBUG`.
- Full documents with message, origin, source blocks of up to seven lines,
- Full documents with message, origin, source lines,
relative paths, traces, and chained causes.
- Trace frames with truncated frame arguments; `#[\SensitiveParameter]`
values are redacted and `__toString()` is never invoked.
Expand Down
8 changes: 3 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,11 +59,9 @@ Paths are relative to the application directory, which defaults to the Composer
overridden with the second `ExceptionHandler` argument. Paths embedded in PHP closure function names and anonymous
class names are also made relative when they point inside the application directory.

The exception's origin and every frame carry one `source` object shaped as `{start, end, code}`. `start` and `end`
are inclusive file line numbers; `code` is an array with one string per source line. Empty strings represent blank
lines. It covers the reported line ±3, clamped to the file, preserving indentation and whitespace. Unavailable source
is omitted. Traces are capped at 30 frames (`traceLimit`), keeping the frames nearest the throw; a capped trace
is flagged with `traceTruncated`.
The exception's origin and every frame carry one `source` string: the source line at the reported `line`, trimmed
of surrounding whitespace. A blank line is an empty string. Unavailable source is omitted. Traces are capped at
30 frames (`traceLimit`), keeping the frames nearest the throw; a capped trace is flagged with `traceTruncated`.

Frame arguments are included, truncated to depth 5, 50 items, and 500 bytes per string. Objects are reduced to a
class name plus at most 50 public properties, with the remainder reported by the same `"*truncated*": "N more
Expand Down
16 changes: 8 additions & 8 deletions docs/superpowers/plans/2026-09-30-snafu-exception-handler.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,31 +4,31 @@

**Goal:** Build a PHP 8.4 library that turns any uncaught `Throwable` into an RFC 9457 `application/problem+json` document, logs it via PSR-3, and exposes it through a PSR-15 middleware — with full and minimal modes.

**Architecture:** Ten focused units. Value objects in `Snafu\Document\` own the JSON contract; `Snafu\Trace\` holds the plumbing that reads source windows, sanitizes arguments, and assembles frames; `Snafu\Path\PathRelativizer` turns absolute paths into project-relative ones; `Snafu\ExceptionHandler` maps a `Throwable` to a `Problem`; `Snafu\Middleware\ExceptionMiddleware` catches, logs, encodes, and responds. Every unit is independently testable, which the 100% coverage gate requires.
**Architecture:** Ten focused units. Value objects in `Snafu\Document\` own the JSON contract; `Snafu\Trace\` holds the plumbing that reads source lines, sanitizes arguments, and assembles frames; `Snafu\Path\PathRelativizer` turns absolute paths into project-relative ones; `Snafu\ExceptionHandler` maps a `Throwable` to a `Problem`; `Snafu\Middleware\ExceptionMiddleware` catches, logs, encodes, and responds. Every unit is independently testable, which the 100% coverage gate requires.

**Tech Stack:** PHP 8.4, PSR-7 (`psr/http-factory`), PSR-15 (`psr/http-server-middleware`), PSR-3 (`psr/log`), `composer-runtime-api` (`Composer\InstalledVersions`), `codeinc/http-reason-phrase-lookup` (`CodeInc\HttpReasonPhraseLookup\HttpReasonPhraseLookup`), PHPUnit 13.3, Mago for lint/analyze/format, `nyholm/psr7` for PSR-7 test doubles.

**Spec:** `docs/superpowers/specs/2026-09-30-snafu-exception-handler-design.md` — read it alongside this plan; it records why each decision was made.

> **Source-context amendments (2026-10-01, implemented):** The spec requires one `{start, end, code}` source
> block, `code` as an array of source lines, the reported line ±3, and preserved blank lines. This supersedes the
> `SourceLine` list, ±2 window,
> blank-line stripping, and related signatures/tests throughout this original implementation plan. These tasks
> describe the original design; the implementation now follows the amended spec.
> **Source-context amendments (2026-10-01, implemented):** The spec requires `source` as a single string: the
> source line at the reported line, trimmed of surrounding whitespace. This supersedes the `SourceLine`
> list, ±2 window, blank-line stripping, the `{start, end, code}` block, and related signatures/tests throughout
> this original implementation plan. These tasks describe the original design; the implementation now follows the
> amended spec.

## Global Constraints

Copied from the spec; every task implicitly includes them.

- PHP floor is 8.4 (`composer.json` `require.php` is the single source of truth and CI derives the CI version from it). Local dev runs 8.5.11 — never use an 8.5-only API (`array_first`, `|>`, `#[\NoDiscard]`).
- Every class is `final` (mago `enforce-class-finality`).
- Docblock `@api` on: `Mode`, `ExceptionHandler`, `ExceptionMiddleware`, `Http\StatusCodeInterface`, and all six `Document\` DTOs. Docblock `@internal` on every other class (mago `require-api-or-internal`).
- Docblock `@api` on: `Mode`, `ExceptionHandler`, `ExceptionMiddleware`, `Http\StatusCodeInterface`, and all five `Document\` DTOs. Docblock `@internal` on every other class (mago `require-api-or-internal`).
- Every overriding method carries `#[Override]`.
- Full type hints on parameters, returns, and closures. Nullable parameters use explicit `?T` (PHP 8.4 deprecates implicit nullable).
- 100% line coverage is enforced by `composer run test`. No unreachable line may exist in `src/`, because no test can cover it.
- Test classes carry `#[CoversClass(...)]` (`phpunit.xml` sets `requireCoverageMetadata="true"`); test methods use the `test` prefix (verified: PHPUnit 13.3.6 `Util\Test::isTestMethod` still honours it).
- Output is JSON only, media type `application/problem+json`, `type` is always `about:blank`, `title` is the recommended HTTP status phrase from `codeinc/http-reason-phrase-lookup`'s `HttpReasonPhraseLookup::getReasonPhrase()` (RFC 9457 §4.2.1), and `detail` carries the exception identity.
- Source context is one `{start, end, code}` block with one code-array element per line, for the reported line ±3, clamped to the file, preserving blank lines and whitespace, for the origin and every frame.
- Source context is the source line at the reported line, trimmed of surrounding whitespace, for the origin and every frame.
- **There is no vendor detection.** No vendor flag, no vendor-directory config, no special case for third-party paths.
- Document types are `JsonSerializable` DTOs. Bare PHP arrays appear only as *lists*, plus the two places PHP forces them: `jsonSerialize(): array` and `Throwable::getTrace()`'s input.
- Argument truncation limits: depth 5, 50 items, 500-byte strings. Markers: `*depth limit*`, `*redacted*`, `*truncated*`, `... (N more items)`.
Expand Down
Loading
Loading