Synced Theme Patterns

Orbit allows WordPress block themes to define synced patterns (patterns with pattern overrides) directly in theme PHP files while keeping those files as the single version-controlled source of truth.

Without Orbit, creating a synced block pattern in WordPress requires inserting a wp_block post into the database. If a pattern is defined in a theme file under patterns/, WordPress treats it as an unsynced block pattern. Orbit bridges this gap by automatically discovering theme patterns marked Synced: true and syncing them to real wp_block database records at runtime.

Authoring Synced Patterns

To mark a theme pattern file for runtime synchronisation:

1. Create a pattern file under your theme's patterns/ directory (e.g. patterns/feature-cards.php).
2. Add Synced: true (or yes / 1) to the pattern header block:

<?php
/**
 * Title: Feature Cards
 * Slug: mytheme/feature-cards
 * Categories: featured
 * Synced: true
 */
?>
<!-- wp:group {"metadata":{"name":"Feature Cards"}} -->
<div class="wp-block-group">
    <!-- wp:heading {"metadata":{"name":"Card Title 1"},"bindings":{"ariaLabel":{"label":{"source":"core/pattern-overrides"}}}} -->
    <h2>Card Title</h2>
    <!-- /wp:heading -->
</div>
<!-- /wp:group -->

3. Mark overridable inner content using WordPress pattern override bindings (core/pattern-overrides).

Override Naming Stability Contract

Always specify a stable, explicit metadata.name value (e.g. Card Title 1) for every overridable block in your theme pattern file.

The metadata.name acts as the persistent key connecting instance content overrides stored in post markup to the template structure. Renaming a block's metadata.name in a theme update will orphan existing content overrides across the site.

Runtime Synchronisation Architecture

Orbit synchronises patterns during the init action (priority 20, immediately after core registers theme patterns):

Theme File (patterns/*.php)
       │
       ▼
 [File Fingerprint Cache Check]
       │
  ┌────┴──────────────────────────┐
  │ Cache Match                   │ Cache Miss / Files Changed
  ▼                               ▼
Register Block Refs         Full Pattern Sync
(No DB writes / includes)   • Upsert matching `wp_block` post
                            • Store md5 content hash & slug meta
                            • Update `orbit_synced_theme_patterns_cache`
                            • Register block ref

Fingerprint Caching

To ensure zero performance overhead on regular page renders, Orbit computes a lightweight file fingerprint combining:

• Active stylesheet and template theme names
• The modification time (mtime) and file size (filesize) of every pattern PHP file in the theme and parent theme.

If the fingerprint matches the stored orbit_synced_theme_patterns_cache option, Orbit skips file parsing and database checks entirely, re-registering in-memory core/block references directly from the cache.

When pattern files are edited or deployed, the fingerprint changes, triggering a full sync to update wp_block posts and refresh the cache.

Site Editor Protection & REST Restrictions

To maintain version control integrity, REST API requests (PUT or PATCH) that attempt to update Orbit-managed wp_block posts via the Site Editor are rejected with a 403 Forbidden error by default.

Theme pattern files must remain the source of truth; edit the theme file directly rather than attempting to edit the synced layout in the Site Editor.

Block Theme Developer Compatibility

When using the Block Theme Developer plugin during local development, REST updates are permitted in file-export mode via the orbit_allow_theme_synced_pattern_updates filter so pattern changes made in the editor can be saved back to theme files.

Orbit vs Block Theme Developer

Tool	Environment	Primary Responsibility
Orbit	All environments (Production, Staging, Local)	Automatic runtime sync: theme Synced pattern files → wp_block posts
Block Theme Developer	Local development only	Editor authoring, export, and writing back patterns/templates to theme files

Do not rely on developer tooling plugins for production synchronisation. Orbit handles production runtime sync automatically.

When to Use Synced Patterns

• Use Synced Patterns: For reusable layout components (e.g. call-to-action bands, hero headers, feature card grids) that should maintain consistent site-wide design, layout, and structure while allowing specific text or images to be customised per page via pattern overrides.
• Leave Unsynced: For complete page scaffolds or one-off layouts. (For un-synced structural protection, use WordPress contentOnly editing locks).

Cache Invalidation & Troubleshooting

• Theme Switching: Orbit automatically clears the pattern cache when switching active themes (after_switch_theme).
• Manual Invalidation: To force an immediate re-sync, delete the WordPress option:

  delete_option( 'orbit_synced_theme_patterns_cache' );

• Filter Overrides: Use orbit_enable_synced_theme_patterns to disable the feature entirely:

  add_filter( 'orbit_enable_synced_theme_patterns', '__return_false' );