feat: move the debugger and DB viewer into a presence-debugger plugin by aldorizona10-glitch · Pull Request #760 · WordPress/presence-api

aldorizona10-glitch · 2026-10-06T12:42:52Z

Closes #732. Builds on the split started in #558/#554 — this takes the debugger out of the bundle, as the issue describes.

Follows plugins/presence-scenes: a new plugins/presence-debugger plugin with its own load.php header, Requires Plugins: presence-api, README, .distignore, and a release-please entry. The tools stay WP_DEBUG-only.

What moved

The two files move unchanged (git mv, 100% rename):

includes/debugger-admin-bar.php → presence-debugger/debugger-admin-bar.php
includes/db-viewer.php → presence-debugger/db-viewer.php
tests/test-debugger-admin-bar.php → presence-debugger/tests/ (only its require path changed)

They keep the presence-api text domain they already had — those strings only show under WP_DEBUG and were deliberately kept out of the translation template, so the move adds no new domain for translators. There's no uninstall.php: neither tool writes an option, transient or cron event.

Loader

presence-api.php drops its WP_DEBUG block. The new load.php re-registers the exact same hooks, under the same guard, on plugins_loaded once wp_get_presence() exists:

if ( ! ( defined( 'WP_DEBUG' ) && WP_DEBUG ) ) {
	return;
}
// … require the two files + the same add_action/add_filter calls.

Exclusion lists & release config

