PBJ Essentials — Install and Usage Guide
1. What this plugin does
PBJ Essentials bundles seven independent mini-modules: HTTPS & Cache, Region Blocker, Basic Forms, Page Login Lock, Content Push, 3-Day Traffic, and a single-product License Server. Each is a small, complete feature; each has a full PBJ plugin as its bigger sibling, and stands down automatically when that sibling is active.
2. Requirements
- WordPress 5.8+, PHP 7.4+
- Pretty permalinks (the license module's REST endpoints need them)
- LiteSpeed hosting for the edge-cache feature (harmless elsewhere, just inert)
- Cloudflare for header-based geo detection, or enable the optional ip-api.com fallback
3. Installation
- Plugins → Add New → Upload Plugin →
pbj-essentials.zip → Activate.
- Nothing changes on activation: every behavior-affecting module starts OFF.
- Open PBJ Essentials in the admin menu; the Modules screen shows every area with its status and a one-line summary of what turning it on does.
Settings carry over on upgrades.
4. First-time setup
The Settings, Forms, Sync, Traffic, and License tabs each open with a plain-English intro and numbered how-to steps (1.0.1+), so the screens walk you through this themselves; the notes below are the short version.
Settings tab, top "Modules on/off" section: switch on the modules you want. Then per module:
- HTTPS & Cache: tick Force HTTPS (only acts when your Site Address is already https) and/or LiteSpeed edge cache + TTL.
- Region Blocker: enter one 2-letter country code (e.g.
RU); optionally enable the ip-api.com fallback (off by default; external service, cached 12h); adjust the banner text.
- Page Login Lock: set the restricted message. Then tick "Require login" in the PBJ Essentials box when editing any Page.
- Content Push: remote URL, remote username, and an Application Password created on the remote site (Users → Profile → Application Passwords).
- 3-Day Traffic: optionally count logged-in visits (off by default).
- License Server: on the License tab, describe your product and note the manifest URL shown there.
5. Daily usage
- Forms tab: create a form (title, destination email, up to 8 fields), embed with the shortcode shown after saving, e.g.
[pbj_essentials_form slug="contact"]. Submissions are emailed, not stored.
- Sync tab: "Push now" sends published posts + pages to the remote, matched by slug (existing updated, missing created), 100 items per run — run again for more.
- Traffic tab: last-3-days totals, top pages, top referrers.
- License tab: issue a key per buyer (send it to them yourself), revoke/reinstate keys, and update "Latest version" + package URL when you release.
6. Testing as a visitor
Use a private/incognito window while logged out: the Region Blocker and Page Login Lock always exempt logged-in admins, and 3-Day Traffic ignores your logged-in visits by default.
7. Upgrading
From WordPress.org via the normal update UI. Installing a full PBJ plugin later needs nothing from you — the matching module stands down by itself, and your Essentials settings stay saved.
8. Troubleshooting
- A tab says the module is standing down — the matching full PBJ plugin is active and owns that area. By design.
- Form emails missing — host
wp_mail unreliable; install an SMTP plugin. Check spam for [Form title] New submission.
- Push returns 401/403 — application password wrong/revoked, or the remote user can't edit posts/pages.
- Push says more items than one run carries — run Push again; slug matching makes reruns safe.
- Region blocker inert — no Cloudflare header and the ip-api fallback is off; or you're logged in (admins exempt).
- License manifest 404 — Settings → Permalinks must not be "Plain".
- Traffic shows zero — module was just enabled (counting starts now), or all your visits were logged-in/bot traffic.
9. Where things live
- Main file:
wp-content/plugins/pbj-essentials/pbj-essentials.php
- Settings option:
pbj_essentials_settings · Forms: pbj_essentials_forms · License keys: pbj_essentials_license_keys
- Traffic table:
{prefix}pbj_essentials_hits (3-day retention, daily cron pbj_essentials_analytics_prune)
- Page-lock meta:
_pbj_essentials_locked
- License REST:
/wp-json/pbj-essentials-license/v1/manifest and /download
- Transients:
pbj_essentials_*
- Feedback recipient (hardcoded):
jake@pbj.tech in includes/class-pbj-essentials-feedback.php