WPCalibrate ShareBrand – Social Images

Automate high-converting, branded social sharing images (Open Graph & X/Twitter Large Cards) for your WordPress posts, pages, and WooCommerce products. Features custom watermarking, split branded card generation, a live multi-platform feed simulator, and seamless integration with all major WordPress SEO plugins.

---

Table of Contents

• About
• Features
• Architecture & Performance
• Documentation
  • System Requirements
  • Installation
  • Updating via WordPress Dashboard
  • Configuration Guide
  • Developer Hooks & Filters
• Changelog
• Contributing & Support
• License

---

About

When articles or products are shared across social channels (LinkedIn, X/Twitter, Facebook, Slack, Discord, and iMessage), social network crawlers request Open Graph (og:image) and Twitter Card (twitter:image) metadata tags.

Without dedicated branding:

• Social shares display generic, unbranded thumbnails or awkward image crops.
• Real-time on-the-fly image generators strain web servers, exhaust PHP memory limits, and cause crawler timeouts that result in missing previews.
• Custom-coded solutions often overwrite original Media Library uploads or output duplicate Open Graph tags that conflict with existing SEO plugins.

WPCalibrate ShareBrand – Social Images solves this cleanly. It creates crisp, pre-rendered 1200×630 social cards in the background, caches them in a dedicated directory, detects content updates via deterministic SHA-256 signatures, and injects images into your existing SEO plugins without ever touching your original media.

---

Features

1. Dual Branding Engines

• Watermark Mode:
  • Scales and crops the source image to standard social card dimensions (1200×630 or custom dimensions).
  • Overlays your brand logo onto any of 9 anchor positions (Top-Left, Top-Center, Top-Right, Center-Left, Center, Center-Right, Bottom-Left, Bottom-Center, Bottom-Right).
  • Fully configurable logo sizing (percentage of canvas width), opacity (10% to 100%), and boundary padding.
• Branded Card Mode:
  • Generates a modern split-card layout (1.91:1 aspect ratio).
  • Left panel features your customizable brand background color, dynamic post title with automated multi-line word wrapping and font scaling, domain watermark, and contrast-aware brand badge.
  • Right panel showcases the post's featured image framed with Cover or Contain fitting strategies.
  • Automatic luminance detection: Cards automatically select dark or light logos based on background color luminance to guarantee high contrast.

2. Interactive Preview & Test Workbench

• Live Social Feed Simulator:
  • Interactive live preview mocking exact feed presentations for Facebook / Open Graph, X / Twitter Large Summary Cards, and LinkedIn Posts.
  • Toggle between Branded Card Mode and Watermark Mode in real time.
  • Live title and position testing.
• Server Engine Test Generator:
  • Run the actual server-side GD/Imagick canvas pipeline with one click.
  • Real-time telemetry reporting generation duration in milliseconds, rendered file size, pixel dimensions, image MIME type, and SHA-256 signature hash.
• Content Post & Product Inspector:
  • Look up any published post, page, or WooCommerce product.
  • Inspect resolved source image types, generation status, and final HTML meta tags.
  • Direct one-click links to external validator tools: Facebook Sharing Debugger, Twitter Card Validator, and LinkedIn Post Inspector.

3. Performance & Background Processing

• Deterministic SHA-256 Signatures:
  • Every image signature incorporates source attachment ID, source modification time, title, branding settings, logo ID, and dimensions.
  • Re-saving a post without modifying the title or image skips generation, consuming zero server CPU.
• Asynchronous Queue:
  • Dispatches generation jobs in the background upon post save.
  • Automatically utilizes Action Scheduler when available (e.g. WooCommerce), falling back seamlessly to native WP-Cron.
  • Atomic transient locks (wpcalibrate_sb_lock_{id}) prevent race conditions and duplicate concurrent processing.
• Zero Original Media Modification:
  • Original featured images and Media Library assets are never permanently edited, cropped, or overwritten. Generated files reside in /wp-content/uploads/wpcalibrate-sharebrand/.

