Suma Patches

Overview

Suma Patches is a WordPress plugin that applies Rhino Group standard customizations to WordPress core, admin, and third-party plugin functionality. It provides centralized control over common site modifications without editing core files.

Plugin Details

Plugin Name: Suma Patches
Version: 1.5.19
Developer: Rhino Group
Location: wp-content/plugins/suma-patches/
Namespace: Suma\Patches\

Purpose

This plugin serves as a single source of truth for:

WordPress admin customizations
Frontend behavior modifications
Third-party plugin compatibility fixes
Performance optimizations
Security enhancements

Architecture

Main Plugin File

File: suma-patches.php

namespace Suma;

class Patches {
    public function init() {
        require_once( 'inc/class-system.php' );
        require_once( 'inc/class-admin.php' );
        require_once( 'inc/class-frontend.php' );
        require_once( 'inc/class-images.php' );
        require_once( 'inc/class-woocommerce.php' );
        require_once( 'inc/class-algolia.php' );
        
        new Patches\System();
        new Patches\Admin();
        new Patches\Frontend();
        new Patches\Images();
        new Patches\WooCommerce();
        new Patches\Algolia();
    }
}

Module Classes

Located in inc/:

File	Purpose
`class-system.php`	System-level customizations
`class-admin.php`	WordPress admin modifications
`class-frontend.php`	Public-facing changes
`class-images.php`	Image handling optimizations
`class-woocommerce.php`	WooCommerce compatibility (if present)
`class-algolia.php`	Algolia search customizations
`class-dev.php`	Development-only features (optional)

Module: Frontend

File: inc/class-frontend.php

Features

1. Custom Head Scripts

Hook: wp_head
Option: suma_head_scripts

Injects custom scripts into <head> section, such as:

Tracking pixels
Analytics code
Verification meta tags
Custom CSS

2. Google Analytics Integration

Hook: wp_head
Option: suma_ga_code

Automatically injects Google Analytics (legacy gtag.js) when GA tracking ID is configured:

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_CODE"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'GA_CODE');
</script>

Note: This is supplementary to GTM4WP; used for additional tracking needs.

Hook: wp_footer
Option: suma_footer_scripts

Injects custom scripts before </body>, such as:

Chat widgets
Exit-intent popups
Additional tracking scripts

4. WP Rocket Cache Control

Hook: wp (priority 999)
Option: suma_wprocket_cache_disabled

When set to 'yes', automatically clears WP Rocket cache on every page load:

if ( 'yes' == get_option( 'suma_wprocket_cache_disabled' ) ) {
    if ( function_exists( 'rocket_clean_minify' ) ) {
        rocket_clean_minify();
    }
    if ( function_exists( 'rocket_clean_domain' ) ) {
        rocket_clean_domain();
    }
}

Use Case: During active development or debugging, disable caching temporarily.

Module: Algolia

File: inc/class-algolia.php

HTTP Client Customization

Hook: algolia_http_client_options

Sets the HTTP referrer header for Algolia API requests to match the WordPress site domain:

public function update_algolia_referrer($options){
    $urlparts = wp_parse_url(home_url());
    $domain = $urlparts['host'];
    $options['CURLOPT_REFERER'] = $domain;
    return $options;
}

Purpose: Ensures Algolia API requests are properly attributed to the site, helpful for multi-site Algolia setups.

Module: WooCommerce

File: inc/class-woocommerce.php

Email Sent Order Notes

Hook: woocommerce_email_sent

Automatically adds order notes when WooCommerce emails are sent:

public function add_note_on_email_sent( $success, $email_id, $email ) {
    if ($email->object instanceof \WC_Order) {
        $order = $email->object;
        $order->add_order_note(
            sprintf(
                __( '%s email sent to customer.', 'woocommerce' ),
                $email->get_title()
            )
        );
    }
}

Benefit: Provides audit trail of customer communications in order history.

Note: While WooCommerce is not currently active on Walkers (using BigCommerce), this module exists for compatibility if WC is enabled.

Module: Admin

File: inc/class-admin.php

Typical Admin Customizations

While specific implementation varies per site, common admin patches include:

Dashboard widgets: Remove or add custom widgets
Admin menu: Hide/reorder menu items
Editor features: Remove unwanted TinyMCE buttons
Admin notices: Suppress update nags
User roles: Custom capability adjustments
Login page: Custom logo and styling

Module: Images

File: inc/class-images.php

Image Handling Optimizations

Common image-related patches:

Upload restrictions: Limit file types or sizes
Image sizes: Register custom thumbnail sizes
Compression: Adjust default JPEG quality
Lazy loading: Enforce lazy loading attributes
SVG support: Enable SVG uploads (with sanitization)

Module: System

File: inc/class-system.php

System-Level Modifications

Core WordPress behavior adjustments:

Disable REST API: For specific endpoints or users
Heartbeat control: Adjust admin-ajax polling frequency
Disable embeds: Remove oEmbed functionality
Disable emojis: Remove emoji scripts/styles
XML-RPC: Disable XML-RPC for security
File editor: Disable theme/plugin file editors
Auto-updates: Control core/plugin/theme updates

Configuration

Admin Settings Panel

Custom settings are managed via WordPress options:

Option Key	Type	Purpose
`suma_head_scripts`	Textarea	Scripts injected in `<head>`
`suma_footer_scripts`	Textarea	Scripts injected before `</body>`
`suma_ga_code`	Text	Google Analytics tracking ID
`suma_wprocket_cache_disabled`	Checkbox	Disable WP Rocket caching
`suma_settings_misc`	Array	Miscellaneous settings

Accessing Settings

