Expose activation URLs through stable global functions

Consumers were told to resolve Activation_Url from the container, which ties
them to whichever Harbor version's class their own copy ships rather than the
loaded, highest-version one. Add lw_harbor_get_activation_url() and
lw_harbor_get_product_activation_url() -- version-keyed global functions, the
stable public API -- wrapping Activation_Url::get_base() and for_product().
Point the activation-URL guide and the API reference at the functions instead
of the class.

Claude-Session: https://claude.ai/code/session_011uxoDruAaZXzRy3hk8mr4W

Author: dave-green-uk

changelog/smtnc-1844-activation-url-api.yaml

@@ -1,4 +1,4 @@
 significance: minor
 type: feature
-entry: Added a reusable activation URL API. Host plugins can build Liquid Web portal activation URLs from PHP via the Activation_Url service, or in the browser via the shared lw-harbor-activation script, which exposes window.lwHarbor.buildActivationUrl()
+entry: Added a reusable activation URL API. Host plugins can build Liquid Web portal activation URLs from PHP via the lw_harbor_get_activation_url() and lw_harbor_get_product_activation_url() global functions, or in the browser via the shared lw-harbor-activation script, which exposes window.lwHarbor.buildActivationUrl()
 timestamp: 2026-07-22T00:00:00.000Z

docs/guides/activation-urls.md

@@ -55,29 +55,29 @@ Consequences worth knowing:
 
 ## From PHP
 
-Resolve `Activation_Url` from the container.
+Call the global functions. Like the rest of Harbor's public API they resolve to
+the highest-version Harbor copy on the site, so you always get the loaded
+version's logic — do not build `Activation_Url` from your own bundled copy, which
+may not be the one actually running.
 
 ```php
-use LiquidWeb\Harbor\Portal\Activation_Url;
-
-$activation_url = Config::get_container()->get( Activation_Url::class );
-
 // Product-scoped, returning the user to your onboarding screen.
-$href = $activation_url->for_product(
+$href = lw_harbor_get_product_activation_url(
     'kadence',
     'pro',
     admin_url( 'admin.php?page=kadence-onboarding&step=2' )
 );
 ```
 
-| Method                                                             | Returns                                                                 |
-| ------------------------------------------------------------------ | ----------------------------------------------------------------------- |
-| `get_base( ?string $redirect_url )`                                | The portal subscriptions URL with referral, redirect, and domain params |
-| `for_product( string $slug, string $tier, ?string $redirect_url )` | The same, plus `sku={slug}:{tier}`                                      |
+| Function                                                                                    | Returns                                                                 |
+| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `lw_harbor_get_activation_url( ?string $redirect_url )`                                      | The portal subscriptions URL with referral, redirect, and domain params |
+| `lw_harbor_get_product_activation_url( string $slug, string $tier, ?string $redirect_url )` | The same, plus `sku={slug}:{tier}`                                       |
 
-Omit `$redirect_url` to fall back to Harbor's Software Manager page. Pass your
-own whenever the user started somewhere else — otherwise they will not come
-back to where they were.
+Both return an empty string when no Harbor instance is active — treat that as
+"hide the button". Omit `$redirect_url` to fall back to Harbor's Software Manager
+page. Pass your own whenever the user started somewhere else — otherwise they
+will not come back to where they were.
 
 ### Getting the return URL right
 
