README

A small WordPress-only library that enables updates for a plugin from a custom update server.

Requirements

• PHP 8.0+
• WordPress (admin context)

Installation

Packagist / private registry

composer require affinite/updater

Direct VCS repository

{
  "repositories": [
    { "type": "vcs", "url": "git@github.com:YOUR_ORG/affinite-updater.git" }
  ],
  "require": {
    "affinite/updater": "^1.0"
  }
}

Usage (inside your plugin)

Add this code to your plugin's main file:

<?php
use Affinite\Updater\Updater;

try {
    $plugin_slug = dirname( plugin_basename( __FILE__ ) );
    new Updater( $plugin_slug );
} catch ( \Exception $e ) {
    if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
        error_log( 'AffiniteUpdater initialization failed: ' . $e->getMessage() );
    }
}

The plugin_slug is automatically detected from the plugin folder name, so it works regardless of your main file name.

Plugin file detection

The updater automatically finds the plugin main file regardless of its name. It searches in the following order:

1. Standard format: {slug}/{slug}.php (e.g., my-plugin/my-plugin.php)
2. Index file: {slug}/index.php (if it contains a valid WordPress plugin header)
3. WordPress plugin registry: Searches through all registered plugins to find the one matching the folder name

This means you can use any file name for your plugin main file, as long as:

• The plugin folder name matches the slug you pass to Updater
• The main file contains a valid WordPress plugin header (Plugin Name:)

Force check for updates

By default, update checks are cached for 1 hour. To force a fresh check (ignoring cache), use the forceCheck() method:

<?php
use Affinite\Updater\Updater;

$updater = new Updater('my-plugin-slug');

// Force a fresh update check (ignores cache)
$updateData = $updater->forceCheck();

if ($updateData) {
    // Process update data...
    echo 'Latest version: ' . $updateData->version;
}

Update server response

The update server returns JSON responses with a standardized format. All responses include response codes and metadata.

Response format

All API responses follow this structure:

{
  "code": 200,
  "message": "Plugin update available",
  "message_code": "PLUGIN_UPDATE_AVAILABLE",
  "need_license": false
}

Update check response (?plugin=<slug>)

When an update is available, the server returns:

{
  "code": 200,
  "message": "Plugin update available",
  "message_code": "PLUGIN_UPDATE_AVAILABLE",
  "need_license": false,
  "name": "My Plugin",
  "version": "1.2.3",
  "author": "Affinite",
  "author_profile": "https://example.com",
  "requires": "6.0",
  "tested": "6.6",
  "requires_php": "8.0",
  "download_url": "https://example.com/my-plugin.zip",
  "sections": {
    "description": "…",
    "installation": "…",
    "changelog": "…"
  },
  "banners": {
    "low": "https://example.com/banner-772x250.jpg",
    "high": "https://example.com/banner-1544x500.jpg"
  },
  "is_valid_license": true
}

When an update is not available or an error occurs, the server returns HTTP status code 40+ with an error response:

{
  "code": 401,
  "message": "Invalid license",
  "message_code": "INVALID_LICENSE",
  "need_license": true
}

Response codes

The library provides constants for all response message codes:

• Updater::INVALID_REQUEST - Invalid request
• Updater::FILE_NOT_FOUND - File not found
• Updater::INVALID_PLUGIN - Invalid plugin
• Updater::INVALID_PLUGIN_VERSION - Invalid plugin version
• Updater::PLUGIN_PARAMETER_REQUIRED - Plugin parameter is required
• Updater::INVALID_LICENSE - Invalid license
• Updater::LICENSE_ACTIVATION_FAILED - License activation failed
• Updater::LICENSE_PARAMETER_REQUIRED - License parameter is required
• Updater::INVALID_LICENSE_ENDPOINT - Invalid license endpoint
• Updater::LICENSE_ACTIVATED - License activated
• Updater::LICENSE_VALID - License is valid
• Updater::LICENSE_INFO_RETRIEVED - License information retrieved
• Updater::PLUGIN_UPDATE_AVAILABLE - Plugin update available
• Updater::PLUGIN_LIST_GENERATED - Plugin list generated

License management

The updater includes methods for license activation and validation:

Activate license

<?php
use Affinite\Updater\Updater;

$updater = new Updater('my-plugin-slug');
$result = $updater->activateLicense('my-plugin-slug', 'license-key-here');

if ($result->success) {
    echo 'License activated: ' . $result->message;
} else {
    echo 'Activation failed: ' . $result->message;
    echo 'Response code: ' . $result->code;
    echo 'Message code: ' . $result->message_code;
}

The activateLicense() method returns an object with:

• success (bool) - Whether activation was successful
• code (int) - HTTP response code from server
• message (string) - Human-readable message
• message_code (string) - Response code constant (e.g., LICENSE_ACTIVATED)
• need_license (bool) - Whether plugin requires license

Check license

<?php
use Affinite\Updater\Updater;

$updater = new Updater('my-plugin-slug');
$result = $updater->checkLicense('my-plugin-slug', 'license-key-here');

if ($result->valid) {
    echo 'License is valid';
    echo 'Expires: ' . ($result->expires ?? 'Never');
    echo 'Version: ' . ($result->version ?? 'N/A');
} else {
    echo 'License invalid: ' . $result->message;
}

The checkLicense() method returns an object with:

• valid (bool) - Whether license is valid
• code (int) - HTTP response code from server
• expires (string|null) - Expiration date or null for lifetime licenses
• message (string) - Human-readable message
• message_code (string) - Response code constant
• version (string|null) - Plugin version from API response
• need_license (bool) - Whether plugin requires license

HTTP status codes

The updater accepts HTTP status codes 40+ (error responses) in addition to 200 (success). When the server cannot provide a plugin ZIP file, it returns HTTP 40+ with a JSON error response containing the error details.

License validation during updates

When need_license is true in the update response, the updater automatically validates the license before providing the update. If validation fails, the update is not shown to the user. License status is only updated when the license is valid - failed checks do not overwrite existing license status.

License

MIT. See LICENSE.