Skip to content

CLAUDE.md

Latest commit

 

History

History
133 lines (98 loc) · 4.96 KB

CLAUDE.md

File metadata and controls

133 lines (98 loc) · 4.96 KB
Raw

Schema - All In One Schema Rich Snippets

WordPress plugin by Brainstorm Force that adds structured data (schema markup / Microdata) to posts and pages via a meta box interface.

Tech Stack

  • Language: PHP (WordPress plugin — no framework)
  • Standards: WordPress Coding Standards (WPCS) via PHPCS
  • Static analysis: PHPStan level 9
  • Build: Grunt (i18n, zip packaging, README generation)
  • Testing: PHPUnit 9.x
  • Package manager: Composer (PHP dev deps) + npm (Grunt/i18n tools)
  • Git hooks: brainmaestro/composer-git-hooks (pre-commit merge-conflict guard)

Key Files

File Purpose
index.php Plugin bootstrap — RichSnippets class, all hook registrations
functions.php Front-end rendering (display_rich_snippet()), AJAX rating handlers
meta-boxes.php bsf_metaboxes() — all schema field definitions
settings.php Default option seeds for each schema type
init.php Bsf_Meta_Box class (meta box framework)
admin/index.php Admin dashboard page (rich_snippet_dashboard)
js/toggle.js Dynamic field show/hide based on schema type dropdown
phpcs.xml.dist PHPCS ruleset (WPCS + security forbidden functions)
phpstan.neon PHPStan config (level 9, WP stubs)

Commands

# Install all dependencies
composer install && npm install

# Install git pre-commit hooks
vendor/bin/cghooks add --ignore-lock

# Lint (PHPCS)
composer lint

# Auto-fix style issues (PHPCBF)
composer format

# Static analysis (PHPStan)
composer phpstan

# Run unit tests (PHPUnit)
vendor/bin/phpunit

# Regenerate PHPStan stubs
composer gen-stubs

# Generate .pot translation file
npm run i18n

# Compile .mo files from .po
npm run i18n:mo

# Regenerate README.md from readme.txt
npx grunt readme

# Build release ZIP
npx grunt zip

Architecture

  • Single meta box (review_metabox) covers all schema types — field visibility toggled by js/toggle.js
  • Post meta key prefix: _bsf_ (leading underscore hides from WP Custom Fields panel)
  • Type selector: _bsf_post_type — integer 0/1/2/5/6/7/8/9/10/11
  • Options prefix: bsf_* (e.g. bsf_review, bsf_product, bsf_custom)
  • Front-end output: display_rich_snippet() on the_content filter — outputs Microdata HTML
  • AJAX handlers: bsf_submit_rating, bsf_update_rating (public), bsf_submit_color, bsf_submit_request (admin)
  • Third-party libs: BSF Analytics (admin/bsf-analytics/), NPS Survey (lib/nps-survey/), Astra Notices (lib/notices/)

Schema Types

Value Type Option Key
1 Item Review bsf_review
2 Event bsf_event
5 Person bsf_person
6 Product bsf_product
7 Recipe bsf_recipe
8 Software Application bsf_software
9 Video bsf_video
10 Article bsf_article
11 Service bsf_service

Gotchas

  • WooCommerce exclusion: By default, product post types are excluded from the meta box. Toggle in admin Tab 5 or use bsf_exclude_custom_post_type filter.
  • BSF_META_BOX_URL constant: Defined in init.php with Windows path handling — don't redefine it.
  • Pre-commit hook blocks literal conflict markers (7x <, 7x =, 7x >) in any committed file — including docs. Use alternative notation in documentation.
  • PHPCS excludes: lib/, vendor/, admin/bsf-analytics/, node_modules/, stubs/ — don't add production code there expecting it to be linted.
  • PHPStan baseline: phpstan-baseline.neon suppresses known false positives — add new intentional patterns here rather than inline ignores.
  • Text domain is rich-snippets (not the plugin slug all-in-one-schemaorg-rich-snippets).
  • register_activation_hook is called in index.php and seeds options via settings.php — re-running add_option() is safe (won't overwrite existing values).
  • Schema Pro detection: is_schema_pro_installed() checks for wp-schema-pro/wp-schema-pro.php file existence to conditionally show the "Get Schema Pro" upsell.

Current Focus

  • Ongoing maintenance and compatibility updates

Development Notes

  • Run composer format before every commit to avoid PHPCS failures
  • PHPStan must pass with no new errors — add to baseline if suppression is intentional
  • All user input must be sanitized; all output must be escaped (see WPCS rules)
  • Nonce verification required on all AJAX handlers before processing
  • manage_options capability check required for admin-only AJAX actions