PBJ License Manager — User Guide

PBJ License Manager — Install and Usage Guide

1. What this plugin does

PBJ License Manager runs on the site you sell from and acts as a license server for your own plugins and themes. It stores products and license keys, tracks which customer sites activated each key, serves update manifests to the WordPress update system, and streams plugin zips through signed, expiring download links. A key never disables a customer's plugin — it only controls whether they receive updates.

2. Requirements

• WordPress 5.8 or newer (the update mechanism relies on the WP 5.8 Update URI system)
• PHP 7.4 or newer
• Pretty permalinks enabled (the REST API endpoints are used by customer sites)
• Optional: PBJ Form Builder 1.1.0+ for automatic key issuing on paid purchases

3. Installation

1. In wp-admin go to Plugins → Add New → Upload Plugin.
2. Choose pbj-license-manager.zip and click Install Now.
3. Activate. A "License Manager" entry appears in the admin menu.
4. On activation the plugin creates the wp_pbj_licenses table and generates its two secrets (issue API key, download signing secret).

Settings carry over on upgrades.

4. First-time setup

Work through the tabs in this order:

Products tab. Add one product per plugin you sell.

• Slug — must equal the plugin's folder name, e.g. pbj-seo. This is the identity used in keys, REST URLs, and the client.
• Display name — what buyers see in emails, e.g. "PBJ SEO Pro".
• Current major version — new keys are entitled to this major (start at 1 or your current major). Bump only when you ship a paid major upgrade.
• Sites per key — how many sites one key may activate. 3 is a friendly default.
• Latest version — the version served in update manifests, e.g. 2.1.0. You will bump this on every release.
• Requires WP / Tested up to / Requires PHP — passed through to the WordPress update UI.
• Package file path — absolute server path to the current zip, e.g. /home/you/private/pbj-seo.zip. Keep it OUTSIDE the public web root; the plugin streams it through signed links. Preferred over Package URL.
• Package URL (fallback) — only used when no file path is set. Anyone with this URL can download, so treat it as a weaker option.
• Info URL — your product page, linked from the update UI.

Settings tab.

• Email key on issue — leave on; buyers get their key automatically.
• Email subject / body — {product} and {key} are replaced at send time.
• PBJ Form Builder map — one line per purchase form: Form Title => product-slug. Matching is by form title, case-insensitive (form IDs are never used because they change across Studio→Live syncs).
• Download link lifetime — how long a signed download URL stays valid. 3600 seconds is fine.
• Uninstall — leave the DROP-table option off unless you truly want license data destroyed when the plugin is deleted.

Secrets (bottom of Settings tab).

• Issue API key — send as the X-PBJ-LM-Key header when an external system POSTs to the issue endpoint.
• Download signing secret — never displayed; regenerate only if you believe it leaked (outstanding download links die immediately).

5. Daily usage

Issuing a key manually. Keys tab → Issue a key → pick product, enter buyer email and order reference, keep "Email key to buyer" checked → Issue key. The key appears in the notice and the list.

Automatic keys from PBJ Form Builder. Nothing to do once the map is set: every PAID submission on a mapped form mints a key and emails it to the submission's email field. Free submissions never mint keys.

Issuing from code. From any plugin on the same site:

do_action( 'pbj_license_issue', 'pbj-seo', 'buyer@example.com', 'order-123' );

Issuing from an external system. POST to /wp-json/pbj-license/v1/issue with header X-PBJ-LM-Key: <your API key> and body fields product, email, order_ref. The response contains the key.

Revoking / reinstating. Keys tab → search the key or buyer email → Revoke (refunds, chargebacks) or Reinstate.

Exporting. Keys tab → Export CSV.

Managing package files (Packages tab, 1.1.0+). Upload each release zip with its version number; files are stored in wp-content/uploads/pbj-license-packages/<product>/ behind a deny-all .htaccess and served only through signed expiring links. Leaving "Set as current release" ticked updates the product's package file AND latest version in one step. Old versions stay listed per product with size/date; "Make current" rolls back or forward, and Delete removes anything that isn't the current package.

Shipping a release. Packages tab → upload the new zip with "Set as current release" ticked. Done — customer sites see the update within ~6 hours (their manifest cache), or immediately after Dashboard → Updates → Check Again.

Download link in key emails (1.1.0+). The {download_url} placeholder in the key email is a signed link (default 72 hours, Settings → Email download link lifetime) to the current release of the major version the buyer purchased. Feature/minor updates are never emailed — they flow through the WordPress update system. Use "Resend email" on any key row to send a fresh copy with a fresh link.

Shipping a paid major upgrade. Do the above AND bump Current major version. Existing keys keep working installs but get manifests with reason new_major and no package; sell them a new key (a discount coupon to existing buyers works well).

6. Testing as a customer

1. Issue yourself a key for a test product.
2. On a second WordPress install, add your sold plugin (with the bundled client configured — see the User Guide tab) and enter the key.
3. Set the product's Latest version higher than the installed version.
4. On the test site: Dashboard → Updates → Check Again. The update should appear and install through the normal UI.
5. Now revoke the key, clear the test site's cache (the client caches manifests for 6 hours — the client's flush_cache() runs when the key is re-saved), and confirm the update still shows but the download link is gone.

7. Upgrading

Upload the new pbj-license-manager.zip via Plugins → Add New → Upload Plugin and choose "Replace current with uploaded". Settings, products, and all license data survive. Once the plugin's own update channel is live at pbj.tech, updates arrive through the normal WordPress update UI instead.

8. Troubleshooting

• Customer sees no update. Their manifest is cached up to 6 hours. Dashboard → Updates → Check Again forces a fresh check. Then confirm: key entered correctly, key status active (Keys tab), key's major matches the product's latest major, site within the activation limit.
• Update shows but install fails with a download error. The product's package file path is wrong or unreadable by PHP, or the signing secret was regenerated between check and click. Fix the path (or re-check for a fresh signed link).
• Form Builder purchases don't mint keys. The map line must match the form's exact title (case doesn't matter, spelling does). Confirm the submission shows as paid (paid_cents > 0) in Form Builder. Confirm the product slug on the right side of => exists in Products.
• Buyer never received the key email. wp_mail failed on your host. The key is in the Keys tab — resend manually. Installing an SMTP plugin fixes delivery permanently.
• Every activation fails with site_limit. The key's sites are used up. Keys tab shows the hostnames; ask the customer to deactivate an old site (their plugin's license field) or raise Sites per key on the product.
• REST endpoints return 404. Permalinks are set to Plain. Settings → Permalinks → pick anything else → Save.
• You deleted a product by accident. Re-add it with the same slug; existing keys reference the slug and resume working. Keys are never deleted with a product.

9. Where things live

• Main file: wp-content/plugins/pbj-license-manager/pbj-license-manager.php
• License data: table {prefix}pbj_licenses
• Settings option: pbj_license_manager_settings
• Products option: pbj_license_manager_products
• Schema version option: pbj_license_manager_db_version
• Transients: pbj_license_manager_ (server side), pbj_lc_ (client side, on customer sites)
• REST namespace: /wp-json/pbj-license/v1/ (activate, deactivate, manifest/<product>, download/<product>, issue)
• Package storage: wp-content/uploads/pbj-license-packages/<product>/ (deny-all .htaccess; managed from the Packages tab)
• Bundled client for your sold plugins: wp-content/plugins/pbj-license-manager/sdk/class-pbj-license-client.php
• Feedback recipient (hardcoded): jake@pbj.tech in includes/class-pbj-license-manager-feedback.php