plugins/presence-api/.distignore, phpunit.xml.dist coverage, and codecov.yml drop the two old includes/*.php paths; codecov.yml now ignores plugins/presence-debugger/**. scripts/check-debug-exclusions.sh now checks that the two coverage lists agree (phpunit.xml.dist == codecov.yml) on the remaining always-excluded includes/*.php files; the .distignore comparison is gone, since no includes/*.php lines remain there.
release-please-config.json gets a presence-debugger package (initial-version 0.1.0) and the root package excludes its path; .release-please-manifest.json seeds 0.1.0. scripts/sync-versions.sh already handles "every other package" generically, so it finds the new load.php header on its own.
presence-scenes' debugger test is repointed to the new location; the test bootstrap loads the new plugin (before presence-scenes, matching plugin load order).

Playground demo

Both playground-preview and playground-main-build now build presence-debugger.zip next to presence-api.zip and publish it, and the four preview blueprints plus blueprint-scenes.json install it as a second plugin (the two multisite blueprints network-activate it after presence-api). The schema-validate step now requires exactly one presence-debugger.zip alongside presence-api.zip, and the publish transform rewrites its URL too, so the preview demo and the README's Presence Scenes demo show the debugger again. The wordpress.org blueprint.json (released presence-api + the debugger from the pinned tag) is untouched until the next release.

Verification

Locally I ran scripts/check-debug-exclusions.sh (passes) and validated the JSON. PHPUnit/PHPCS/PHPStan/php -l run here in CI.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus
Used for: Working through this review — drafting the call-site notes that explain the debugger's use of presence-api internals, and the tooling and Playground wiring (phpcs/phpstan/wp-env, the exclusions check, the preview/main-build workflows and the blueprints). I reviewed the diff, ran the checks locally, and take responsibility for the result.

github-actions · 2026-10-06T12:43:01Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props aldorza, joefusco.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2026-10-06T12:43:39Z

🛝 WordPress Playgrounds

Built from df9aed9

	Post locks	RTC	Settings
Single site
Multisite

josephfusco

Thanks for picking this up. Keeping the hook names and load order means presence-scenes still works: in wp-env its assets load right after the debugger's, and Presence API keeps running with presence-debugger deactivated.

#732 also asks about the private functions. The debugger calls wp_presence_room_rows(), wp_presence_get_timeout(), wp_presence_has_table() and wp_presence_fragment_request(), and the DB viewer calls wp_presence_has_table(). Each needs a public equivalent, or a short note on why the call stays. The asset versions can keep WP_PRESENCE_VERSION.

.wp-env.json doesn't list ./plugins/presence-debugger, so npm run env:start no longer shows the debugger. phpcs.xml.dist and phpstan.neon.dist don't scan plugins/presence-debugger/ either. The moved files pass both, so add the path to each.

blueprint-scenes.json installs the preview-main zip, which won't carry the debugger after this merges, so the README's Presence Scenes demo would lose it along with the scene ticket. On your Playground question, please handle it here: zip plugins/presence-debugger in both playground workflows next to presence-api.zip, and install it as a second plugin in the preview blueprints and blueprint-scenes.json. The wordpress.org blueprint.json can wait for the next release.

In check-debug-exclusions.sh, .distignore has no includes/*.php lines left, so the distignore comparison can go instead of getting || true. The header needs updating too, since it says "two places" and then lists three. The comments added to the two workflows and make-pot.sh describe what used to happen. The workflow ones can go, and the make-pot.sh paragraph can go back to its first sentence.

Please add an AI disclosure to the description, or "None" if you didn't use any.

The WP_DEBUG-only admin-bar debugger and the ?presence-db=1 table viewer move out of Presence API into their own plugin, plugins/presence-debugger, following plugins/presence-scenes. The files move unchanged: presence-api drops its WP_DEBUG loader block and the new plugin's load.php registers the same hooks under the same WP_DEBUG + `Requires Plugins: presence-api` guard, so a normal site still loads nothing. - release-please: new presence-debugger package (0.1.0) and root exclude-path - coverage: the three exclusion lists (.distignore / phpunit.xml.dist / codecov.yml) and check-debug-exclusions.sh updated for the new location - presence-scenes' debugger test repointed to the moved file - Playground preview/main-build no longer inject the moved files Closes WordPress#732

…strap Matches the alphabetical order WordPress loads the plugins in, so the test environment mirrors a real site.

…erage-exclusion check

aldorizona10-glitch · 2026-10-06T19:00:06Z

Thanks for the thorough review — addressed all of it.

Private functions. Kept the calls and documented each at the call site, since the public API doesn't cover what a debug tool needs:

wp_presence_has_table() (both files) — guards on the table existing. wp_presence_is_available() also requires recording to be on, which would hide stored rows when it's switched off.
wp_presence_room_rows() — the debugger shows the reserved bookkeeping rows that the public wp_get_presence() deliberately drops.
wp_presence_get_timeout() — reports the resolved TTL after the wp_presence_default_ttl filter; there's no public getter for it.
wp_presence_fragment_request() — reads the Heartbeat payload under the same key the surfaces in presence-ping.js register.

Happy to promote any of these to the public API instead if you'd rather not have the debugger lean on internals.

Tooling. .wp-env.json now lists ./plugins/presence-debugger (before presence-scenes, matching load order), and phpcs.xml.dist / phpstan.neon.dist scan plugins/presence-debugger/ with its tests excluded, as presence-scenes does. Asset versions keep WP_PRESENCE_VERSION.

check-debug-exclusions.sh. Dropped the .distignore comparison — no includes/*.php lines remain there — instead of papering it over with || true. The header now says two places and lists the two it actually checks (phpunit.xml.dist and codecov.yml).

Stale comments. Removed from both playground workflows, and the make-pot.sh paragraph is back to its first sentence.

Playground (done in this PR). Both workflows now build presence-debugger.zip next to presence-api.zip and publish it (preview-main and the per-PR branch); the four preview blueprints plus blueprint-scenes.json install it as a second plugin, and the two multisite blueprints network-activate it after presence-api. The schema-validate step now requires exactly one presence-debugger.zip alongside presence-api.zip, and the publish transform rewrites its URL too. The wordpress.org blueprint.json is untouched.

PR template. Added the AI disclosure section below.

…comments

josephfusco

I pushed 1e0e259 to finish this off. Removing the debugger file from includes/ would have broken the WordPress.org demo in 0.16.0, so the demo now installs plugins/presence-debugger from the release tag, and sync-versions.sh moves that tag forward with each release. I also cut the comments about the move and shortened the private-function notes to one sentence each.

aldorizona10-glitch requested review from i-am-chitti and josephfusco as code owners October 6, 2026 12:42

github-actions Bot added a commit that referenced this pull request Oct 6, 2026

Playground preview for PR #760 at 8227d3a

58759ce

josephfusco requested changes Oct 6, 2026

View reviewed changes

josephfusco mentioned this pull request Oct 6, 2026

Trim presence-scenes and presence-debugger to what WordPress needs to load them #761

Closed

4 tasks

josephfusco added [Type] Enhancement A suggestion for improvement of an existing feature [Area] Infrastructure Issues for the repository infrastructure [Area] Admin UI Issues for the admin UI integrations labels Oct 6, 2026

aldorizona10-glitch added 2 commits October 6, 2026 11:22

chore: load presence-debugger before presence-scenes in the test boot…

df9aed9

…strap Matches the alphabetical order WordPress loads the plugins in, so the test environment mirrors a real site.

josephfusco force-pushed the move-debugger-to-plugin branch from 8227d3a to df9aed9 Compare October 6, 2026 15:22

github-actions Bot added a commit that referenced this pull request Oct 6, 2026

Playground preview for PR #760 at df9aed9

c088fc3

aldorizona10-glitch added 3 commits October 7, 2026 01:28

docs: explain the presence-debugger calls into presence-api internals

a17beb3

ci: add presence-debugger to phpcs, phpstan, and wp-env; tidy the cov…

c81d395

…erage-exclusion check

ci: install presence-debugger in the Playground preview and demos

4af3e98

josephfusco added 2 commits October 7, 2026 10:46

fix: install presence-debugger in the WordPress.org preview and trim …

1e0e259

…comments

test: give the sync-versions fixture a debugger ref

5809658

josephfusco approved these changes Oct 7, 2026

View reviewed changes

josephfusco merged commit 7577905 into WordPress:main Oct 7, 2026
30 checks passed

josephfusco added this to the 0.16.0 milestone Oct 7, 2026

This was referenced Oct 7, 2026

chore(main): release 0.16.0 #759

Merged

chore(main): release presence-scenes 0.2.0 #776

Merged

chore(main): release presence-debugger 0.2.0 #777

Merged

📌 Tracking: Presence API path to Core #550

Open

Navigation Menu

Repository navigation

feat: move the debugger and DB viewer into a presence-debugger plugin - #760

feat: move the debugger and DB viewer into a presence-debugger plugin#760
josephfusco merged 7 commits into
WordPress:mainfrom
aldorizona10-glitch:move-debugger-to-plugin

aldorizona10-glitch commented Oct 6, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 6, 2026

Uh oh!

github-actions Bot commented Oct 6, 2026 •

edited

Loading

Uh oh!

josephfusco left a comment •

edited

Loading

Uh oh!

aldorizona10-glitch commented Oct 6, 2026

Uh oh!

josephfusco left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

aldorizona10-glitch commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What moved

Loader

Exclusion lists & release config

Playground demo

Verification

Uh oh!

github-actions Bot commented Oct 6, 2026

Uh oh!

github-actions Bot commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛝 WordPress Playgrounds

Uh oh!

josephfusco left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aldorizona10-glitch commented Oct 6, 2026

Uh oh!

josephfusco left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aldorizona10-glitch commented Oct 6, 2026 •

edited

Loading

github-actions Bot commented Oct 6, 2026 •

edited

Loading

josephfusco left a comment •

edited

Loading