From b675d2606eb6e378e65304e1e9af0435ef043476 Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Mon, 16 Nov 2026 08:32:49 -0300 Subject: [PATCH 1/2] docs(skills): add the package skill and AI guide; add `README.md` Security and Built with AI sections and Scorecard badge. --- .agents/skills/php-forge-debug-core | 1 + .claude/skills/php-forge-debug-core | 1 + .gitattributes | 24 ++++++++ .github/workflows/build.yml | 2 +- .github/workflows/dependency-check.yml | 2 +- .github/workflows/ecs.yml | 2 +- .github/workflows/mutation.yml | 2 +- .github/workflows/quality.yml | 2 +- .github/workflows/scorecard.yml | 23 +++++++ .github/workflows/security.yml | 2 +- .github/workflows/static.yml | 2 +- .gitignore | 13 ++++ CHANGELOG.md | 2 + README.md | 46 +++++++++++--- composer.json | 3 + docs/agents.md | 61 +++++++++++++++++++ skills/php-forge-debug-core/SKILL.md | 41 +++++++++++++ .../php-forge-debug-core/agents/openai.yaml | 4 ++ src/Capture/CapturePolicy.php | 2 + src/Collector/CollectorCoordinator.php | 4 +- src/Instrumentation/InstrumentationGuard.php | 2 + src/Panel/Asset/AssetBundleRow.php | 3 + src/Panel/Asset/AssetSnapshot.php | 2 + src/Panel/Asset/ViteChunk.php | 3 + src/Panel/Asset/ViteManifest.php | 4 +- src/Panel/Db/DbSnapshot.php | 2 + src/Panel/Db/DbSummary.php | 2 + src/Panel/Db/NPlusOneFinding.php | 2 + src/Panel/Dump/DumpRow.php | 5 +- src/Panel/Dump/DumpSnapshot.php | 2 + src/Panel/Event/EventRow.php | 3 + src/Panel/Log/DumpEntry.php | 3 + src/Panel/Log/DumpNode.php | 1 + src/Panel/Log/LogCounts.php | 3 + src/Panel/Log/LogRow.php | 5 +- src/Panel/Log/LogSnapshot.php | 2 + src/Panel/Mail/MailSnapshot.php | 2 + src/Panel/MemorySample.php | 3 + src/Panel/PanelRenderContext.php | 2 + src/Panel/Profile/ProfileRow.php | 3 + src/Panel/Profile/ProfilingSnapshot.php | 2 + src/Panel/Queue/JobRecord.php | 3 + src/Panel/Queue/QueueSnapshot.php | 2 + src/Panel/Queue/QueueSummary.php | 3 + src/Panel/Request/RequestHero.php | 2 + src/Panel/Request/RequestSection.php | 3 + src/Panel/Request/RequestTab.php | 3 + .../Request/RequestToolbarItemFactory.php | 2 + src/Panel/Request/RequestView.php | 3 + .../Request/Routing/CurrentRouteView.php | 2 + .../Request/Routing/RequestRoutingView.php | 2 + src/Panel/Request/Routing/RouteBadge.php | 2 + src/Panel/Request/Routing/RouteDefinition.php | 2 + .../Request/Routing/RouteInventoryView.php | 2 + src/Panel/Request/Routing/RouteTraceRow.php | 2 + src/Panel/Request/ServerVariableGroup.php | 2 + src/Panel/Router/ActionRouteRow.php | 3 + src/Panel/Router/CurrentRouteLogRow.php | 3 + src/Panel/Router/RouterRuleRow.php | 3 + src/Panel/Router/RouterSnapshot.php | 2 + src/Panel/Timeline/TimelineSpanRow.php | 3 + src/Panel/User/UserAttribute.php | 5 +- src/Panel/User/UserIdentityHero.php | 3 + src/Panel/User/UserIdentitySection.php | 3 + src/Panel/User/UserIdentityView.php | 3 + src/Panel/User/UserRbacRow.php | 2 + src/PhpInfo/PhpInfoCompactModule.php | 3 + src/PhpInfo/PhpInfoSection.php | 3 + src/PhpInfo/PhpInfoTile.php | 3 + src/PhpInfo/PhpInfoTocEntry.php | 3 + src/PhpInfo/PhpInfoToken.php | 3 + src/PhpInfo/PhpInfoView.php | 3 + src/Registration/PanelOverride.php | 2 + src/Registration/PanelRegistry.php | 6 +- src/Registration/ParsedEntry.php | 2 + src/Storage/DebugSnapshot.php | 2 + src/Storage/ManifestReadResult.php | 2 + src/Storage/PanelFailure.php | 2 + src/Storage/SnapshotReadResult.php | 2 + src/Storage/SnapshotWriteResult.php | 2 + src/View/Grid/SortHeader.php | 2 + src/View/History/HistoryRow.php | 3 + src/View/History/HistoryScale.php | 3 + src/View/History/HistoryStatusBucket.php | 3 + src/View/History/HistorySummary.php | 3 + src/View/Sidebar/SidebarNavItem.php | 3 + src/View/Sidebar/SidebarNavigation.php | 3 + src/View/Sidebar/SidebarView.php | 3 + 88 files changed, 401 insertions(+), 20 deletions(-) create mode 120000 .agents/skills/php-forge-debug-core create mode 120000 .claude/skills/php-forge-debug-core create mode 100644 .github/workflows/scorecard.yml create mode 100644 docs/agents.md create mode 100644 skills/php-forge-debug-core/SKILL.md create mode 100644 skills/php-forge-debug-core/agents/openai.yaml diff --git a/.agents/skills/php-forge-debug-core b/.agents/skills/php-forge-debug-core new file mode 120000 index 0000000..0677e45 --- /dev/null +++ b/.agents/skills/php-forge-debug-core @@ -0,0 +1 @@ +../../skills/php-forge-debug-core \ No newline at end of file diff --git a/.claude/skills/php-forge-debug-core b/.claude/skills/php-forge-debug-core new file mode 120000 index 0000000..0677e45 --- /dev/null +++ b/.claude/skills/php-forge-debug-core @@ -0,0 +1 @@ +../../skills/php-forge-debug-core \ No newline at end of file diff --git a/.gitattributes b/.gitattributes index cddb187..61170e8 100644 --- a/.gitattributes +++ b/.gitattributes @@ -52,3 +52,27 @@ # Avoid merge conflicts in CHANGELOG # https://about.gitlab.com/2015/02/10/gitlab-reduced-merge-conflicts-by-90-percent-with-changelog-placeholders/ /CHANGELOG.md merge=union + +/.agents export-ignore + +/.claude export-ignore + +/internal export-ignore +/vendor export-ignore +/node_modules export-ignore +/.env export-ignore +/.env.* export-ignore + +/.phpunit.cache export-ignore + +/.phpunit.result.cache export-ignore + +/.stryker-tmp export-ignore + +/.codex export-ignore + +/.config export-ignore + +/reports/mutation export-ignore + +/artifacts export-ignore diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index dc810d8..a740535 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -17,7 +17,7 @@ permissions: jobs: phpunit: - uses: yii2-framework/actions/.github/workflows/phpunit.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1 + uses: php-forge/actions/.github/workflows/phpunit.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 secrets: CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} with: diff --git a/.github/workflows/dependency-check.yml b/.github/workflows/dependency-check.yml index c938637..75d0bc0 100644 --- a/.github/workflows/dependency-check.yml +++ b/.github/workflows/dependency-check.yml @@ -17,4 +17,4 @@ permissions: jobs: composer-require-checker: - uses: yii2-framework/actions/.github/workflows/composer-require-checker.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1 + uses: php-forge/actions/.github/workflows/composer-require-checker.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 diff --git a/.github/workflows/ecs.yml b/.github/workflows/ecs.yml index e4159b4..a2a78fd 100644 --- a/.github/workflows/ecs.yml +++ b/.github/workflows/ecs.yml @@ -17,4 +17,4 @@ permissions: jobs: easy-coding-standard: - uses: yii2-framework/actions/.github/workflows/ecs.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1 + uses: php-forge/actions/.github/workflows/ecs.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 diff --git a/.github/workflows/mutation.yml b/.github/workflows/mutation.yml index 90dabee..e530829 100644 --- a/.github/workflows/mutation.yml +++ b/.github/workflows/mutation.yml @@ -17,7 +17,7 @@ permissions: jobs: mutation: - uses: yii2-framework/actions/.github/workflows/infection.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1 + uses: php-forge/actions/.github/workflows/infection.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 with: command-options: --threads=4 --ignore-msi-with-no-mutations phpstan: true diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml index 613b0ca..1b5236f 100644 --- a/.github/workflows/quality.yml +++ b/.github/workflows/quality.yml @@ -10,7 +10,7 @@ permissions: jobs: quality: - uses: yii2-framework/actions/.github/workflows/quality.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1 + uses: php-forge/actions/.github/workflows/quality.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 permissions: contents: read with: diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml new file mode 100644 index 0000000..0640a44 --- /dev/null +++ b/.github/workflows/scorecard.yml @@ -0,0 +1,23 @@ +--- +on: + branch_protection_rule: + push: + branches: + - main + schedule: + - cron: "30 1 * * 6" + +name: scorecard + +permissions: + contents: read + +jobs: + scorecard: + uses: php-forge/actions/.github/workflows/scorecard.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 + permissions: + contents: read # Required to check out the repository. + id-token: write # Required to sign published results with the GitHub OIDC token. + security-events: write # Required to upload SARIF results to code scanning. + with: + publish-results: true diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index 6a771ba..29b8119 100644 --- a/.github/workflows/security.yml +++ b/.github/workflows/security.yml @@ -10,7 +10,7 @@ permissions: jobs: security: - uses: yii2-framework/actions/.github/workflows/security.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1 + uses: php-forge/actions/.github/workflows/security.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 permissions: contents: read with: diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml index 108f5a6..455657f 100644 --- a/.github/workflows/static.yml +++ b/.github/workflows/static.yml @@ -17,4 +17,4 @@ permissions: jobs: phpstan: - uses: yii2-framework/actions/.github/workflows/phpstan.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1 + uses: php-forge/actions/.github/workflows/phpstan.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 diff --git a/.gitignore b/.gitignore index b1939a5..73a398c 100644 --- a/.gitignore +++ b/.gitignore @@ -48,3 +48,16 @@ vendor # windows thumbnail cache (if present) Thumbs.db + +# Package skill discovery; keep other local client state private. +!/.agents/ +/.agents/* +!/.agents/skills/ +/.agents/skills/* +!/.agents/skills/php-forge-debug-core +!/.claude/ +/.claude/* +!/.claude/skills/ +/.claude/skills/* +!/.claude/skills/php-forge-debug-core +/internal/ diff --git a/CHANGELOG.md b/CHANGELOG.md index e14acef..530a94a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## 0.1.3 Under development +- docs(skills): add the package skill and AI guide; add `README.md` Security and Built with AI sections and Scorecard badge. + ## 0.1.2 November 6, 2026 - feat(log): render multi-line log messages with preserved whitespace, `print_r()` dumps as a tree, and `var_export()` values highlighted. diff --git a/README.md b/README.md index d782a1e..f0a8feb 100644 --- a/README.md +++ b/README.md @@ -12,15 +12,15 @@ PHPUnit + + Coverage + Mutation Testing PHPStan - - Security -

