README

A comprehensive WordPress plugin updater library that enables automatic updates, license verification, and remote plugin management for custom WordPress plugins.

Features

• Automatic Plugin Updates: Seamlessly check for and install plugin updates from your remote server
• License Management: Built-in license key verification and validation system
• Admin Interface: Clean WordPress admin interface for license management
• Plugin Tracking: Track plugin activation, deactivation, and usage statistics
• WordPress Integration: Hooks into WordPress core update system
• Flexible Configuration: Customizable API endpoints, menu placement, and licensing options

Requirements

• WordPress 5.0 or higher
• PHP 7.4 or higher
• Valid API server endpoint for plugin updates and license verification

Installation

composer require shazzad/plugin-updater

Quick Start

<?php
// Initialize the updater (autoloaded via Composer)
new \Shazzad\PluginUpdater\Integration(
    'https://your-api-server.com/api',  // API URL
    plugin_basename( __FILE__ ),        // Plugin file path
    'your-product-id',                  // Product ID
    true,                              // Enable licensing
    true,                              // Display admin menu
    'My Plugin License',               // Menu label
    'plugins.php',                     // Parent menu
    10                                 // Menu priority
);

File Structure

/src/
├── Integration.php    # Core state, license helpers, and subsystem wiring
├── Client.php        # API client with typed methods (ping, check_license, updates, details)
├── Updater.php       # Update checks and WordPress integration
├── Admin.php         # WordPress admin interface
└── Tracker.php       # Plugin tracking and license sync

Configuration Options

Constructor Parameters

Example Configurations

Basic Update Checking (No Licensing)

new \Shazzad\PluginUpdater\Integration(
    'https://api.example.com',
    plugin_basename( __FILE__ ),
    'my-plugin-id'
);

Full Featured with Licensing and Metadata

( new \Shazzad\PluginUpdater\Integration(
    'https://api.example.com',
    plugin_basename( __FILE__ ),
    'my-plugin-id',
    true,                           // Enable licensing
    true,                           // Show admin menu
    'My Plugin Updates',            // Menu label
    'tools.php',                    // Under Tools menu
    20                              // Menu priority
) )->setMeta( [
    'php_version' => function () { return phpversion(); },
    'theme'       => function () { return get_stylesheet(); },
] );

API Server Requirements

Your API server should provide the following endpoints:

Update Check Endpoint

GET /products/{product_id}/updates

Response:

{
  "updates": {
    "new_version": "2.1.0",
    "package": "https://download-url.com/plugin.zip",
    "url": "https://plugin-info-url.com",
    "tested": "6.4",
    "requires": "5.0",
    "changelog": "Bug fixes and improvements"
  }
}

Plugin Details Endpoint

GET /products/{product_id}/details

Response:

{
  "details": {
    "name": "My Plugin",
    "version": "2.1.0",
    "author": "Developer Name",
    "homepage": "https://plugin-website.com",
    "sections": {
      "description": "Plugin description",
      "changelog": "Version history",
      "installation": "Installation instructions"
    },
    "download_link": "https://download-url.com/plugin.zip"
  }
}

License Verification Endpoint

GET /products/{product_id}/check_license?license=LICENSE_KEY

Response:

{
  "license": {
    "status": "active",
    "expires": "2024-12-31",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "renewal_url": "https://example.com/renew?license={license_code}&email={email}"
  }
}

The renewal_url field is optional in the license verification response. When present and the license status is expired, a renewal link is displayed on the admin license page. The URL supports two placeholders that are replaced automatically:

• {license_code} — replaced with the stored license key
• {email} — replaced with the buyer_email from the license data

A static URL without placeholders (e.g., https://example.com/renew) is also supported.

Ping Endpoint

POST /products/{product_id}/ping

Used for tracking plugin installations and status. Sends site environment data and optional custom metadata.

Request body:

• product_version: Current plugin version
• product_status: Plugin status (active/inactive)
• wp_url: WordPress site URL
• wp_locale: WordPress locale
• wp_version: WordPress version
• admin_email: Site admin email
• admin_name: First admin user's display name
• meta: Optional key-value pairs of custom metadata

Custom Metadata

You can attach custom metadata to pings using setMeta(). Values can be static or closures — closures are resolved at ping time so data is always fresh.

( new \Shazzad\PluginUpdater\Integration(
    'https://api.example.com',
    plugin_basename( __FILE__ ),
    'my-plugin-id'
) )->setMeta( [
    'php_version'          => function () { return phpversion(); },
    'theme'                => function () { return get_stylesheet(); },
    'memory_limit'         => ini_get( 'memory_limit' ),
    'active_plugins_count' => function () {
        return count( get_option( 'active_plugins' ) );
    },
] );

• Static values (strings, numbers) are sent as-is
• Closures are called at each ping and the return value is sent (only Closure instances, not arbitrary callable strings)
• Metadata is synced on every ping — keys removed from setMeta() are deleted from the server

Request Parameters

API requests to updates, details, and check_license include these query parameters:

• license: License key (if licensing enabled)

WordPress Integration

Hooks and Filters

The updater integrates with WordPress using these hooks:

• pre_set_site_transient_update_plugins: Inject update information
• plugins_api: Provide plugin details for update screen
• upgrader_package_options: Configure upgrade process
• upgrader_process_complete: Handle post-update cleanup
• Plugin activation/deactivation hooks for tracking

Scheduled Tasks

• License Sync: Hourly cron job to verify license status
• Update Checks: Integrated with WordPress core update system

Admin Interface

When licensing is enabled, the updater adds an admin page with:

• License key input field
• License status display
• Update availability notifications
• Direct upgrade buttons
• Changelog and upgrade notices

Menu Placement

By default, the license page appears under Plugins menu. You can customize this:

// Under Tools menu
'menu_parent' => 'tools.php'

// Under Settings menu
'menu_parent' => 'options-general.php'

// Top-level menu
'menu_parent' => null

Security Features

• Input Sanitization: All user inputs are properly sanitized
• Nonce Verification: WordPress nonces protect admin forms
• Capability Checks: Requires delete_users capability for license management
• XSS Protection: Output is escaped using WordPress functions

Error Handling

The updater includes comprehensive error handling:

• API connection failures
• Invalid license keys
• Update server timeouts
• Malformed responses

Errors are logged and displayed appropriately in the WordPress admin.

Changelog

Version 1.1

• Send ping as POST request with admin_email and admin_name
• Add setMeta() for custom install metadata (static values and callables)
• Skip update transient injection when plugin is inactive
• Send ping on hourly cron for licensed plugins

Version 1.0

• Refactored into modular structure
• Improved error handling
• Enhanced security measures
• Better WordPress integration
• Comprehensive documentation

Support

For support and bug reports, please contact your plugin developer or visit the plugin's official support channels.

License

This updater package is typically licensed under the same terms as your main plugin. Check your plugin's license file for specific terms.