README

A lite, UI-free Freemius SDK for Duck Dev WordPress plugins. The library handles license activation, deactivation, update delivery, and addon listing by talking to the Freemius API directly. It deliberately ships no admin screens — host plugins build their own UI and call into this library for the underlying logic.

Requirements

• PHP 7.4 or higher
• WordPress 5.0+
• Composer

Installation

composer require duckdev/freemius-plugin-licensing

The library autoloads under the DuckDev\Freemius\ namespace via PSR-4.

Architecture

The library is organised as a small dependency-injection container wired up by the entry class DuckDev\Freemius\Freemius. The folder layout mirrors the namespace:

src/
├── Freemius.php              # Container + entry point
├── Api/
│   ├── Client.php            # Unsigned HTTP client over wp_remote_request
│   ├── SignedClient.php      # Adds FS / FSP signed auth headers
│   ├── RequestSigner.php     # Pure header-signing logic
│   └── ApiFactory.php        # Builds fresh clients per call
├── Contracts/
│   ├── ServiceInterface.php
│   ├── ApiClientInterface.php
│   └── CacheInterface.php
├── Data/
│   ├── Plugin.php            # Immutable host plugin info
│   ├── Activation.php        # Value object around the persisted activation
│   └── ApiKeys.php           # Public / secret key pair
├── Storage/
│   ├── ActivationRepository.php   # Reads / writes the activation option
│   └── TransientCache.php         # Per-plugin transient cache + throttle
├── Services/
│   ├── AbstractService.php
│   ├── License.php           # activate() / deactivate()
│   ├── Update.php            # WP update hooks
│   └── Addon.php             # Addon listing
├── Support/
│   └── SiteIdentity.php      # Deterministic site UID
└── Exceptions/
    └── FreemiusException.php

Each service receives its collaborators by constructor injection, so they can be unit-tested without WordPress in the loop. Hook registration happens inside boot() (called once by the container), so simply instantiating the container has no side effects.

Usage

Initialization

Initialise the container by calling Freemius::get_instance() with your Freemius product ID and an arguments array:

// Assuming Composer's autoload.php has been included.
$freemius = \DuckDev\Freemius\Freemius::get_instance(
    12345, // Your Freemius product ID.
    array(
        'slug'       => 'loggedin',              // Your plugin's unique Freemius slug.
        'main_file'  => LOGGEDIN_FILE,           // Absolute path to the plugin's main file.
        'public_key' => 'pk_XXXXXXXXXXXXXXXXX',  // Plugin public key.
        'is_premium' => true,                    // Whether this build is the premium edition.
        'has_addons' => false,                   // Whether the product has addons to list.
    )
);

The supported arguments are:

The first call to get_instance() creates the container and registers WordPress hooks. Subsequent calls for the same plugin ID return the existing instance (the second argument is ignored after the first call).

License Activation

$result = $freemius->license()->activate( 'XXXX-XXXX-XXXX' );

if ( is_wp_error( $result ) ) {
    // $result->get_error_message() — show to the user.
}

activate() returns true / false from the option update on success, or a WP_Error when the key is empty, the plugin is not the premium build, the API call fails, or the response does not include an install ID.

License Deactivation

$result = $freemius->license()->deactivate();

deactivate() refuses to proceed when the stored UID does not match the current site — that means the activation was moved to another host, and we let the new host appear unlicensed rather than silently freeing the original seat.

Reading the Current Activation

$activation = $freemius->license()->get_activation();

if ( $activation->is_active() ) {
    // $activation->license_key(), $activation->install_id(), …
}

get_activation() always returns an Activation value object — use is_empty() to detect the no-activation case.

Updates

Update hooks are registered automatically during boot() for premium builds. There is no manual integration needed — WordPress will check for, display, and apply updates through its standard pipeline.

To force a refresh from the host plugin's UI:

$freemius->update()->get_update_data( true );

Addons

$addons = $freemius->addon()->get_addons();              // Cached for 24h.
$addons = $freemius->addon()->get_addons( true );        // Force refresh.

Each entry is enriched with a link field (Freemius checkout URL) and an is_premium boolean. Use the duckdev_freemius_format_addon_data filter to add or rewrite fields per addon.

Hooks

Actions

Filters

Security Notes

• The library does not verify nonces or capabilities. Host plugins MUST do that before forwarding form input to License::activate() / License::deactivate().
• The license key is stored in the duckdev_freemius_activation_data option (an autoload-safe option keyed by plugin ID). It is blanked from storage on deactivation.

License

GPL-2.0+