@@ -30,8 +30,8 @@ ## Features - - Feature overview + + Feature overview ## Installation @@ -92,6 +92,28 @@ npm run check:icons `check:icons` compares the toolbar's inline glyphs with `resources/assets/svg`; the toolbar-only chrome glyphs (`chevron-left`, `chevron-right`, `close`, `external-link`) have no panel file by design and never fail `--strict`. +## Documentation + +This package has no separate guides; its documentation topics live in this README and the source PHPDoc. + +- 📦 [Installation](#installation) +- 🧩 [Adapter boundary](#adapter-boundary) +- 🎨 [Frontend development](#frontend-development) + +## AI assistance + +AI agents: read the [documentation index](https://yii2-framework.github.io/docs/llms.txt) and fetch the Markdown version +of a page by appending `index.md` to its URL. The +[AI agents guide](https://github.com/yii2-framework/docs/blob/main/src/content/docs/project/ai-agents.md) covers skill +installation, client setup and verification. + +- 🤖 [`php-forge-debug-core` skill](https://github.com/php-forge/debug-core/blob/main/docs/agents.md): building a + debugger adapter on the core, with snapshot storage and read diagnostics, log context redaction, the routing + contract and the toolbar frontend sources. + +See the [repository guides](#documentation), the [skill source](skills/php-forge-debug-core/SKILL.md), the source PHPDoc +and the [changelog](CHANGELOG.md). + ## Package information [![PHP](https://img.shields.io/badge/%3E%3D8.3-777BB4.svg?style=for-the-badge&logo=php&logoColor=white)](https://www.php.net/releases/8.3/en.php) @@ -101,10 +123,20 @@ npm run check:icons ## Code quality -[![Codecov](https://img.shields.io/codecov/c/github/php-forge/debug-core.svg?style=for-the-badge&logo=codecov&logoColor=white&label=Coverage)](https://codecov.io/gh/php-forge/debug-core) [![Quality](https://img.shields.io/github/actions/workflow/status/php-forge/debug-core/quality.yml?style=for-the-badge&label=Quality&logo=github)](https://github.com/php-forge/debug-core/actions/workflows/quality.yml) [![Assets](https://img.shields.io/github/actions/workflow/status/php-forge/debug-core/assets.yml?style=for-the-badge&label=Assets&logo=github)](https://github.com/php-forge/debug-core/actions/workflows/assets.yml) -[![StyleCI](https://img.shields.io/badge/StyleCI-Passed-44CC11.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.styleci.io/repos/php-forge/debug-core?branch=main) +[![StyleCI](https://img.shields.io/badge/dynamic/xml?url=https%3A%2F%2Fgithub.styleci.io%2Frepos%2F1334500828%2Fshield%3Fbranch%3Dmain&query=%2F%2F*%5Blocal-name%28%29%3D%27text%27%5D%5B2%5D&label=StyleCI&style=for-the-badge&logo=github&logoColor=white&color=4F5D95)](https://github.styleci.io/repos/1334500828?branch=main) + +## Security + +[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/php-forge/debug-core/badge?style=for-the-badge)](https://scorecard.dev/viewer/?uri=github.com/php-forge/debug-core) +[![Zizmor](https://img.shields.io/github/actions/workflow/status/php-forge/debug-core/security.yml?style=for-the-badge&label=Zizmor&logo=github)](https://github.com/php-forge/debug-core/actions/workflows/security.yml) + +## Built with AI + +[![Built with Claude Code](https://img.shields.io/badge/Built%20with-Claude%20Code-D97757.svg?style=for-the-badge&logo=claude&logoColor=white)](https://claude.com/claude-code) +[![Built with Codex](https://img.shields.io/badge/Built%20with-Codex-10A37F.svg?style=for-the-badge&logo=openaigym&logoColor=white)](https://openai.com/codex) +[![Reviewed by CodeRabbit](https://img.shields.io/badge/Reviewed%20by-CodeRabbit-FF570A.svg?style=for-the-badge&logo=coderabbit&logoColor=white)](https://www.coderabbit.ai) ## Social networks diff --git a/composer.json b/composer.json index e5db0d4..459a7ba 100644 --- a/composer.json +++ b/composer.json @@ -55,6 +55,9 @@ "extra": { "branch-alias": { "dev-main": "0.2.x-dev" + }, + "skills": { + "source": "skills" } }, "config": { diff --git a/docs/agents.md b/docs/agents.md new file mode 100644 index 0000000..4c76d7a --- /dev/null +++ b/docs/agents.md @@ -0,0 +1,61 @@ +# AI assistance + +Use the package-owned [php-forge-debug-core](../skills/php-forge-debug-core/SKILL.md) skill for integrating PHP Forge debugger snapshots, storage and adapter boundaries. The canonical source is `skills/`; checkout discovery links in `.agents/skills/` and `.claude/skills/` point to that same source. + +## Install in an application + +### Automatic Composer installation + +Composer is the primary distribution path. `extra.skills.source` declares the bundle; installing the package alone does +not register its skill at the application root. In a consumer already configured for `llm/skills`, explicitly trust +`php-forge/debug-core` and use that installed synchronizer's documented setup. Do not enable plugins or broaden trust by +copying an example. + +```bash +composer install +composer skills:show +``` + +With verified auto-sync enabled, installation/update can synchronize the bundle; otherwise run +`composer skills:update` and inspect `composer skills:show`. Composer exit zero is not proof of client activation. + +### Optional npx installation + +An optional pinned installer can use a local checkout or an installed package that contains the bundle: + +```bash +npx skills@1.7.2 add /absolute/path/to/debug-core --list +npx skills@1.7.2 add /absolute/path/to/debug-core --skill php-forge-debug-core --agent claude-code codex opencode +``` + +Keep project scope. Inspect a remote source with `--list` before claiming an unpublished skill is available there. +Copied installations must be refreshed after upgrades. The complete skill directory is the unit of installation. + +## Discover and invoke + +Open a fresh client session at the checkout or consumer root. Codex discovers `.agents/skills/php-forge-debug-core/` and supports +`$php-forge-debug-core` or its skill picker. Claude Code uses `.claude/skills/php-forge-debug-core/` and `/php-forge-debug-core`. For OpenCode, verify the +installed client's native skill tool and shared paths. Do not assume one client's invocation syntax works in another. + +## Example prompts + +Explicit Codex invocation: + +```text +$php-forge-debug-core +Outline an adapter using the installed snapshot and routing contracts. Verify missing/corrupt snapshot handling and request isolation without changing production routes or exposing diagnostics. +``` + +For natural selection, repeat the task without the first line. Record whether the client loads this skill rather than +a global same-named copy. As an unrelated negative control, ask it to explain HTTP 301 versus 302 without inspecting the +repository or loading package skills. + +## Verify the result + +Capture the native load/tool evidence and selected source path, then execute the generated task checks against the +installed package. Cover the normal operation, the described boundary case and a failure/unsupported input. Inspect +generated code before executing it; use disposable fixtures for writes. Run the package's actual non-mutating checks +and report runtime versions, warnings and unavailable dependencies. Listing, manually reading the skill, or supplying +its body in a prompt does not prove native activation or functional execution. + +[Back to README](../README.md) diff --git a/skills/php-forge-debug-core/SKILL.md b/skills/php-forge-debug-core/SKILL.md new file mode 100644 index 0000000..c05a898 --- /dev/null +++ b/skills/php-forge-debug-core/SKILL.md @@ -0,0 +1,41 @@ +--- +name: php-forge-debug-core +description: Use when building or maintaining a debugger adapter on php-forge/debug-core, covering snapshot storage, capture redaction, panel URL generation, toolbar injection and the shared frontend sources. Not for installing the debugger in an application, which goes through yii2-extensions/debug or yii3/debug, nor for framework routes, access policy or asset publishing. +license: BSD-3-Clause +--- + +# Use php-forge/debug-core + +## Resolve the package + +Inspect the installed package path, actual source and Composer metadata before choosing APIs. The current PHP constraint +is `>=8.3`. A lockfile or branch alias alone does not prove the installed files match it. Use +local guides at that revision; if a guide is excluded from the archive, consult the matching repository revision, not +unverified current documentation. Installing this skill does not install dependencies or authorize mutations. + +## Package contracts + +Applications normally install a framework adapter; this package owns common storage, snapshots, renderers and +frontend resources. Adapters own routing, access policy, assets and the decision to inject the toolbar. Collectors +implement `PHPForge\Debug\CollectorInterface` from `php-forge/debug`. Implement +`PHPForge\Debug\Routing\DebugUrlGeneratorInterface` rather than importing a framework URL manager into the core. + +These behaviors are intended; do not "fix" them as incidental cleanups: + +- `Storage\SnapshotStore::readSnapshot()` returns `null` for a missing, corrupt or invalid-tag snapshot and hides the + cause. Use `readSnapshotResult()` when the diagnostic matters: a missing snapshot yields no snapshot and no error, + while a corrupt file or an invalid tag yields a `StorageException` in `error`. +- `Panel\Log\LogContext::normalize()` applies the host `Capture\CapturePolicy` to the PSR-3 context only. The core + does not redact the log message text; do not add redaction there. +- `Toolbar\ToolbarInjector::inject()` inserts the markup before the last case-insensitive `` found by string + search, not by parsing HTML, and appends it when there is none. + +Keep the debugger limited to local/development use. Test corrupt or missing snapshots, request isolation and response +injection separately. PHP storage tests do not prove browser toolbar behavior; frontend source is under +`resources/src`, with generated output under `resources/assets/dist`. + +## Verify the task + +Run the relevant existing package checks and independent assertions for the selected operation. Read `composer.json` +scripts before executing them: fixers, installers and cleanup commands can mutate files. Use isolated synthetic inputs +for side-effecting behavior. Report the PHP version and missing dependencies. diff --git a/skills/php-forge-debug-core/agents/openai.yaml b/skills/php-forge-debug-core/agents/openai.yaml new file mode 100644 index 0000000..e8e2f83 --- /dev/null +++ b/skills/php-forge-debug-core/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "PHP Forge Debug Core" + short_description: "Build debugger adapters on the shared debug core" + default_prompt: "Use $php-forge-debug-core to build or review a debugger adapter on the shared snapshot, storage and toolbar contracts." diff --git a/src/Capture/CapturePolicy.php b/src/Capture/CapturePolicy.php index b6760b5..967b551 100644 --- a/src/Capture/CapturePolicy.php +++ b/src/Capture/CapturePolicy.php @@ -43,6 +43,8 @@ private array $sensitiveKeyPatterns; /** + * Creates a capture policy with redaction and size limits. + * * @param list $sensitiveKeys Exact, case-insensitive keys to redact recursively. * @param int $maxBodyBytes Maximum raw request or response body bytes to retain; must be positive. * @param list $sensitiveKeyPrefixes Literal, case-insensitive key prefixes to redact recursively. diff --git a/src/Collector/CollectorCoordinator.php b/src/Collector/CollectorCoordinator.php index 786bd4c..ee89357 100644 --- a/src/Collector/CollectorCoordinator.php +++ b/src/Collector/CollectorCoordinator.php @@ -103,7 +103,9 @@ public function collector(string $id): CollectorInterface|null } /** - * @return array Registered collectors for host-local instrumentation hooks. + * Returns the collectors registered for host-local instrumentation hooks. + * + * @return array Registered collectors indexed by ID. */ public function collectors(): array { diff --git a/src/Instrumentation/InstrumentationGuard.php b/src/Instrumentation/InstrumentationGuard.php index fe6c6c2..fd3661b 100644 --- a/src/Instrumentation/InstrumentationGuard.php +++ b/src/Instrumentation/InstrumentationGuard.php @@ -18,6 +18,8 @@ private Closure|null $failureHandler; /** + * Creates a guard around an optional diagnostic failure observer. + * * @param (callable(Throwable): void)|null $failureHandler Optional observer for suppressed instrumentation errors. */ public function __construct(callable|null $failureHandler = null) diff --git a/src/Panel/Asset/AssetBundleRow.php b/src/Panel/Asset/AssetBundleRow.php index 883c75b..3e1ba64 100644 --- a/src/Panel/Asset/AssetBundleRow.php +++ b/src/Panel/Asset/AssetBundleRow.php @@ -16,6 +16,9 @@ */ final readonly class AssetBundleRow implements PanelRow { + /** + * Creates an asset-bundle row from its captured metadata. + */ public function __construct( /** * Bundle class name as registered on the asset manager. diff --git a/src/Panel/Asset/AssetSnapshot.php b/src/Panel/Asset/AssetSnapshot.php index ab955ca..cb73452 100644 --- a/src/Panel/Asset/AssetSnapshot.php +++ b/src/Panel/Asset/AssetSnapshot.php @@ -14,6 +14,8 @@ final readonly class AssetSnapshot implements PanelSnapshot { /** + * Creates an asset snapshot from bundles and an optional Vite manifest. + * * @param list $bundles */ public function __construct( diff --git a/src/Panel/Asset/ViteChunk.php b/src/Panel/Asset/ViteChunk.php index f4de776..caf6cd0 100644 --- a/src/Panel/Asset/ViteChunk.php +++ b/src/Panel/Asset/ViteChunk.php @@ -11,6 +11,9 @@ */ final readonly class ViteChunk implements PanelRow { + /** + * Creates a Vite manifest entry with its built file and asset counts. + */ public function __construct( /** * Chunk name as keyed in the manifest. diff --git a/src/Panel/Asset/ViteManifest.php b/src/Panel/Asset/ViteManifest.php index 767c287..cb40341 100644 --- a/src/Panel/Asset/ViteManifest.php +++ b/src/Panel/Asset/ViteManifest.php @@ -14,7 +14,9 @@ final readonly class ViteManifest { /** - * @param list $chunks + * Creates a Vite snapshot from bridge settings and build chunks. + * + * @param list $chunks Build chunks in the manifest. */ public function __construct( /** diff --git a/src/Panel/Db/DbSnapshot.php b/src/Panel/Db/DbSnapshot.php index 93f7c5b..c44567c 100644 --- a/src/Panel/Db/DbSnapshot.php +++ b/src/Panel/Db/DbSnapshot.php @@ -15,6 +15,8 @@ final readonly class DbSnapshot implements PanelSnapshot { /** + * Creates a database snapshot from captured query rows. + * * @param list $entries */ public function __construct(private array $entries) {} diff --git a/src/Panel/Db/DbSummary.php b/src/Panel/Db/DbSummary.php index bb65f4d..34ec745 100644 --- a/src/Panel/Db/DbSummary.php +++ b/src/Panel/Db/DbSummary.php @@ -37,6 +37,8 @@ public array $types; /** + * Creates request-wide database metrics. + * * @param list $rows Captured query rows the metrics are computed from. */ public function __construct(array $rows) diff --git a/src/Panel/Db/NPlusOneFinding.php b/src/Panel/Db/NPlusOneFinding.php index 8cfb655..2e86cea 100644 --- a/src/Panel/Db/NPlusOneFinding.php +++ b/src/Panel/Db/NPlusOneFinding.php @@ -10,6 +10,8 @@ final readonly class NPlusOneFinding { /** + * Creates a potential N+1 query finding. + * * @param non-empty-string $fingerprint Stable backtrace fingerprint. * @param positive-int $count Number of observed query occurrences. * @param float $totalDuration Total group duration in milliseconds. diff --git a/src/Panel/Dump/DumpRow.php b/src/Panel/Dump/DumpRow.php index 9ec8552..1a5ae2b 100644 --- a/src/Panel/Dump/DumpRow.php +++ b/src/Panel/Dump/DumpRow.php @@ -13,13 +13,16 @@ */ final readonly class DumpRow implements PanelRow { + /** + * Creates a dump row from its captured log data. + */ public function __construct( /** * Highlighted dump payload as produced by the Dump collector `varDump()` pipeline. */ public string $message, /** - * Logger level constant ({@see \\PHPForge\\Debug\\Helper\\LogLevel}). + * Logger level constant ({@see \PHPForge\Debug\Helper\LogLevel}). */ public int $level, /** diff --git a/src/Panel/Dump/DumpSnapshot.php b/src/Panel/Dump/DumpSnapshot.php index 0cb73e3..03b2ac9 100644 --- a/src/Panel/Dump/DumpSnapshot.php +++ b/src/Panel/Dump/DumpSnapshot.php @@ -16,6 +16,8 @@ final readonly class DumpSnapshot implements PanelSnapshot { /** + * Creates a dump snapshot from captured rows. + * * @param list $entries */ public function __construct(private array $entries) {} diff --git a/src/Panel/Event/EventRow.php b/src/Panel/Event/EventRow.php index b2707a8..3d0b8a0 100644 --- a/src/Panel/Event/EventRow.php +++ b/src/Panel/Event/EventRow.php @@ -19,6 +19,9 @@ final class EventRow implements PanelRow */ private EventInspection|null $inspection = null; + /** + * Creates an event row from captured listener data. + */ public function __construct( /** * Capture timestamp in seconds since the Unix epoch. diff --git a/src/Panel/Log/DumpEntry.php b/src/Panel/Log/DumpEntry.php index d2f3e26..69be5ca 100644 --- a/src/Panel/Log/DumpEntry.php +++ b/src/Panel/Log/DumpEntry.php @@ -12,7 +12,10 @@ final readonly class DumpEntry { /** + * Creates a dump-tree entry with its key, value, and visibility. + * * @param string $key Array key or property name. + * @param DumpNode $value Value associated with the key. * @param string $visibility `protected`, `private`, or `''` for a public property or an array key. * @param string $declaringClass Class declaring a private property; `''` otherwise. */ diff --git a/src/Panel/Log/DumpNode.php b/src/Panel/Log/DumpNode.php index 70a4852..6413cfe 100644 --- a/src/Panel/Log/DumpNode.php +++ b/src/Panel/Log/DumpNode.php @@ -21,6 +21,7 @@ final readonly class DumpNode { /** + * @param DumpKind $kind Kind of value represented by the node. * @param string $label Class name of an object, enum, or recursive object; `''` otherwise. * @param string $text Scalar text, enum case name, or free text preceding a root block header. * @param list $entries Block entries. diff --git a/src/Panel/Log/LogCounts.php b/src/Panel/Log/LogCounts.php index f0bf14b..4bddf05 100644 --- a/src/Panel/Log/LogCounts.php +++ b/src/Panel/Log/LogCounts.php @@ -13,6 +13,9 @@ */ final readonly class LogCounts { + /** + * Creates the log-level totals for the detail view. + */ public function __construct( /** * Total number of log messages captured for the request. diff --git a/src/Panel/Log/LogRow.php b/src/Panel/Log/LogRow.php index c334843..cab2247 100644 --- a/src/Panel/Log/LogRow.php +++ b/src/Panel/Log/LogRow.php @@ -16,6 +16,9 @@ */ final readonly class LogRow implements PanelRow { + /** + * Creates a log row from its captured logger data. + */ public function __construct( /** * One-based row id assigned in capture order. @@ -26,7 +29,7 @@ public function __construct( */ public string $message, /** - * Logger level constant ({@see \\PHPForge\\Debug\\Helper\\LogLevel}). + * Logger level constant ({@see \PHPForge\Debug\Helper\LogLevel}). */ public int $level, /** diff --git a/src/Panel/Log/LogSnapshot.php b/src/Panel/Log/LogSnapshot.php index 5d0178b..2c2613e 100644 --- a/src/Panel/Log/LogSnapshot.php +++ b/src/Panel/Log/LogSnapshot.php @@ -26,6 +26,8 @@ final readonly class LogSnapshot implements PanelSnapshot { /** + * Creates a log snapshot from captured rows. + * * @param list $entries */ public function __construct(private array $entries) {} diff --git a/src/Panel/Mail/MailSnapshot.php b/src/Panel/Mail/MailSnapshot.php index 8b3863e..6583325 100644 --- a/src/Panel/Mail/MailSnapshot.php +++ b/src/Panel/Mail/MailSnapshot.php @@ -15,6 +15,8 @@ final readonly class MailSnapshot implements PanelSnapshot { /** + * Creates a mail snapshot from captured messages. + * * @param list $entries Captured messages in send order. */ public function __construct(private array $entries) {} diff --git a/src/Panel/MemorySample.php b/src/Panel/MemorySample.php index a3d81e9..e76068c 100644 --- a/src/Panel/MemorySample.php +++ b/src/Panel/MemorySample.php @@ -9,6 +9,9 @@ */ final readonly class MemorySample { + /** + * Creates a timestamped memory sample. + */ public function __construct( /** * Sample timestamp in milliseconds since the Unix epoch. diff --git a/src/Panel/PanelRenderContext.php b/src/Panel/PanelRenderContext.php index 0b71ace..dfe14ec 100644 --- a/src/Panel/PanelRenderContext.php +++ b/src/Panel/PanelRenderContext.php @@ -12,6 +12,8 @@ final readonly class PanelRenderContext { /** + * Creates the request, theme, and URL context for a panel renderer. + * * @param string $tag Captured request tag. * @param string $panel Stable identifier of the panel being rendered. * @param array $queryParams Parsed query parameters of the current debugger request. diff --git a/src/Panel/Profile/ProfileRow.php b/src/Panel/Profile/ProfileRow.php index 28f5a7e..415268d 100644 --- a/src/Panel/Profile/ProfileRow.php +++ b/src/Panel/Profile/ProfileRow.php @@ -15,6 +15,9 @@ */ final readonly class ProfileRow implements PanelRow { + /** + * Creates a profile row from captured timing data. + */ public function __construct( /** * Capture timestamp in milliseconds since the Unix epoch. diff --git a/src/Panel/Profile/ProfilingSnapshot.php b/src/Panel/Profile/ProfilingSnapshot.php index 387b8d0..f8e962f 100644 --- a/src/Panel/Profile/ProfilingSnapshot.php +++ b/src/Panel/Profile/ProfilingSnapshot.php @@ -23,6 +23,8 @@ final readonly class ProfilingSnapshot implements PanelSnapshot { /** + * Creates a profiling snapshot from request metrics, blocks, and memory samples. + * * @param list $entries * @param list $samples */ diff --git a/src/Panel/Queue/JobRecord.php b/src/Panel/Queue/JobRecord.php index 33d1e01..18af773 100644 --- a/src/Panel/Queue/JobRecord.php +++ b/src/Panel/Queue/JobRecord.php @@ -44,6 +44,9 @@ */ public const string TYPE_PUSH = 'push'; + /** + * Creates a queue lifecycle event record. + */ public function __construct( /** * Lifecycle phase: `'push'` (job enqueued), `'exec'` (job finished successfully) or `'error'` (job threw). diff --git a/src/Panel/Queue/QueueSnapshot.php b/src/Panel/Queue/QueueSnapshot.php index 0145b56..7a3611c 100644 --- a/src/Panel/Queue/QueueSnapshot.php +++ b/src/Panel/Queue/QueueSnapshot.php @@ -15,6 +15,8 @@ final readonly class QueueSnapshot implements PanelSnapshot { /** + * Creates a queue snapshot from captured job events. + * * @param list $entries */ public function __construct(private array $entries) {} diff --git a/src/Panel/Queue/QueueSummary.php b/src/Panel/Queue/QueueSummary.php index f46e05e..3ab04a4 100644 --- a/src/Panel/Queue/QueueSummary.php +++ b/src/Panel/Queue/QueueSummary.php @@ -13,6 +13,9 @@ */ final readonly class QueueSummary { + /** + * Creates a Queue panel summary from captured events. + */ public function __construct( /** * @var list Captured events in chronological order. diff --git a/src/Panel/Request/RequestHero.php b/src/Panel/Request/RequestHero.php index f4b8b6c..96547aa 100644 --- a/src/Panel/Request/RequestHero.php +++ b/src/Panel/Request/RequestHero.php @@ -37,6 +37,8 @@ final class RequestHero private string $time = ''; /** + * Creates a request identity ready for response and display metadata. + * * @param string $method HTTP method of the request. * @param string $url Full URL of the request. */ diff --git a/src/Panel/Request/RequestSection.php b/src/Panel/Request/RequestSection.php index 34310b0..4808dd8 100644 --- a/src/Panel/Request/RequestSection.php +++ b/src/Panel/Request/RequestSection.php @@ -9,6 +9,9 @@ */ final readonly class RequestSection { + /** + * Creates a name/value section for the Request panel. + */ public function __construct( /** * Section heading shown at the top of the rendered table. diff --git a/src/Panel/Request/RequestTab.php b/src/Panel/Request/RequestTab.php index 570e670..bc8a2a9 100644 --- a/src/Panel/Request/RequestTab.php +++ b/src/Panel/Request/RequestTab.php @@ -9,6 +9,9 @@ */ final readonly class RequestTab { + /** + * Creates a tab for the Request panel. + */ public function __construct( /** * Navigation label shown in the tab strip (`'Parameters'`, `'Headers'`, `'Session'`, `'Server'`). diff --git a/src/Panel/Request/RequestToolbarItemFactory.php b/src/Panel/Request/RequestToolbarItemFactory.php index e6b4ff5..095b0d8 100644 --- a/src/Panel/Request/RequestToolbarItemFactory.php +++ b/src/Panel/Request/RequestToolbarItemFactory.php @@ -15,6 +15,8 @@ final class RequestToolbarItemFactory { /** + * Builds request toolbar items for the route and response status. + * * @return list Request toolbar metrics. */ public static function create(string $route, int $statusCode, string $statusText = ''): array diff --git a/src/Panel/Request/RequestView.php b/src/Panel/Request/RequestView.php index 1a5426a..ff611c7 100644 --- a/src/Panel/Request/RequestView.php +++ b/src/Panel/Request/RequestView.php @@ -9,6 +9,9 @@ */ final readonly class RequestView { + /** + * Creates the composed Request panel view. + */ public function __construct( /** * Hero header view-model. diff --git a/src/Panel/Request/Routing/CurrentRouteView.php b/src/Panel/Request/Routing/CurrentRouteView.php index 09aad04..e318470 100644 --- a/src/Panel/Request/Routing/CurrentRouteView.php +++ b/src/Panel/Request/Routing/CurrentRouteView.php @@ -44,6 +44,8 @@ final class CurrentRouteView private array $trace = []; /** + * Creates current-route diagnostics for the supplied route. + * * @param string $route Route the request resolved to, as the application declares it. */ public function __construct( diff --git a/src/Panel/Request/Routing/RequestRoutingView.php b/src/Panel/Request/Routing/RequestRoutingView.php index 3e26fb1..746148b 100644 --- a/src/Panel/Request/Routing/RequestRoutingView.php +++ b/src/Panel/Request/Routing/RequestRoutingView.php @@ -10,6 +10,8 @@ final readonly class RequestRoutingView { /** + * Creates routing diagnostics for the Request panel. + * * @param CurrentRouteView $current Current route view. * @param RouteInventoryView|null $inventory Route inventory view, or null if not available. */ diff --git a/src/Panel/Request/Routing/RouteBadge.php b/src/Panel/Request/Routing/RouteBadge.php index 2e96486..69edc4d 100644 --- a/src/Panel/Request/Routing/RouteBadge.php +++ b/src/Panel/Request/Routing/RouteBadge.php @@ -10,6 +10,8 @@ final readonly class RouteBadge { /** + * Creates a routing configuration badge. + * * @param string $label Badge label. * @param string $variant Badge variant, defaults to 'muted'. */ diff --git a/src/Panel/Request/Routing/RouteDefinition.php b/src/Panel/Request/Routing/RouteDefinition.php index 3a8e8c4..7719dbe 100644 --- a/src/Panel/Request/Routing/RouteDefinition.php +++ b/src/Panel/Request/Routing/RouteDefinition.php @@ -63,6 +63,8 @@ final class RouteDefinition private string|null $type = null; /** + * Creates persistence-safe route metadata. + * * @param string $name Route name as the application declares it. * @param string $pattern URL pattern the route matches. */ diff --git a/src/Panel/Request/Routing/RouteInventoryView.php b/src/Panel/Request/Routing/RouteInventoryView.php index 09733da..4d9d2c9 100644 --- a/src/Panel/Request/Routing/RouteInventoryView.php +++ b/src/Panel/Request/Routing/RouteInventoryView.php @@ -29,6 +29,8 @@ final class RouteInventoryView private string $source = 'Current application configuration'; /** + * Creates a route inventory with its provenance. + * * @param list $routes Route definitions the application declares. */ public function __construct( diff --git a/src/Panel/Request/Routing/RouteTraceRow.php b/src/Panel/Request/Routing/RouteTraceRow.php index 66d9107..ddbbefa 100644 --- a/src/Panel/Request/Routing/RouteTraceRow.php +++ b/src/Panel/Request/Routing/RouteTraceRow.php @@ -10,6 +10,8 @@ final readonly class RouteTraceRow { /** + * Creates a row for an inspected routing rule. + * * @param string $rule Routing rule inspected. * @param string $parent Parent rule, if any. * @param bool $matched Whether this rule matched the current request. diff --git a/src/Panel/Request/ServerVariableGroup.php b/src/Panel/Request/ServerVariableGroup.php index 8c93d43..1c11b73 100644 --- a/src/Panel/Request/ServerVariableGroup.php +++ b/src/Panel/Request/ServerVariableGroup.php @@ -10,6 +10,8 @@ final readonly class ServerVariableGroup { /** + * Creates a group of captured server variables. + * * @param string $id Identifier for the server variable group. * @param string $label Human-readable label for the server variable group. * @param array $entries Captured server variables within the group. diff --git a/src/Panel/Router/ActionRouteRow.php b/src/Panel/Router/ActionRouteRow.php index 7000cdf..860ac75 100644 --- a/src/Panel/Router/ActionRouteRow.php +++ b/src/Panel/Router/ActionRouteRow.php @@ -11,6 +11,9 @@ */ final readonly class ActionRouteRow { + /** + * Creates an Action Routes table row. + */ public function __construct( /** * Action FQCN used as the table key (for example, `app\controllers\SiteController::actionIndex`). diff --git a/src/Panel/Router/CurrentRouteLogRow.php b/src/Panel/Router/CurrentRouteLogRow.php index 5ab33fb..724c0fb 100644 --- a/src/Panel/Router/CurrentRouteLogRow.php +++ b/src/Panel/Router/CurrentRouteLogRow.php @@ -16,6 +16,9 @@ */ final readonly class CurrentRouteLogRow implements PanelRow { + /** + * Creates a row from the current-route rules-tested log. + */ public function __construct( /** * Rule name or its class FQCN as captured by the route resolver. diff --git a/src/Panel/Router/RouterRuleRow.php b/src/Panel/Router/RouterRuleRow.php index 9438bcf..23a3d8b 100644 --- a/src/Panel/Router/RouterRuleRow.php +++ b/src/Panel/Router/RouterRuleRow.php @@ -15,6 +15,9 @@ */ final readonly class RouterRuleRow { + /** + * Creates a Router Rules table row. + */ public function __construct( /** * Rule name or its class FQCN. diff --git a/src/Panel/Router/RouterSnapshot.php b/src/Panel/Router/RouterSnapshot.php index 3ec5083..e755f03 100644 --- a/src/Panel/Router/RouterSnapshot.php +++ b/src/Panel/Router/RouterSnapshot.php @@ -16,6 +16,8 @@ final readonly class RouterSnapshot implements PanelSnapshot { /** + * Creates a routing snapshot from the captured rule trace. + * * @param list $entries */ public function __construct( diff --git a/src/Panel/Timeline/TimelineSpanRow.php b/src/Panel/Timeline/TimelineSpanRow.php index 12e2ed1..19612d9 100644 --- a/src/Panel/Timeline/TimelineSpanRow.php +++ b/src/Panel/Timeline/TimelineSpanRow.php @@ -17,6 +17,9 @@ */ final readonly class TimelineSpanRow { + /** + * Creates a span row for the Timeline chart. + */ public function __construct( /** * Span category ({@see \yii\db\Command::query}, {@see \yii\base\Application::handleRequest}, ...), or `''` diff --git a/src/Panel/User/UserAttribute.php b/src/Panel/User/UserAttribute.php index c4585e6..a49adf1 100644 --- a/src/Panel/User/UserAttribute.php +++ b/src/Panel/User/UserAttribute.php @@ -26,6 +26,9 @@ */ public const string KIND_TIMESTAMP = 'timestamp'; + /** + * Creates a user-identity attribute row. + */ public function __construct( /** * Raw attribute key (for example, `username`, `created_at`, `auth_key`). @@ -37,7 +40,7 @@ public function __construct( */ public string $label, /** - * Display string with surrounding {@see \\PHPForge\\Debug\\Helper\\Dump} quotes already stripped, or `''` when the raw + * Display string with surrounding {@see \PHPForge\Debug\Helper\Dump} quotes already stripped, or `''` when the raw * value was `null` or empty. */ public string $displayValue, diff --git a/src/Panel/User/UserIdentityHero.php b/src/Panel/User/UserIdentityHero.php index 5d86db0..2ae0186 100644 --- a/src/Panel/User/UserIdentityHero.php +++ b/src/Panel/User/UserIdentityHero.php @@ -9,6 +9,9 @@ */ final readonly class UserIdentityHero { + /** + * Creates the user-identity hero card data. + */ public function __construct( /** * Display username; falls back to `Unknown user` when the identity has no `username` or `name`. diff --git a/src/Panel/User/UserIdentitySection.php b/src/Panel/User/UserIdentitySection.php index f706d3d..56579b5 100644 --- a/src/Panel/User/UserIdentitySection.php +++ b/src/Panel/User/UserIdentitySection.php @@ -9,6 +9,9 @@ */ final readonly class UserIdentitySection { + /** + * Creates a section of user-identity attributes. + */ public function __construct( /** * Section label shown in the section header (`Identity`, `Security`, ...). diff --git a/src/Panel/User/UserIdentityView.php b/src/Panel/User/UserIdentityView.php index 0d379d0..cf38348 100644 --- a/src/Panel/User/UserIdentityView.php +++ b/src/Panel/User/UserIdentityView.php @@ -9,6 +9,9 @@ */ final readonly class UserIdentityView { + /** + * Creates the user-identity card view. + */ public function __construct( /** * Hero card view-model. diff --git a/src/Panel/User/UserRbacRow.php b/src/Panel/User/UserRbacRow.php index acee2db..b3389d3 100644 --- a/src/Panel/User/UserRbacRow.php +++ b/src/Panel/User/UserRbacRow.php @@ -12,6 +12,8 @@ final readonly class UserRbacRow { /** + * Creates a User panel role or permission row. + * * @param string $name Item name, unique within the hierarchy. * @param string $description Human-readable description of the item's purpose. * @param string $ruleName Name of the rule associated with the item, or an empty string when none. diff --git a/src/PhpInfo/PhpInfoCompactModule.php b/src/PhpInfo/PhpInfoCompactModule.php index c784d59..8664e0b 100644 --- a/src/PhpInfo/PhpInfoCompactModule.php +++ b/src/PhpInfo/PhpInfoCompactModule.php @@ -9,6 +9,9 @@ */ final readonly class PhpInfoCompactModule { + /** + * Creates a compact module for the phpinfo overview. + */ public function __construct( /** * Module title reported by {@see phpinfo()}. diff --git a/src/PhpInfo/PhpInfoSection.php b/src/PhpInfo/PhpInfoSection.php index 33f1760..7e9c3c6 100644 --- a/src/PhpInfo/PhpInfoSection.php +++ b/src/PhpInfo/PhpInfoSection.php @@ -10,6 +10,9 @@ */ final readonly class PhpInfoSection { + /** + * Creates a phpinfo overview section. + */ public function __construct( /** * Eyebrow shown in the section header ('PHP version', 'Build', ...). diff --git a/src/PhpInfo/PhpInfoTile.php b/src/PhpInfo/PhpInfoTile.php index f1d305f..592751e 100644 --- a/src/PhpInfo/PhpInfoTile.php +++ b/src/PhpInfo/PhpInfoTile.php @@ -37,6 +37,9 @@ */ public const string KIND_TOKEN_LIST = 'token-list'; + /** + * Creates a typed tile for a phpinfo overview section. + */ public function __construct( /** * Tile label rendered in the `

