Harbor

Bundled library that handles licensing, updates, and feature gating for WordPress plugins and themes.

Installation

It's recommended that you install Harbor as a project dependency via Composer:

composer require stellarwp/harbor

We actually recommend that this library gets included in your project using Strauss.

Luckily, adding Strauss to your composer.json is only slightly more complicated than adding a typical dependency, so checkout our strauss docs.

Strauss must not prefix the global functions

Harbor's global functions (src/Harbor/global-functions.php) are deliberately non-namespaced. They are how the Harbor copies on a site find each other and route every call to the highest-version copy. Recent Strauss versions prefix global function names as well as namespaces, which breaks that negotiation — each plugin gets a privately-named copy of the helpers and the function_exists() guards never see one another.

Exclude the file in your Strauss config:

"exclude_from_prefix": {
    "file_patterns": [
        "/harbor/src/Harbor/global-functions\\.php$"
    ]
}

Agent skill

Harbor ships skill/SKILL.md: the rules a consuming plugin has to follow, written for the AI coding agent that will edit your plugin. It covers the free-vs-premium WordPress.org boundary, consuming the lw_harbor_* API instead of hand-rolling Portal URLs, Harbor's release train, and how to find the Strauss-prefixed copy that actually runs.

Agents only read it if your plugin tells them to. Paste this into your plugin's AGENTS.md (or CLAUDE.md):

## Harbor (licensing)

Licensing, license keys, premium or add-on checks, platform fees, and anything calling `lw_harbor_*` go through Harbor, the library vendored at `vendor/vendor-prefixed/stellarwp/harbor/`.

Hard rules, no exceptions:

- A plugin distributed on WordPress.org must not validate a license key, send a request to the Commerce Portal, the Licensing API, or Herald, or install or activate anything from an entered key. That work belongs in the premium plugin.
- Onboarding for a free plugin never requires a license key, not even as a step that can be skipped.
- Never build a Portal URL, activation URL, or licensing request by hand. Use the `lw_harbor_*` helpers. A missing helper is a Harbor ticket.
- Never release or QA with `composer.json` pinned to a Harbor `dev-` branch.
- Strauss must not prefix `src/Harbor/global-functions.php`.
- Call the license page the "Unified License Manager" in anything a user sees.

Before changing any of that code, read `vendor/vendor-prefixed/stellarwp/harbor/skill/SKILL.md` for the API, hooks, and bootstrap order of the installed version. If the file is missing, run `composer install` first.

Replace vendor/vendor-prefixed with your Strauss target_directory if it differs. Nothing else needs changing.

The hard rules sit in your own file so every agent and review bot sees them on a fresh clone, before composer install. The API detail stays in the vendored file so it always matches the Harbor version you have installed.

If you are an agent reading this from vendor/ and the plugin's AGENTS.md has no Harbor section, read skill/SKILL.md next to this file before writing licensing code, and tell the developer to add the section.

Harbor and WordPress.org

Harbor is bundled in free WordPress.org plugins as well as paid ones, and stays inert in the free ones by design. Several of the things it does — validating a license key, calling our servers, installing a plugin — could be read as running against the WordPress.org plugin guidelines if a plugin distributed there did them.

A plugin on WordPress.org must not present a license field that validates a key, send a request to the Commerce Portal / the Licensing API / Herald at runtime (directly or through Harbor), or install or activate anything from an entered key. All new licensing and activation surface belongs in the premium plugin, behind the premium-plugin gate. The skill and the Integration Guide carry the full rule.

Initialize the library

Initializing the Harbor library should be done within the plugins_loaded action, preferably at priority 0.

Harbor only boots its providers when at least one premium plugin announces itself via the lw_harbor/premium_plugin_exists filter. The filter must be attached before Harbor::init() is called, otherwise the gate inside Harbor::init() short-circuits and the providers, REST routes, admin page, and lw_harbor/loaded action are never registered. The simplest pattern is to add the filter on the line immediately above the Harbor::init() call (as shown below), but anywhere earlier in the request works just as well.

use LiquidWeb\Harbor\Config;
use LiquidWeb\Harbor\Harbor;

