A reusable WordPress plugin updater class that handles automatic updates from GitHub repositories using the yahnis-elsts/plugin-update-checker library.
- Quick Start
- Configuration Parameters
- GitHub Workflow for Automatic Release Assets
- Usage Examples
- Customizing the Class
- Dependencies
- Key Features
- Best Practices
- Error Handling
- License
Copy class-github-plugin-updater.php to your plugin directory.
if ( ! class_exists( 'Soderlind\WordPress\GitHub_Plugin_Updater' ) ) { require_once 'class-github-plugin-updater.php'; }<?php $updater = \Soderlind\WordPress\GitHub_Plugin_Updater::create( 'https://github.com/username/plugin-name', __FILE__, 'plugin-name' );<?php $updater = \Soderlind\WordPress\GitHub_Plugin_Updater::create( 'https://github.com/username/plugin-name', __FILE__, 'plugin-name', 'develop' // Branch name );<?php $updater = \Soderlind\WordPress\GitHub_Plugin_Updater::create_with_assets( 'https://github.com/username/plugin-name', __FILE__, 'plugin-name', '/plugin-name\.zip/' // Regex pattern for zip file );<?php $updater = new \Soderlind\WordPress\GitHub_Plugin_Updater( array( 'github_url' => 'https://github.com/username/plugin-name', 'plugin_file' => __FILE__, 'plugin_slug' => 'plugin-name', 'branch' => 'main', 'name_regex' => '/plugin-name-v[\d\.]+\.zip/', 'enable_release_assets' => true, ) );| Parameter | Required | Description | Example |
|---|---|---|---|
github_url | Yes | GitHub repository URL | 'https://github.com/username/plugin-name' |
plugin_file | Yes | Path to main plugin file | __FILE__ or PLUGIN_CONSTANT_FILE |
plugin_slug | Yes | Plugin slug for WordPress | 'my-awesome-plugin' |
branch | No | Git branch to check for updates | 'master' (default), 'main', 'develop'.Caveat: If you set the branch to master , the update checker will look for recent releases and tags first. It'll only use the master branch if it doesn't find anything else suitable. |
name_regex | No | Regex pattern for release assets | '/plugin-name\.zip/' |
enable_release_assets | No | Whether to enable release assets | true if name_regex provided |
To automatically create zip files when you publish a GitHub release, include this workflow file in your repository. This is especially useful when using the name_regex parameter to filter release assets.
name: On Release, Build release zip on: release: types: [published] jobs: build: name: Build release zip runs-on: ubuntu-latest permissions: contents: write steps: - name: Checkout uses: actions/checkout@v4 - name: Build plugin # Remove or modify this step as needed run: | composer install --no-dev - name: Archive Release uses: thedoctor0/zip-release@b57d897cb5d60cb78b51a507f63fa184cfe35554 #0.7.6 with: type: 'zip' filename: 'your-plugin-name.zip' # Change this to match your plugin exclusions: '*.git* .editorconfig composer* *.md package.json package-lock.json' - name: Release uses: softprops/action-gh-release@c95fe1489396fe8a9eb87c0abf8aa5b2ef267fda #v2 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: files: your-plugin-name.zip # Change this to match your plugin tag_name: ${{ github.event.release.tag_name }}- Trigger: Automatically runs when you publish a GitHub release
- Build: Installs production dependencies with
composer install --no-dev - Archive: Creates a zip file excluding development files
- Attach: Adds the zip file to the GitHub release as an asset
- Change filename: Update both
filename:andfiles:to match your plugin name - Modify exclusions: Add or remove files/patterns from the
exclusions:list - Build step: Modify the build process (npm, webpack, etc.) as needed for your plugin
After the workflow runs, your release assets will be available at URLs like:
https://github.com/username/plugin-name/releases/latest/download/plugin-name.zip Real example from this plugin:
https://github.com/soderlind/additional-javascript/releases/latest/download/additional-javascript.zip When using release assets, configure your updater like this:
<?php $updater = \Soderlind\WordPress\GitHub_Plugin_Updater::create_with_assets( 'https://github.com/username/plugin-name', __FILE__, 'plugin-name', '/plugin-name\.zip/' // This regex will match the zip created by the workflow );<?php // In your main plugin file define( 'MY_PLUGIN_FILE', __FILE__ ); require_once plugin_dir_path( __FILE__ ) . 'class-github-plugin-updater.php'; $my_plugin_updater = \Soderlind\WordPress\GitHub_Plugin_Updater::create( 'https://github.com/myusername/my-awesome-plugin', MY_PLUGIN_FILE, 'my-awesome-plugin' );<?php $updater = \Soderlind\WordPress\GitHub_Plugin_Updater::create_with_assets( 'https://github.com/company/enterprise-plugin', __FILE__, 'enterprise-plugin', '/enterprise-plugin-v[\d\.]+\.zip/', 'release' // Custom branch );<?php // Plugin A $plugin_a_updater = \Soderlind\WordPress\GitHub_Plugin_Updater::create_with_assets( 'https://github.com/mycompany/plugin-suite', plugin_dir_path( __FILE__ ) . 'plugin-a/plugin-a.php', 'plugin-a', '/plugin-a\.zip/' ); // Plugin B $plugin_b_updater = \Soderlind\WordPress\GitHub_Plugin_Updater::create_with_assets( 'https://github.com/mycompany/plugin-suite', plugin_dir_path( __FILE__ ) . 'plugin-b/plugin-b.php', 'plugin-b', '/plugin-b\.zip/' );<?php $updater = new \Soderlind\WordPress\GitHub_Plugin_Updater( array( 'github_url' => 'https://github.com/mycompany/premium-plugin', 'plugin_file' => __FILE__, 'plugin_slug' => 'premium-plugin', 'branch' => 'stable', 'name_regex' => '/premium-plugin-pro-v[\d\.]+\.zip/', 'enable_release_assets' => true, ) );If you want to avoid conflicts, rename the class:
<?php namespace YourCompany\YourPlugin; use YahnisElsts\PluginUpdateChecker\v5\PucFactory; class Your_Plugin_Updater extends \Soderlind\WordPress\GitHub_Plugin_Updater { // Inherit all functionality, customize as needed }Create a plugin-specific version:
<?php namespace YourCompany\YourPlugin; class Your_Plugin_Updater { private $updater; public function __construct() { $this->updater = \Soderlind\WordPress\GitHub_Plugin_Updater::create( 'https://github.com/yourcompany/your-plugin', YOUR_PLUGIN_FILE, 'your-plugin' ); } }This updater requires the yahnis-elsts/plugin-update-checker library:
composer require yahnis-elsts/plugin-update-checkerOr download it manually from: https://github.com/YahnisElsts/plugin-update-checker
- ✅ Automatic updates from GitHub releases
- ✅ Custom branch support for development/staging
- ✅ Release asset filtering with regex patterns
- ✅ Error handling with debug logging
- ✅ Multiple initialization methods (static factories)
- ✅ Parameter validation with meaningful error messages
- ✅ Flexible configuration options
- ✅ Fully documented with examples
- Use Constants: Define your plugin file as a constant for consistency
- Static Factory Methods: Use
::create()methods for simpler initialization - Error Handling: The updater includes proper validation and debug logging
- Testing: Test with different branch names and release asset patterns
- Documentation: Document your specific configuration for future reference
- Namespace: Consider using your own namespace to avoid conflicts
The GitHub_Plugin_Updater class includes robust error handling:
- Parameter Validation: Required parameters are validated on construction
- Exception Handling: Gracefully handles errors during update check setup
- Debug Logging: Errors are logged when
WP_DEBUGis enabled - Graceful Degradation: Plugin continues to work even if updater fails
GPL-2.0+ (same as the original plugin)