4. SEO Plugin Adapters (Zero Tag Conflicts)

ShareBrand includes dedicated adapters for all leading WordPress SEO plugins:

• Yoast SEO (wpseo_opengraph_image, wpseo_twitter_image)
• Rank Math (rank_math/opengraph/facebook/image, rank_math/opengraph/twitter/image)
• All in One SEO (AIOSEO) (aioseo_facebook_tags, aioseo_twitter_tags)
• SEOPress (seopress_social_og_thumb, seopress_social_twitter_card_thumb)
• The SEO Framework (the_seo_framework_og_image_after_eval)

When an SEO plugin is detected, ShareBrand supplies the generated image directly to that plugin's metadata hooks and suppresses its own standalone tags. When no SEO plugin is active, ShareBrand outputs standard Open Graph and Twitter Card tags directly in <head>.

5. WooCommerce Compatible

• Automatically enables social image generation for the product post type when WooCommerce is active.
• Officially declares full compatibility with High-Performance Order Storage (HPOS) (custom_order_tables) and Cart/Checkout Blocks (cart_checkout_blocks).
• Never modifies orders, checkout workflows, carts, or customer session data.

---

Architecture & Performance

Post Save / Update Trigger
            │
            ▼
┌─────────────────────────┐
│ Calculate Deterministic │
│    SHA-256 Signature    │
└───────────┬─────────────┘
            │
      Signature Matches?
     ├── YES ──► [Skip Generation - Image Valid]
     └── NO  ──► Enqueue Background Job
                       │
                       ▼
         ┌───────────────────────────┐
         │ Action Scheduler / WP-Cron│
         │   (Atomic Lock Applied)   │
         └─────────────┬─────────────┘
                       │
                       ▼
         ┌───────────────────────────┐
         │  GD / Imagick Abstraction │
         │   - Watermark Engine      │
         │   - Branded Card Engine   │
         └─────────────┬─────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│  Save to /uploads/wpcalibrate-sharebrand/    │
│  Update Post Meta & Dispatch Notifications   │
└──────────────────────────────────────────────┘

---

Documentation

System Requirements

• WordPress: 6.4 or higher
• PHP: 8.2 or 8.3 (with GD or Imagick extension enabled)
• WooCommerce: 8.0+ to 11.1+ (optional)

Installation

Method 1: WordPress Admin Upload (Recommended)

1. Download the latest wpcalibrate-sharebrand-1.0.0.zip from Releases.
2. In your WordPress admin, go to Plugins > Add New > Upload Plugin.
3. Select the downloaded ZIP file and click Install Now.
4. Click Activate Plugin.

Method 2: Manual FTP / SFTP

1. Extract the wpcalibrate-sharebrand-1.0.0.zip archive.
2. Upload the wpcalibrate-sharebrand directory to /wp-content/plugins/.
3. Activate the plugin via Plugins in your WordPress dashboard.

---

Updating via WordPress Dashboard

This repository includes native WordPress update headers:

• Update URI: https://github.com/zeeshanraza-official/wpcalibrate-sharebrand
• GitHub Plugin URI: https://github.com/zeeshanraza-official/wpcalibrate-sharebrand
• Primary Branch: main

To receive automatic one-click updates directly inside your WordPress dashboard:

1. Install the free Git Updater plugin on your WordPress site.
2. WPCalibrate ShareBrand will automatically appear in your WordPress updates list whenever a new release tag or commit is published to this GitHub repository.
3. Simply click Update Now in Dashboard > Updates or Plugins.

---

Configuration Guide

Navigate to WPCalibrate > ShareBrand in your WordPress admin menu:

1. Overview Tab: Displays overall system status, total images generated, active background scheduler, and storage usage.
2. Image Settings Tab:
   • Set Default Branding Mode (Watermark Mode or Branded Card Mode).
   • Set Dimensions (default 1200 × 630 px).
   • Set Output Format (JPEG or PNG) and Compression Quality (default 85%).
   • Choose Source Image Fit Strategy (Cover or Contain).
   • Upload a Global Fallback Image for content without featured images.