@@ -106,11 +106,7 @@ Harbor registers a dependency-free script exposing `window.lwHarbor`. Declare it
 as a dependency:
 
 ```php
-use LiquidWeb\Harbor\Config;
 use LiquidWeb\Harbor\Portal\Activation_Script;
-use LiquidWeb\Harbor\Portal\Activation_Url;
-
-$activation_url = Config::get_container()->get( Activation_Url::class );
 
 wp_enqueue_script(
     'kadence-onboarding',
@@ -125,7 +121,7 @@ wp_localize_script(
     'kadence-onboarding',
     'kadenceOnboarding',
     [
-        'activationBaseUrl' => $activation_url->get_base(
+        'activationBaseUrl' => lw_harbor_get_activation_url(
             admin_url( 'admin.php?page=kadence-onboarding&step=2' )
         ),
     ]

src/Harbor/API/Functions/Global_Function_Registry.php

@@ -8,6 +8,7 @@
 use LiquidWeb\Harbor\Config;
 use LiquidWeb\Harbor\Features\Manager;
 use LiquidWeb\Harbor\Licensing\Repositories\License_Repository;
+use LiquidWeb\Harbor\Portal\Activation_Url;
 use LiquidWeb\Harbor\Portal\Catalog_Repository;
 use LiquidWeb\Harbor\Site\Data;
 use LiquidWeb\Harbor\Traits\With_Debugging;
@@ -131,6 +132,34 @@ static function (): string {
 			}
 		);
 
+		\_lw_harbor_global_function_registry(
+			'lw_harbor_get_activation_url',
+			$version,
+			static function ( ?string $redirect_url = null ): string {
+				try {
+					return Config::get_container()->get( Activation_Url::class )->get_base( $redirect_url );
+				} catch ( Throwable $e ) {
+					self::debug_log_throwable( $e, 'Error building activation URL' );
+
+					return '';
+				}
+			}
+		);
+
+		\_lw_harbor_global_function_registry(
+			'lw_harbor_get_product_activation_url',
+			$version,
+			static function ( string $product_slug, string $tier, ?string $redirect_url = null ): string {
+				try {
+					return Config::get_container()->get( Activation_Url::class )->for_product( $product_slug, $tier, $redirect_url );
+				} catch ( Throwable $e ) {
+					self::debug_log_throwable( $e, 'Error building product activation URL' );
+
+					return '';
+				}
+			}
+		);
+
 		\_lw_harbor_global_function_registry(
 			'lw_harbor_display_legacy_license_page_notice',
 			$version,

src/Harbor/API/Functions/README.md

@@ -125,6 +125,8 @@ Strauss rewrites class references at parse time. `License_Repository::class` ins
 | `lw_harbor_is_feature_enabled( $slug )`                              | Whether a feature is in the catalog AND currently enabled/active                              |
 | `lw_harbor_is_feature_available( $slug )`                            | Whether a feature exists in the catalog, regardless of enabled state                          |
 | `lw_harbor_get_license_page_url()`                                   | Returns the admin URL for the Harbor Feature Manager page                                     |
+| `lw_harbor_get_activation_url( $redirect_url = null )`               | Returns a portal activation URL for this site, returning the user to `$redirect_url`          |
+| `lw_harbor_get_product_activation_url( $slug, $tier, $redirect = null )` | The activation URL scoped to a product and tier via `sku`                                 |
 | `lw_harbor_get_licensed_domain()`                                    | Returns the domain Harbor uses for licensing on the current site                              |
 | `lw_harbor_register_submenu( $parent_slug )`                         | Appends a Licensing submenu item under a plugin's top-level admin menu                        |
 | `lw_harbor_display_legacy_license_page_notice( $product_name = '' )` | Renders an info notice on a plugin's legacy license page pointing users to the unified system |

src/Harbor/global-functions.php

@@ -240,6 +240,53 @@ function lw_harbor_get_license_page_url(): string {
 	}
 }
 
+if ( ! function_exists( 'lw_harbor_get_activation_url' ) ) {
+	/**
+	 * Returns a Liquid Web portal activation URL for this site.
+	 *
+	 * Drops the user on the portal's subscriptions screen to activate a product
+	 * against this site, then returns them to $redirect_url (or the Software
+	 * Manager page when none is given).
+	 *
+	 * @since TBD
+	 *
+	 * @param string|null $redirect_url Where the portal returns the user afterwards.
+	 *
+	 * @return string The activation URL, or an empty string if no instance is active.
+	 */
+	function lw_harbor_get_activation_url( ?string $redirect_url = null ): string {
+		$callback = _lw_harbor_global_function_registry( 'lw_harbor_get_activation_url' );
+
+		$result = $callback ? $callback( $redirect_url ) : '';
+
+		return is_string( $result ) ? $result : '';
+	}
+}
+
+if ( ! function_exists( 'lw_harbor_get_product_activation_url' ) ) {
+	/**
+	 * Returns a portal activation URL scoped to a single product and tier.
+	 *
+	 * Like lw_harbor_get_activation_url(), but adds an `sku` param so the portal
+	 * pre-selects the given product and tier instead of an unfiltered list.
+	 *
+	 * @since TBD
+	 *
+	 * @param string      $product_slug The product slug, e.g. 'learndash'.
+	 * @param string      $tier         The tier slug, e.g. 'elite'.
+	 * @param string|null $redirect_url Where the portal returns the user afterwards.
+	 *
+	 * @return string The activation URL, or an empty string if no instance is active.
+	 */
+	function lw_harbor_get_product_activation_url( string $product_slug, string $tier, ?string $redirect_url = null ): string {
+		$callback = _lw_harbor_global_function_registry( 'lw_harbor_get_product_activation_url' );
+
+		$result = $callback ? $callback( $product_slug, $tier, $redirect_url ) : '';
+
+		return is_string( $result ) ? $result : '';
+	}
+}
+
 if ( ! function_exists( 'lw_harbor_refresh_catalog' ) ) {
 	/**
 	 * Forces a synchronous fresh catalog fetch from the Commerce Portal API.

tests/wpunit/API/Functions/GlobalFunctionsTest.php

@@ -276,4 +276,32 @@ public function test_refresh_catalog_returns_false_when_refresh_returns_wp_error
 
 		$this->assertFalse( lw_harbor_refresh_catalog() );
 	}
+
+	// -------------------------------------------------------------------------
+	// lw_harbor_get_activation_url() / lw_harbor_get_product_activation_url()
+	// -------------------------------------------------------------------------
+
+	public function test_get_activation_url_targets_the_subscriptions_screen(): void {
+		$url = lw_harbor_get_activation_url();
+
+		$this->assertStringContainsString( '/subscriptions/', $url );
+		$this->assertStringContainsString( 'portal-referral=plugin', $url );
+		$this->assertStringNotContainsString( 'sku=', $url );
+	}
+
+	public function test_get_activation_url_carries_the_given_return_destination(): void {
+		$url = lw_harbor_get_activation_url( 'https://example.test/onboarding' );
+
+		$this->assertStringContainsString( rawurlencode( 'https://example.test/onboarding' ), $url );
+		// The return trip is tagged so Harbor refreshes its cache on the way back.
+		$this->assertStringContainsString( 'lw-harbor-activated', $url );
+	}
+
+	public function test_get_product_activation_url_scopes_to_the_product_and_tier(): void {
+		$url = lw_harbor_get_product_activation_url( 'learndash', 'elite' );
+
+		$this->assertStringContainsString( '/subscriptions/', $url );
+		// The sku is RFC3986-encoded, so the colon becomes %3A.
+		$this->assertStringContainsString( 'sku=learndash%3Aelite', $url );
+	}
 }