// Get head scripts
$head_scripts = get_option('suma_head_scripts');

// Get misc settings array
$misc_settings = get_option('suma_settings_misc') ?: [];
$autohide = $misc_settings['header_autohide_on_scroll'] ?? 'no';

Use Cases

Example 1: Add Custom Tracking Script

Admin → Suma Patches → Head Scripts:

<!-- Facebook Pixel -->
<script>
!function(f,b,e,v,n,t,s)
{if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};
if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];
s.parentNode.insertBefore(t,s)}(window, document,'script',
'https://connect.facebook.net/en_US/fbevents.js');
fbq('init', 'YOUR_PIXEL_ID');
fbq('track', 'PageView');
</script>

Example 2: Temporarily Disable Caching

During active development:

Go to Suma Patches settings
Check "Disable WP Rocket Cache"
Save settings

All page loads will clear cache until unchecked.

Example 3: Fix Algolia Referrer Issue

If Algolia API requests are being blocked or misattributed, the Algolia module automatically sets the correct referrer header based on the WordPress site URL.

Filters & Actions

Available Hooks

Custom hooks provided by Suma Patches:

Actions:

suma_patches_init — Fired after all modules initialized
suma_patches_before_head_scripts — Before head scripts output
suma_patches_after_footer_scripts — After footer scripts output

Filters:

suma_patches_head_scripts — Modify head scripts before output
suma_patches_footer_scripts — Modify footer scripts before output
suma_patches_ga_code — Modify GA tracking ID

Example Usage

// Customize head scripts
add_filter('suma_patches_head_scripts', function($scripts) {
    $scripts .= '<!-- Custom addition -->';
    return $scripts;
});

// Add custom initialization
add_action('suma_patches_init', function() {
    // Your custom code
});

Performance Considerations

Cache Control Warning

Disabling WP Rocket cache via Suma Patches should only be used temporarily during development. Leaving it enabled in production significantly impacts performance.

Best Practice:

Use cache control sparingly
Re-enable caching before deploying to production
Use cache exclusions for specific pages instead

Script Injection

Scripts injected via Suma Patches are not minified or combined with other assets. For production use:

Minimize custom script size
Use async/defer attributes where appropriate
Consider moving scripts to theme's compiled assets for better performance

Security Considerations

Script Sanitization

Warning: Scripts entered in Suma Patches settings are output directly without sanitization. Only allow trusted administrators to access these settings.

Recommended:

Restrict settings page to admin role
Use unfiltered_html capability checks
Audit script contents regularly

WP Rocket Cache Bypass

The cache disable feature is powerful but can be exploited if settings are not properly protected. Ensure admin access is limited to trusted users only.

Troubleshooting

Scripts Not Appearing

Check script is saved in correct option (suma_head_scripts or suma_footer_scripts)
Verify wp_head and wp_footer hooks are present in theme
Clear all caches (page cache, object cache, browser cache)
Check for JavaScript errors blocking execution

Cache Control Not Working

Verify WP Rocket is installed and active
Check option suma_wprocket_cache_disabled is set to 'yes' (string, not boolean)
Confirm functions rocket_clean_minify and rocket_clean_domain exist
Check for conflicting cache plugins

Algolia Referrer Issues

If Algolia requests still failing:

Check algolia_http_client_options filter is firing
Verify domain parsing is correct: wp_parse_url(home_url())
Check Algolia dashboard for request logs
Ensure Algolia API key has correct referrer restrictions

Version History

Version 1.5.19 (Current)

Current stable version
All documented features active

Development

Adding New Patches

To add a new system-wide patch:

Identify the patch need: What core behavior needs modification?
Choose appropriate module: System, Admin, Frontend, Images, etc.
Add hook/filter: Implement in module class constructor
Test thoroughly: Verify patch works without side effects
Document: Update plugin documentation

Example: Add New Frontend Patch

// File: inc/class-frontend.php

public function __construct() {
    // Existing hooks...
    
    // New patch: Remove query strings from static resources
    add_filter('script_loader_src', [$this, 'remove_query_strings'], 15, 1);
    add_filter('style_loader_src', [$this, 'remove_query_strings'], 15, 1);
}

public function remove_query_strings($src) {
    if (strpos($src, '?ver=')) {
        $src = remove_query_arg('ver', $src);
    }
    return $src;
}

Next Steps

Theme Customizations — How theme uses Suma Patches settings
Development Setup — Testing patches locally

Overview​

Plugin Details​

Purpose​

Architecture​

Main Plugin File​

Module Classes​

Module: Frontend​

Features​

1. Custom Head Scripts​

2. Google Analytics Integration​

3. Custom Footer Scripts​

4. WP Rocket Cache Control​

Module: Algolia​

HTTP Client Customization​

Module: WooCommerce​

Email Sent Order Notes​

Module: Admin​

Typical Admin Customizations​

Module: Images​

Image Handling Optimizations​

Module: System​

System-Level Modifications​

Configuration​

Admin Settings Panel​

Accessing Settings​

Use Cases​

Example 1: Add Custom Tracking Script​

Example 2: Temporarily Disable Caching​

Example 3: Fix Algolia Referrer Issue​

Filters & Actions​

Available Hooks​

Example Usage​

Performance Considerations​

Cache Control Warning​

Script Injection​

Security Considerations​

Script Sanitization​

WP Rocket Cache Bypass​

Troubleshooting​

Scripts Not Appearing​

Cache Control Not Working​

Algolia Referrer Issues​

Version History​

Version 1.5.19 (Current)​

Development​

Adding New Patches​

Example: Add New Frontend Patch​

Next Steps​