conventions.md

Conventions

Naming

Harbor is a PHP library bundled by Liquid Web WordPress plugins. Each plugin ships its own vendor-prefixed copy via Strauss. Multiple copies coexist on a single WordPress site and negotiate leadership internally.

Because of this architecture, identifiers appear in several scopes with different collision risks. The conventions below ensure consistency and avoid conflicts.

PHP Namespace

namespace LiquidWeb\Harbor\Features;

use LiquidWeb\Harbor\Licensing\License_Manager;

Packages

The Composer package is stellarwp/harbor. The GitHub repository lives under the stellarwp organization. These may migrate to liquidweb in the future depending on GitHub organization and Packagist policies that are still being resolved. The stellarwp scope is a publishing detail and does not affect the PHP namespace or any runtime identifiers.

The NPM package (@stellarwp/harbor) is private and not published to any registry. It exists only for local package management within this project.

Source Layout

src/Harbor/           PHP source (PSR-4 root)
resources/js/         TypeScript/React frontend
resources/css/        CSS (Tailwind + PostCSS)
build/                Production assets (committed)
build-dev/            Development assets (committed)

WordPress Hooks

Prefix: lw-harbor/

apply_filters( 'lw-harbor/catalog/fetched', $catalog );
do_action( 'lw-harbor/licensing/key_stored', $key );

Options, Transients, and User Meta

Prefix: lw_harbor_

get_option( 'lw_harbor_unified_license_key' );
get_user_meta( $user_id, 'lw_harbor_dismissed_notices', true );

Cache Keys

Prefix: lw_harbor_

wp_cache_get( 'lw_harbor_domain', 'lw_harbor' );

Container Keys

Prefix: lw-harbor.

$container->get( 'lw-harbor.admin-views.path' );

REST API

Namespace: liquidweb/harbor/v1

/wp-json/liquidweb/harbor/v1/features
/wp-json/liquidweb/harbor/v1/license
/wp-json/liquidweb/harbor/v1/catalog
/wp-json/liquidweb/harbor/v1/legacy-licenses

The liquidweb/harbor/v1 namespace is shared across Liquid Web libraries. Harbor registers its routes there, and other libraries can add their own routes under the same namespace.

Global PHP Functions

Prefix: lw_harbor_ (public) and _lw_harbor_ (internal)

lw_harbor_is_feature_enabled( 'ai-content' );
lw_harbor_get_unified_license_key();

These are non-namespaced functions that survive Strauss prefixing. They use a global registry so the highest-version copy always handles the call. Each function has three references that must stay in sync: the function_exists() guard, the function definition, and the registry key.

WP-CLI

Parent command: wp harbor

wp harbor feature list
wp harbor license validate
wp harbor catalog refresh

The harbor parent command is project-specific, following WP-CLI convention of namespacing under the project name.

Cron Hooks

Prefix: lw_harbor_

'lw_harbor_data_refresh'

Error Codes (PHP)

Prefix: lw-harbor-

'lw-harbor-feature-not-found'
'lw-harbor-invalid-key'
'lw-harbor-store-failed'

CSS Scope and DOM

<div id="lw-harbor-root" class="lw-harbor-ui"></div>

The .lw-harbor-ui class is the Tailwind CSS scope boundary. A PostCSS plugin (scopeToHarborUI) prefixes all generated selectors with .lw-harbor-ui to prevent style conflicts with the WordPress admin. The lw-harbor prefix family remains the canonical namespace for IDs and other DOM identifiers.

Script Handles

Prefix: lw-harbor-

wp_enqueue_script( 'lw-harbor-ui', ... );
wp_enqueue_style( 'lw-harbor-ui', ... );
wp_enqueue_script( 'lw-harbor-notice-dismiss', ... );

JavaScript and TypeScript

Identifier	Convention
Error class	HarborError (file: harbor-error.ts)
Store name	'lw/harbor'
Store registration	registerHarborStore
Store import alias	harborStore
REST paths	'/liquidweb/harbor/v1/...'
Docblock package	@package LiquidWeb\Harbor

Error Codes (JS)

The ErrorCode enum values in TypeScript do not carry a prefix. They are scoped by the enum itself.

ErrorCode.FeaturesFetchFailed; // 'features-fetch-failed'
ErrorCode.LicenseStoreFailed; // 'license-store-failed'

Version Tags

The library version starts at 0.0.1. All @since tags for new code use @since 1.0.0.

Summary

Scope	Prefix	Separator	Example
PHP namespace	LiquidWeb\Harbor	\	LiquidWeb\Harbor\Features\Manager
Hooks	lw-harbor	/	lw-harbor/catalog/fetched
Options/meta/cache/cron	lw_harbor	_	lw_harbor_unified_license_key
Container keys	lw-harbor	.	lw-harbor.admin-views.path
REST namespace	liquidweb	/	liquidweb/harbor/v1/features
Global functions	lw_harbor	_	lw_harbor_is_feature_enabled()
WP-CLI	harbor		wp harbor feature list
Error codes (PHP)	lw-harbor	-	lw-harbor-feature-not-found
CSS/DOM	lw-harbor	-	.lw-harbor-ui, #lw-harbor-root
Script handles	lw-harbor	-	lw-harbor-ui