Skip to content

AGENTS.md

Latest commit

 

History

History
88 lines (70 loc) · 4.84 KB

AGENTS.md

File metadata and controls

88 lines (70 loc) · 4.84 KB
Raw

Rewrite Rules Inspector

Debug and inspect WordPress rewrite rules.

Project Knowledge

Property Value
Main file rewrite-rules-inspector.php
Text domain rewrite-rules-inspector
Namespace Automattic\RewriteRulesInspector
Source directory src/
Version 1.6.1
Requires PHP 7.4+
Requires WP 6.4+

Directory Structure

rewrite-rules-inspector/
├── src/
│   ├── Plugin.php          # Main plugin class
│   ├── Core/               # Core logic (UrlTester, RewriteRules)
│   └── Admin/              # Admin UI (AdminPage, RewriteRulesTable)
├── views/                  # PHP template files for admin pages
├── assets/                 # CSS/JS assets
├── tests/
│   ├── Unit/               # Unit tests
│   └── Integration/        # Integration tests (wp-env)
├── languages/              # Translation files
├── rector.php              # Rector configuration for code modernisation
├── .github/workflows/      # CI: deploy, integration
└── .phpcs.xml.dist         # PHPCS configuration

Key Classes

  • Plugin — Main plugin bootstrap, registers hooks
  • Core\RewriteRules — Retrieves and analyses WordPress rewrite rules
  • Core\UrlTester — Tests URLs against rewrite rules
  • Admin\AdminPage — Admin tools page registration
  • Admin\RewriteRulesTable — WP_List_Table for displaying rewrite rules

Dependencies

  • Dev: automattic/vipwpcs, yoast/wp-test-utils, rector/rector

Commands

composer cs                # Check code standards (PHPCS)
composer cs-fix            # Auto-fix code standard violations
composer lint              # PHP syntax lint
composer test:unit         # Run unit tests
composer test:integration  # Run integration tests (requires wp-env)
composer test:integration-ms  # Run multisite integration tests
composer coverage          # Run tests with HTML coverage report
composer rector            # Run Rector for code modernisation suggestions

Conventions

See CONTRIBUTING.md for setup, checks and the contribution workflow. Key points:

  • Commits: Every commit must be signed; develop and main reject unsigned commits. Use a Conventional Commits prefix (fix:, feat:, test:, docs:, ci:, chore: and so on) with an imperative subject of about 50 characters, and a body that explains why the change was needed rather than what changed. One concern per commit.
  • PRs: Open against develop. The title describes the outcome in sentence case, without a conventional commit prefix. The description explains the problem first, then how the PR solves it. PRs land as merge commits (squash and rebase merging are disabled), so every commit message reaches develop as written.
  • Branch naming: feature/description, fix/description from develop.
  • Testing: Write integration tests for WordPress-dependent behaviour, unit tests for isolated logic. Use Yoast\WPTestUtils\WPIntegration\TestCase for integration, Yoast\WPTestUtils\BrainMonkey\YoastTestCase for unit.
  • Code style: WordPress coding standards via PHPCS. Tabs for indentation.
  • i18n: All user-facing strings must use the rewrite-rules-inspector text domain.

Architectural Decisions

  • Separation of concerns: Core logic (rewrite rule analysis, URL testing) is separated from admin UI. Keep this boundary — do not mix display logic into core classes.
  • View templates: Admin page HTML is in views/ as separate template files, not inline in PHP classes. New admin views should follow this pattern.
  • WordPress.org deployment: Has a deploy workflow for WordPress.org SVN. Do not manually modify SVN assets.
  • Rector available: Includes Rector for automated code modernisation. Use composer rector to check for opportunities.
  • Debugging tool: This plugin is a developer tool, not an end-user feature. The UI prioritises information density and accuracy over visual polish.

Common Pitfalls

  • Do not edit WordPress core files or bundled dependencies in vendor/.
  • Run composer cs before committing. CI will reject code standard violations.
  • Integration tests require npx wp-env start running first.
  • Rewrite rules are generated by WordPress core, themes, and other plugins. Do not modify rewrite rules from this plugin — it is an inspector, not a modifier.
  • The flush_rewrite_rules() function is expensive. If adding a flush feature, it must only run on explicit user action, never on every page load.
  • WordPress rewrite rules can vary significantly between sites. Test with a variety of permalink structures, not just the default.
  • Admin list table extends WP_List_Table, which is a WordPress internal class marked as private. Be cautious with assumptions about its API stability.