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
1 change: 1 addition & 0 deletions .agents/skills/php-forge-debug-core
1 change: 1 addition & 0 deletions .claude/skills/php-forge-debug-core
24 changes: 24 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/dependency-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion .github/workflows/ecs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion .github/workflows/mutation.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/quality.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
23 changes: 23 additions & 0 deletions .github/workflows/scorecard.yml
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion .github/workflows/security.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/static.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
13 changes: 13 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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/
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
46 changes: 39 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,15 @@
<a href="https://github.com/php-forge/debug-core/actions/workflows/build.yml" target="_blank">
<img src="https://img.shields.io/github/actions/workflow/status/php-forge/debug-core/build.yml?style=for-the-badge&label=PHPUnit&logo=github" alt="PHPUnit">
</a>
<a href="https://codecov.io/github/php-forge/debug-core" target="_blank">
<img src="https://img.shields.io/codecov/c/github/php-forge/debug-core.svg?style=for-the-badge&logo=codecov&logoColor=white&label=Coverage" alt="Coverage">
</a>
<a href="https://dashboard.stryker-mutator.io/reports/github.com/php-forge/debug-core/main" target="_blank">
<img src="https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fphp-forge%2Fdebug-core%2Fmain" alt="Mutation Testing">
</a>
<a href="https://github.com/php-forge/debug-core/actions/workflows/static.yml" target="_blank">
<img src="https://img.shields.io/github/actions/workflow/status/php-forge/debug-core/static.yml?style=for-the-badge&label=PHPStan&logo=github" alt="PHPStan">
</a>
<a href="https://github.com/php-forge/debug-core/actions/workflows/security.yml" target="_blank">
<img src="https://img.shields.io/github/actions/workflow/status/php-forge/debug-core/security.yml?style=for-the-badge&label=Security&logo=github" alt="Security">
</a>
</p>

<p align="center">
Expand All @@ -30,8 +30,8 @@
## Features

<picture>
<source media="(min-width: 768px)" srcset="./docs/svgs/features.svg">
<img src="./docs/svgs/features-mobile.svg" alt="Feature overview" style="width: 100%;">
<source media="(min-width: 768px)" srcset="https://raw.githubusercontent.com/php-forge/debug-core/main/docs/svgs/features.svg">
<img src="https://raw.githubusercontent.com/php-forge/debug-core/main/docs/svgs/features-mobile.svg" alt="Feature overview" style="width: 100%;">
</picture>

## Installation
Expand Down Expand Up @@ -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)
Expand All @@ -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

Expand Down
3 changes: 3 additions & 0 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,9 @@
"extra": {
"branch-alias": {
"dev-main": "0.2.x-dev"
},
"skills": {
"source": "skills"
}
},
"config": {
Expand Down
63 changes: 63 additions & 0 deletions docs/agents.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# 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.
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

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)
41 changes: 41 additions & 0 deletions skills/php-forge-debug-core/SKILL.md
Original file line number Diff line number Diff line change
@@ -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 `</body>` 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.
4 changes: 4 additions & 0 deletions skills/php-forge-debug-core/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -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."
2 changes: 2 additions & 0 deletions src/Capture/CapturePolicy.php
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@
private array $sensitiveKeyPatterns;

/**
* Creates a capture policy with redaction and size limits.
*
* @param list<string> $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<string> $sensitiveKeyPrefixes Literal, case-insensitive key prefixes to redact recursively.
Expand Down
4 changes: 3 additions & 1 deletion src/Collector/CollectorCoordinator.php
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,9 @@ public function collector(string $id): CollectorInterface|null
}

/**
* @return array<string, CollectorInterface> Registered collectors for host-local instrumentation hooks.
* Returns the collectors registered for host-local instrumentation hooks.
*
* @return array<string, CollectorInterface> Registered collectors indexed by ID.
*/
public function collectors(): array
{
Expand Down
2 changes: 2 additions & 0 deletions src/Instrumentation/InstrumentationGuard.php
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
3 changes: 3 additions & 0 deletions src/Panel/Asset/AssetBundleRow.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions src/Panel/Asset/AssetSnapshot.php
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@
final readonly class AssetSnapshot implements PanelSnapshot
{
/**
* Creates an asset snapshot from bundles and an optional Vite manifest.
*
* @param list<AssetBundleRow> $bundles
*/
public function __construct(
Expand Down
3 changes: 3 additions & 0 deletions src/Panel/Asset/ViteChunk.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading
Loading