add_action( 'plugins_loaded', function() {
 /**
  * Configure the container.
  *
  * The container must be compatible with stellarwp/container-contract.
  * See here: https://github.com/stellarwp/container-contract#usage.
  *
  * If you do not have a container, we recommend https://github.com/lucatume/di52
  * and the corresponding wrapper:
  * https://github.com/stellarwp/container-contract/blob/main/examples/di52/Container.php
  */
 $container = new Container();
 // Use a plugin basename constant defined in your main plugin file,
 // e.g. define( 'MY_PLUGIN_BASENAME', plugin_basename( __FILE__ ) )
 Config::set_plugin_basename( MY_PLUGIN_BASENAME );
 Config::set_container( $container );

 // Announce that this premium plugin should bring Harbor online.
 // Must be added before Harbor::init(). Anywhere earlier in the request works,
 // but the line above the call is the simplest pattern.
 add_filter( 'lw_harbor/premium_plugin_exists', '__return_true' );

 Harbor::init();
}, 0 );

Translation

Package is using __( 'Invalid request: nonce field is expired. Please try again.', '%TEXTDOMAIN%' ) function for translation. In order to change domain placeholder '%TEXTDOMAIN%' to your plugin translation domain run

./bin/stellar-harbor domain=<your-plugin-domain>

or

./bin/stellar-harbor

and prompt the plugin domain You can also add lines below to your composer file in order to run command automatically

"scripts": {
 "stellar-harbor": [
   "vendor/bin/stellar-harbor domain=<your-plugin-domain>"
 ],
 "post-install-cmd": [
   "@stellar-harbor"
 ],
 "post-update-cmd": [
   "@stellar-harbor"
 ]
  }

Registering a plugin

Harbor discovers your plugin's embedded key automatically by scanning active plugins for a file named LWSW_KEY.php in the plugin root. No filter registration is required. See the Harbor Integration Guide for more details.

Changelog

This project uses @stellarwp/changelogger to manage its changelog. All notable changes are tracked via changelog entry files in the changelog/ directory.

To add a new changelog entry:

bunx @stellarwp/changelogger add

To compile changelog entries into changelog.txt:

bunx @stellarwp/changelogger write --overwrite-version <version>

Releasing

1. Run the Release Prep workflow (Actions → Release Prep → Run workflow). Supply the target branch, version (e.g. 1.2.0), and the release date (e.g. 2026-04-29). The workflow bumps the VERSION constant, compiles the changelog, and opens a PR automatically.
2. Review and merge the PR.
3. Create a GitHub Release with a new tag in the format vX.X.X targeting the merge commit.
4. Optionally, once the release is checked, run the Update Consumers workflow (Actions → Update Consumers → Run workflow) instead of bumping each plugin by hand. It opens a PR in every plugin in Plugins with Harbor that bumps stellarwp/harbor to the new version (The Events Calendar and Event Tickets get theirs through tribe-common). To run it locally, or to target specific repos, run composer release:update-consumers -- [version] [owner/repo ...]. Add --dry-run to see the change without pushing anything. The consumer list lives in dev_scripts/update-consumers.sh.

Documentation

Start with Harbor Overview for the full architecture.

Subsystems

• Licensing — Key discovery, API responses, validation workflows, caching.
• Catalog — Product families, tiers, features, the Commerce Portal API.
• Features — Feature types, resolution, strategies, Manager API.
• Cron — Scheduled refresh of catalog and licensing data.
• Frontend — React app, @wordpress/data store, component hierarchy, CSS scoping.
• Notices — Admin notices, legacy license warnings, persistent dismissal.

Architecture

• Unified License Key — Key model, seat mechanics, system boundaries.
• Fat Leader / Thin Instance — Leader election, cross-instance hooks.
• Conventions — Naming conventions for namespaces, packages, identifiers.

API Reference

• REST: License — License endpoints.
• REST: Catalog — Catalog endpoints.
• REST: Features — Feature endpoints.
• REST: Legacy Licenses — Legacy license endpoints.
• Liquid Web Licensing v1 — External licensing API consumed by Harbor.

Guides

• Integration Guide — How to integrate your plugin with Harbor.
• CLI Commands — WP-CLI commands for feature management.
• Testing — PHP tests with Codeception/slic; E2E tests with Playwright/wp-env.

Plugins with Harbor

Plugin name	Repository	Distribution	Note
GiveWP	impress-org/givewp	wp.org
LearnDash	stellarwp/learndash-core	Herald
MemberDash	stellarwp/memberdash	Herald
The Events Calendar	the-events-calendar/the-events-calendar	wp.org	tribe-common should be updated first
Event Tickets	the-events-calendar/event-tickets	wp.org	tribe-common should be updated first
Kadence Memberships Pro	stellarwp/restrict-content-pro	Herald
Kadence Blocks	stellarwp/kadence-blocks	wp.org
Kadence Shop Kit	stellarwp/kadence-shop-kit	Herald
Kadence Theme Kit Pro	stellarwp/kadence-pro	Herald