3. Branding Tab:
   • Upload your Brand Logo (PNG with transparent background recommended).
   • Configure Watermark Position, Opacity, and Margin.
   • Configure Card Background Color, Font Size, and Domain Watermark text.
4. Preview & Test Tab:
   • Live multi-platform feed simulator (Facebook, Twitter/X, LinkedIn).
   • One-click Server Engine Test Generator.
   • Post and WooCommerce Product Inspector with sharing debugger links.
5. Content Types Tab: Enable or disable social image generation per post type (Posts, Pages, WooCommerce Products).
6. Social Meta Tab: Configure fallback site name, default card type (summary_large_image), and tag behavior.
7. Integrations Tab: View detected SEO plugins and active integration status.
8. Regeneration Tab: Run batched bulk regeneration across existing content with live progress bar.
9. Diagnostics Tab: View detailed PHP extensions, upload folder permissions, FreeType support, and memory limits.

---

Developer Hooks & Filters

Filters

// Modify branding settings dynamically before generation
add_filter( 'wpcalibrate_sharebrand_branding_settings', function( array $settings, int $post_id ): array {
    if ( is_singular( 'product' ) ) {
        $settings['brand_card_bg_color'] = '#1a1a2e';
    }
    return $settings;
}, 10, 2 );

// Override resolved source image attachment ID
add_filter( 'wpcalibrate_sharebrand_source_image_id', function( int $attachment_id, int $post_id ): int {
    $custom_hero = get_post_meta( $post_id, '_my_custom_hero_id', true );
    return $custom_hero ? (int) $custom_hero : $attachment_id;
}, 10, 2 );

// Customize branded card title or domain label
add_filter( 'wpcalibrate_sharebrand_card_args', function( array $args, int $post_id ): array {
    $args['domain_text'] = strtoupper( wp_parse_url( home_url(), PHP_URL_HOST ) );
    return $args;
}, 10, 2 );

Actions

// Fires after a social image is successfully generated and stored
add_action( 'wpcalibrate_sharebrand_image_generated', function( int $post_id, string $image_url, string $file_path, string $signature ): void {
    // Purge external CDN cache or notify third-party service
}, 10, 4 );

// Fires when an existing social image is invalidated
add_action( 'wpcalibrate_sharebrand_image_invalidated', function( int $post_id ): void {
    // Handle image cache invalidation
}, 10, 1 );

---

Changelog

1.0.0 — 2026-10-05

• Initial Production Release.
• Watermark Mode with 9 anchor positions, opacity slider, and margin controls.
• Branded Card Mode (1200×630 split design) with automated multi-line word wrapping and contrast-aware logo rendering.
• Interactive Preview & Test Workbench featuring multi-platform social feed simulator (Facebook/OG, X/Twitter, LinkedIn).
• Server Engine Test Generator executing real GD/Imagick canvas pipelines with real-time telemetry.
• Post & WooCommerce Product Inspector with direct links to external sharing debuggers.
• Deterministic SHA-256 generation signatures for zero redundant re-processing.
• Background asynchronous queue with Action Scheduler and WP-Cron fallback.
• Batched Bulk Regenerator with live progress tracking and cancellation support.
• Native adapters for Yoast SEO, Rank Math, All in One SEO, SEOPress, and The SEO Framework.
• WooCommerce Product compatibility with HPOS (custom_order_tables) and Cart/Checkout Blocks declarations.
• High-resolution WPCalibrate admin branding with scoped CSS menu constraints.
• Post-Redirect-Get (PRG) settings architecture with transient notices.
• FreeType TTF error hardening and dynamic asset versioning (filemtime).

---

Contributing & Support

• Bug Reports & Issues: Please open an issue on the GitHub Issues page.
• Pull Requests: Pull requests are welcome! Please ensure all PHP unit tests pass before submitting.
• Website: WPCalibrate

---

License

WPCalibrate ShareBrand is open-source software licensed under the GPL-2.0-or-later License.