Wp Voyager Conventions

Dependency Chain

voyager-block-theme (parent)
  └── voyagermark / client themes (children)

voyager-core (required by)
  ├── voyager-blocks (soft dep — GSAP, entrance animations)
  └── voyager-orbit (independent, but co-installed)

Naming Conventions

Blocks (voyager-blocks)

• Block name: voyager/{block-slug} — kebab-case
• Directory: src/blocks/{block-slug}/
• CSS class: wp-block-voyager-{block-slug}
• Category: voyager
• Text domain: voyager-blocks

Patterns

• Slug: {theme-slug}/{pattern-name} (e.g., voyagermark/hero-home)
• Registration: Auto-loaded via glob() from patterns/ directory
• Format: PHP file with header comments (Title, Slug, Categories, Keywords)

REST Endpoints (voyager-orbit)

• Namespace: voyager/v1
• Response format: { data: T[], total: N } for lists
• Auth: HMAC-SHA256 via AuthMiddleware (see below)

PHP (voyager-orbit)

• Namespace: Voyager\Orbit\{Module}\{Class}
• Autoloading: PSR-4 via Composer (src/ → Voyager\Orbit\)
• PHP version: 8.1+ with declare(strict_types=1)

Authentication Pattern

All Voyager REST endpoints use the same three-tier auth:

1. WordPress admin: current_user_can('manage_options') — bypasses API auth
2. HMAC-SHA256: Three headers required:
   • X-Voyager-Site-Id — site domain
   • X-Voyager-Signature — sha256= + HMAC of payload
   • X-Voyager-Timestamp — Unix timestamp (300s drift max)
3. Bearer token: Authorization: Bearer {token} (legacy fallback)

Constant-time comparison via hash_equals() everywhere.

Security Baseline

Every Voyager repo follows these rules:

• $wpdb->prepare() for all dynamic SQL — never string concatenation
• sanitize_text_field(), sanitize_email(), esc_url_raw() for input
• esc_html(), esc_attr(), esc_url() for output
• hash_equals() for all secret comparisons
• No eval(), shell_exec(), exec(), system()
• prefers-reduced-motion: reduce respected in all animations

Commit Convention

All repos use Conventional Commits: