Skip to content

AGENTS.md

Latest commit

 

History

History
88 lines (70 loc) · 4.3 KB

AGENTS.md

File metadata and controls

88 lines (70 loc) · 4.3 KB

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.0
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

Follow the standards documented in ~/code/plugin-standards/ for full details. Key points:

  • Commits: Use the /commit skill. Favour explaining "why" over "what".
  • PRs: Use the /pr skill. Squash and merge by default.
  • 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.