` cell ('SAPI', 'Memory limit', ...). diff --git a/src/PhpInfo/PhpInfoTocEntry.php b/src/PhpInfo/PhpInfoTocEntry.php index b8ad2cf..fa15dca 100644 --- a/src/PhpInfo/PhpInfoTocEntry.php +++ b/src/PhpInfo/PhpInfoTocEntry.php @@ -9,6 +9,9 @@ */ final readonly class PhpInfoTocEntry { + /** + * Creates a phpinfo sidebar table-of-contents entry. + */ public function __construct( /** * Display title ('Overview', 'apcu', 'Core', ...). diff --git a/src/PhpInfo/PhpInfoToken.php b/src/PhpInfo/PhpInfoToken.php index 3c81178..81f2b44 100644 --- a/src/PhpInfo/PhpInfoToken.php +++ b/src/PhpInfo/PhpInfoToken.php @@ -10,6 +10,9 @@ */ final readonly class PhpInfoToken { + /** + * Creates a token for a phpinfo overview tile. + */ public function __construct( /** * Display text shown inside the `` token (for path lists this is the basename only). diff --git a/src/PhpInfo/PhpInfoView.php b/src/PhpInfo/PhpInfoView.php index 08c8eb1..62bf26a 100644 --- a/src/PhpInfo/PhpInfoView.php +++ b/src/PhpInfo/PhpInfoView.php @@ -9,6 +9,9 @@ */ final readonly class PhpInfoView { + /** + * Creates the composed phpinfo page view. + */ public function __construct( /** * Overview hero sections ('PHP version' first with the 'PHP_VERSION' headline, then Build / Configuration / diff --git a/src/Registration/PanelOverride.php b/src/Registration/PanelOverride.php index 6137a9f..ee9a1be 100644 --- a/src/Registration/PanelOverride.php +++ b/src/Registration/PanelOverride.php @@ -29,6 +29,8 @@ public const array KEYS = ['enabled', 'icon', 'position', 'title']; /** + * Creates panel metadata overrides from the supplied values. + * * @param string|null $title Display title replacing the provider default, or `null` to keep it. * @param string|null $icon Icon key replacing the provider default, or `null` to keep it. * @param bool|null $enabled `false` to remove the panel from the host, or `null` to keep it registered. diff --git a/src/Registration/PanelRegistry.php b/src/Registration/PanelRegistry.php index e87db0d..9b35b60 100644 --- a/src/Registration/PanelRegistry.php +++ b/src/Registration/PanelRegistry.php @@ -29,7 +29,9 @@ private function __construct(private array $panels, private array $disabled) {} /** - * @return list IDs removed by configuration, sorted alphabetically, including entries with no default. + * Returns the disabled panel IDs, including entries with no default. + * + * @return list IDs removed by configuration, sorted alphabetically. */ public function disabled(): array { @@ -37,6 +39,8 @@ public function disabled(): array } /** + * Returns the effective panel registrations in display order. + * * @return list Effective registrations in display order. */ public function enabled(): array diff --git a/src/Registration/ParsedEntry.php b/src/Registration/ParsedEntry.php index 9da40d6..73786f1 100644 --- a/src/Registration/ParsedEntry.php +++ b/src/Registration/ParsedEntry.php @@ -14,6 +14,8 @@ final readonly class ParsedEntry { /** + * Creates a parsed collector or panel configuration entry. + * * @param string $class Class name or container identifier the host resolves. * @param array $options Keys the entry declares beside `class`, in declaration order. */ diff --git a/src/Storage/DebugSnapshot.php b/src/Storage/DebugSnapshot.php index f6a2184..a368faa 100644 --- a/src/Storage/DebugSnapshot.php +++ b/src/Storage/DebugSnapshot.php @@ -16,6 +16,8 @@ public const int VERSION = 4; /** + * Creates a versioned envelope for a captured request. + * * @param RequestSummary $summary Captured request metadata. * @param array> $panels Serialized panel payloads indexed by panel ID. * @param array $failures Panel failures indexed by panel ID. diff --git a/src/Storage/ManifestReadResult.php b/src/Storage/ManifestReadResult.php index f1cf556..23809fc 100644 --- a/src/Storage/ManifestReadResult.php +++ b/src/Storage/ManifestReadResult.php @@ -10,6 +10,8 @@ final readonly class ManifestReadResult { /** + * Creates a manifest read result with an optional diagnostic. + * * @param array $entries Newest entries first, or an empty list after a failed read. * @param StorageException|null $error Filesystem, recovery, decoding, or hydration failure. */ diff --git a/src/Storage/PanelFailure.php b/src/Storage/PanelFailure.php index 7786eb4..e79abb4 100644 --- a/src/Storage/PanelFailure.php +++ b/src/Storage/PanelFailure.php @@ -22,6 +22,8 @@ public const string HYDRATE = 'hydrate'; /** + * Creates a panel failure record. + * * @param 'capture'|'hydrate' $stage Lifecycle stage the panel failed in. * @param ExceptionSnapshot $exception Captured panel exception. */ diff --git a/src/Storage/SnapshotReadResult.php b/src/Storage/SnapshotReadResult.php index c13215d..0063a81 100644 --- a/src/Storage/SnapshotReadResult.php +++ b/src/Storage/SnapshotReadResult.php @@ -10,6 +10,8 @@ final readonly class SnapshotReadResult { /** + * Creates a snapshot read result with an optional diagnostic. + * * @param DebugSnapshot|null $snapshot The read snapshot, if available. * @param StorageException|null $error The storage error, if any. */ diff --git a/src/Storage/SnapshotWriteResult.php b/src/Storage/SnapshotWriteResult.php index 7790a49..c9fa5a2 100644 --- a/src/Storage/SnapshotWriteResult.php +++ b/src/Storage/SnapshotWriteResult.php @@ -10,6 +10,8 @@ final readonly class SnapshotWriteResult { /** + * Creates a snapshot write result with the committed manifest and evictions. + * * @param array $entries Committed manifest entries, newest first. * @param list $removed Entries evicted from the manifest. */ diff --git a/src/View/Grid/SortHeader.php b/src/View/Grid/SortHeader.php index f91cb57..528ba2b 100644 --- a/src/View/Grid/SortHeader.php +++ b/src/View/Grid/SortHeader.php @@ -12,6 +12,8 @@ final readonly class SortHeader implements Stringable { /** + * Creates a sortable-column header with its announced order. + * * @param string $link Rendered link requesting the order of the next click. * @param array $attributes Header cell attributes announcing the active order, empty while the * rows are ordered by another attribute. diff --git a/src/View/History/HistoryRow.php b/src/View/History/HistoryRow.php index 80c320f..3c084ce 100644 --- a/src/View/History/HistoryRow.php +++ b/src/View/History/HistoryRow.php @@ -13,6 +13,9 @@ */ final readonly class HistoryRow { + /** + * Creates a captured-request row for the History grid. + */ public function __construct( /** * Request tag (hex hash); empty when not captured. diff --git a/src/View/History/HistoryScale.php b/src/View/History/HistoryScale.php index d658585..ed55f48 100644 --- a/src/View/History/HistoryScale.php +++ b/src/View/History/HistoryScale.php @@ -11,6 +11,9 @@ */ final readonly class HistoryScale { + /** + * Creates maxima for the History grid gauges. + */ public function __construct( /** * Largest captured processing time on the page, in seconds; `0.0` when no row carries one. diff --git a/src/View/History/HistoryStatusBucket.php b/src/View/History/HistoryStatusBucket.php index d308b7f..75b30de 100644 --- a/src/View/History/HistoryStatusBucket.php +++ b/src/View/History/HistoryStatusBucket.php @@ -9,6 +9,9 @@ */ final readonly class HistoryStatusBucket { + /** + * Creates a status-code bucket for the History summary. + */ public function __construct( /** * Display label ('2xx' / '3xx' / '4xx' / '5xx'). diff --git a/src/View/History/HistorySummary.php b/src/View/History/HistorySummary.php index 71bb528..c37b8d1 100644 --- a/src/View/History/HistorySummary.php +++ b/src/View/History/HistorySummary.php @@ -13,6 +13,9 @@ */ final readonly class HistorySummary { + /** + * Creates aggregate metrics for the History summary. + */ public function __construct( /** * Total number of captured requests in the manifest. diff --git a/src/View/Sidebar/SidebarNavItem.php b/src/View/Sidebar/SidebarNavItem.php index b449cda..aadb09a 100644 --- a/src/View/Sidebar/SidebarNavItem.php +++ b/src/View/Sidebar/SidebarNavItem.php @@ -9,6 +9,9 @@ */ final readonly class SidebarNavItem { + /** + * Creates a debugger sidebar navigation entry. + */ public function __construct( /** * Visible label shown next to the icon ('History', 'Request', 'Database', ...). diff --git a/src/View/Sidebar/SidebarNavigation.php b/src/View/Sidebar/SidebarNavigation.php index bdad794..6e76402 100644 --- a/src/View/Sidebar/SidebarNavigation.php +++ b/src/View/Sidebar/SidebarNavigation.php @@ -13,6 +13,9 @@ */ final readonly class SidebarNavigation { + /** + * Creates the sidebar snapshot navigation state. + */ public function __construct( /** * `true` when the sidebar is rendered for the index page and the navigator buttons act as a grid cursor. diff --git a/src/View/Sidebar/SidebarView.php b/src/View/Sidebar/SidebarView.php index 897b7f8..fd17ac2 100644 --- a/src/View/Sidebar/SidebarView.php +++ b/src/View/Sidebar/SidebarView.php @@ -14,6 +14,9 @@ */ final readonly class SidebarView { + /** + * Creates the debugger sidebar view. + */ public function __construct( /** * Snapshot card view-model; `null` when the manifest is empty so the card section is skipped entirely. From 746e525eaecc81884ca114882e4ec3b48759f5ac Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Mon, 16 Nov 2026 08:47:28 -0300 Subject: [PATCH 2/2] Apply fixed Coderabbitai review. --- docs/agents.md | 4 +++- stryker.config.mjs | 7 ++++++- tests/Panel/Queue/QueuePanelTest.php | 12 ++++++------ 3 files changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/agents.md b/docs/agents.md index 4c76d7a..820398e 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -29,7 +29,9 @@ npx skills@1.7.2 add /absolute/path/to/debug-core --skill php-forge-debug-core - ``` Keep project scope. Inspect a remote source with `--list` before claiming an unpublished skill is available there. -Copied installations must be refreshed after upgrades. The complete skill directory is the unit of installation. +After upgrading the package, repeat the `npx skills@1.7.2 add` installation command above to refresh copied and +symlinked installations. Symlinks point to the installer's canonical copy, which does not update with the package. +The complete skill directory is the unit of installation. ## Discover and invoke diff --git a/stryker.config.mjs b/stryker.config.mjs index 917e560..b6448bf 100644 --- a/stryker.config.mjs +++ b/stryker.config.mjs @@ -2,7 +2,12 @@ /** @type {import("@stryker-mutator/api/core").PartialStrykerOptions} */ const config = { - ignorePatterns: ["/runtime", "/artifacts"], + ignorePatterns: [ + "/runtime", + "/artifacts", + "/.agents/skills", + "/.claude/skills", + ], mutate: [ "resources/src/core/clipboard.js", "resources/src/core/deep-links.js", diff --git a/tests/Panel/Queue/QueuePanelTest.php b/tests/Panel/Queue/QueuePanelTest.php index f85bbf5..9e7ded5 100644 --- a/tests/Panel/Queue/QueuePanelTest.php +++ b/tests/Panel/Queue/QueuePanelTest.php @@ -198,12 +198,12 @@ public function testJobDetailUrlsComeFromTheAdapter(): void ->jobUrls([1 => '/debug/queue-job?seq=1']) ->present( ( - new QueueSnapshot( - [ - JobRecordFixture::create(time: self::TIME), - JobRecordFixture::create(time: self::TIME), - ], - ) + new QueueSnapshot( + [ + JobRecordFixture::create(time: self::TIME), + JobRecordFixture::create(time: self::TIME), + ], + ) )->jsonSerialize(), );