uupd/README.md

UUPD: Universal Updater Drop-In for WordPress Plugins & Themes

 

UUPD is a lightweight and flexible update manager for WordPress plugins and themes. It supports both GitHub-hosted projects and private update servers, with optional metadata caching and update debugging. The system is designed to work seamlessly for plugin developers who want to manage updates outside of WordPress.org.

 

✨ Key Features

• Works with both GitHub Releases and custom/private update servers

• Uses native WordPress update hooks for seamless integration

• Caches metadata with transients to reduce API usage

• Manual "Check for updates" link added under plugin row

• Lightweight and dependency-free

• Optional GitHub token override for authenticated API calls

 

📚 Additional Documentation

Looking for advanced usage, examples, or integration guides?

We've moved detailed and optional developer information into the docs/ folder for clarity.

Here you'll find:

These documents are optional but helpful if you're customizing UUPD for staging sites, beta testers, private update servers, or power-user workflows.

 

⚙️ Setup

 

1. Add the Updater File

Copy includes/updater.php into your plugin or theme directory.

 

2. Plugin Integration

In your main plugin file (e.g. my-plugin.php):

add_action( 'plugins_loaded', function() {
    require_once __DIR__ . '/includes/updater.php';

    \UUPD\V1\UUPD_Updater_V1::register([
        'plugin_file'     => plugin_basename( __FILE__ ),      // Required: "my-plugin/my-plugin.php"
        'slug'            => 'example-plugin',                 // Required: must match plugin slug or folder
        'name'            => 'Example Plugin',                 // Required: shown in update UI
        'version'         => '1.0.0',                          // Required: current plugin version
        'server'          => 'https://raw.githubusercontent.com/your-user/example-plugin/main/uupd/',

        // Optional keys:
        'github_token'    => 'ghp_YourTokenHere',              // GitHub token (for private repos or rate limits)
        'key'             => 'YourSecretKeyHere',              // Optional secret for private servers
        'textdomain'      => 'example-plugin',                 // Optional, defaults to slug
        'allow_prerelease'=> false,                            // Optional: allow beta/rc versions (default: false)
    ]);
}, 20); // You may increase this priority to allow filter overrides earlier

 

3. Theme Integration

In your theme's functions.php:

add_action( 'after_setup_theme', function() {
    require_once get_stylesheet_directory() . '/includes/updater.php';

    $updater_config = [
        'slug'            => 'example-theme',                 // Required: theme folder name
        'name'            => 'Example Theme',                 // Required: shown in update UI
        'version'         => '1.0.0',                         // Required: should match style.css Version
        'server'          => 'https://raw.githubusercontent.com/your-user/example-theme/main/uupd/',

        // Optional keys:
        'github_token'    => 'ghp_YourTokenHere',             // GitHub token (for private or rate-limited repos)
        'key'             => 'YourSecretKeyHere',             // Optional secret key for private update servers
        'textdomain'      => 'example-theme',                 // Optional, defaults to slug
        'allow_prerelease'=> false,                           // Optional: enable beta/rc updates (default: false)
    ];

    add_action( 'admin_init', function() use ( $updater_config ) {
        \UUPD\V1\UUPD_Updater_V1::register( $updater_config );
    } 20);  // Feel free to raise this priority for more override control
});

 

📁 Hosting Your Update Metadata

 

You can generate the required index.json using the generate_index.php script:

Inputs Required:

• plugin.php file

• changelog.txt

• GitHub username

• Repo name

Output:

• index.json with plugin metadata

• Optional: info.txt for direct integration URL

This can be hosted anywhere:

• GitHub (via raw.githubusercontent.com)

• Static sites (e.g. Cloudflare Pages)

• PHP endpoint (compatible with WP Update Server or similar)

• Wordpress Site using the simple-update-server

 

🚀 Example JSON URL

 

https://raw.githubusercontent.com/your-user/your-plugin/main/uupd/index.json

Include this as the server in your UUPD config to allow automatic updates.

 

📈 Debugging

Enable debug logging:

add_filter( 'updater_enable_debug', fn( $e ) => true );

Also in wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );

 

🔗 Compatibility

• WordPress 5.8+

• PHP 7.4+

• Compatible with WP-Cron, wp_update_plugins() and most deployment workflows

 

✨ Credits

Created by Really Useful Plugins. Inspired by simplicity and the desire to empower developers with GitHub or private updates—without lock-in.

You can view a dummy plugin using this exact updater and its used for testing new versions here:

Plugin: https://github.com/stingray82/example-plugin/
Updates: https://raw.githubusercontent.com/stingray82/example-plugin/main/uupd/index.json

 

Please if your editing the main update scope it read this article here for information and details on why you should scope if your not using standard

 

🎉 Happy Updating!