Skip to content

AGENTS.md

Latest commit

 

History

History
108 lines (89 loc) · 7.2 KB

AGENTS.md

File metadata and controls

108 lines (89 loc) · 7.2 KB

Co-Authors Plus

Multiple byline management for WordPress, supporting both WordPress users and guest authors.

Project Knowledge

Property Value
Main file co-authors-plus.php
Text domain co-authors-plus
Class prefix CoAuthors_ (legacy), CoAuthors\ / Automattic\CoAuthorsPlus\ (namespaced)
Function prefix cap_ (helpers), coauthors* (template tags)
Source directory php/ (PHP classes), src/ (JS/blocks)
Version 4.0.2
Requires PHP 7.4+
Requires WP 6.4+

Directory Structure

co-authors-plus/
├── co-authors-plus.php                # Main plugin file (includes, globals, bootstrap)
├── template-tags.php                  # Template tag functions (coauthors(), get_coauthors(), etc.)
├── upgrade.php                        # Database upgrade functions
├── php/
│   ├── class-coauthors-plus.php       # Main plugin class (taxonomy, meta boxes, AJAX)
│   ├── class-coauthors-guest-authors.php  # Guest author CPT management
│   ├── class-coauthors-template-filters.php # Frontend template filters
│   ├── class-coauthors-wp-list-table.php   # Admin list table
│   ├── class-coauthors-iterator.php   # Iterator for looping through coauthors
│   ├── class-wp-cli.php              # WP-CLI commands
│   ├── api/endpoints/                 # REST API controller (CoAuthors\API\Endpoints)
│   ├── blocks/                        # Gutenberg blocks (CoAuthors\Blocks)
│   └── integrations/                  # AMP, Yoast, WordPress Importer, Jetpack
├── src/                               # JavaScript/React source (blocks, store)
├── build/                             # Compiled JavaScript output
├── tests/
│   └── Integration/                   # Integration tests (requires wp-env)
├── features/                          # Behat acceptance tests
├── .github/workflows/                 # CI: cs-lint, integration, lint, build, behat, deploy
└── .phpcs.xml.dist                    # PHPCS configuration

Key Classes and Files

  • php/class-coauthors-plus.php — Main CoAuthors_Plus class: author taxonomy, meta boxes, post author filtering, AJAX search, caching
  • php/class-coauthors-guest-authors.php — CoAuthors_Guest_Authors: guest author CPT (guest-author), admin UI, avatar handling, privacy export
  • template-tags.php — Template functions: coauthors(), get_coauthors(), is_coauthor_for_post(), coauthors_posts_links(), etc.
  • php/class-coauthors-iterator.php — Enables looping through coauthors; modifies global $authordata
  • php/class-coauthors-template-filters.php — Frontend filters for the_author, the_author_posts_link, RSS feeds
  • php/api/endpoints/class-coauthors-controller.php — REST API controller (coauthors/v1)
  • php/blocks/ — Five Gutenberg blocks for displaying coauthor information
  • php/class-wp-cli.php — WP-CLI commands: wp co-authors-plus create-guest-authors, create-terms-for-posts
  • php/integrations/ — Integrations with AMP, Yoast SEO, WordPress Importer, Jetpack

Dependencies

  • Dev: automattic/vipwpcs, yoast/wp-test-utils, phpunit/phpunit, behat/behat, automattic/behat-wp-env-context

Commands

composer cs                # Check code standards (PHPCS)
composer cs-fix            # Auto-fix code standard violations
composer lint              # PHP syntax lint
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 behat             # Run Behat acceptance tests
npm run build              # Build JavaScript/block assets
npm run lint:js            # Lint JavaScript (ESLint)
npm run lint:css           # Lint CSS (Stylelint)

Note: This plugin has integration tests and Behat acceptance tests — no separate unit test suite.

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: Integration tests for WordPress-dependent behaviour. Use the existing TestCase base class in tests/Integration/. Behat for acceptance testing.
  • Code style: WordPress coding standards via PHPCS. Tabs for indentation.
  • i18n: All user-facing strings must use the co-authors-plus text domain.

Architectural Decisions

  • Taxonomy-based storage: Coauthor relationships are stored via the author taxonomy, with term slugs in the format cap-{user_nicename}. This leverages WordPress's taxonomy infrastructure for queries and caching. Do not switch to post meta or custom tables.
  • Guest author CPT: Guest authors are a custom post type (guest-author) allowing bylines without WordPress user accounts. This is a core feature — do not remove or replace it.
  • Post author field sync: The plugin syncs wp_posts.post_author via the coauthors_set_post_author_field filter to maintain backward compatibility with queries expecting a single author. Do not break this sync.
  • SQL query filters: Author queries are modified via posts_where, posts_join, and posts_groupby filters. Changes to these filters can break archive pages and author queries site-wide.
  • Block system: Five Gutenberg blocks use co-authors-plus/author block context. The blocks are in php/blocks/ with React source in src/blocks/.
  • WordPress.org deployment: Has a deploy workflow for WordPress.org SVN. Do not manually modify SVN assets.

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.
  • Template tags are public API: Functions in template-tags.php (coauthors(), get_coauthors(), coauthors_posts_links(), etc.) are used by themes in production. Do not rename, remove, or change their signatures without a deprecation cycle.
  • Coauthor term ordering is significant: The plugin maintains term order for coauthors. Bulk edits or direct term manipulation can reset ordering.
  • Guest author deletion: When a guest author is deleted, posts need reassignment. The plugin handles this via delete_user_action, but test carefully.
  • post_author sync: Misalignment between the author taxonomy terms and wp_posts.post_author can cause issues. Always use plugin functions to modify coauthors, not direct database updates.
  • Custom wp_notify_postauthor(): The plugin overrides the core function to notify all coauthors of comments. This can conflict with other plugins that also override this function.
  • Author archive pages: Guest authors use a different URL structure. The fix_author_page hook handles this — do not remove it or archive pages will break.
  • Two version locations: Version is defined in co-authors-plus.php (header + constant) and package.json. Both must be kept in sync.