WBAMS is extended by modules. An addon module adds a feature and its own administration pages; a gateway module takes money. They are separate contracts and are configured in different places.

Addon modules

An addon lives in its own directory under the extensions tree, declares its configuration, and is activated from Settings. Once active it can add administration pages, register hooks, define permissions and create its own tables.

Configuration
Declared by the module and rendered by the product, so the settings form is generated rather than written.
Access
An addon declares which administrator roles may use it. Grant access deliberately; the default is not access for everyone.
Schema
A module that needs tables creates them on activation and is responsible for them thereafter. The product’s own migrations do not touch them.
Hooks
An addon’s hooks file is loaded through the hook cache. See Hooks.
Page-builder sections
Since 1.11.0 an addon can offer its own sections in the page builder’s Section Library. See below.
Settings checks and status
An addon can refuse settings, check them once they are saved, and show how it stands on its card. See below.

Activating an addon that takes over an earlier addon’s settings in its own activation keeps what that activation did: since 1.11.0 the list of active addons is no longer read before the addon runs and written back afterwards. Updates never remove an addon — an update deletes only files a release lists as obsolete, and no release lists an addon — so an addon’s files, tables and settings stay as they are until you remove it.

Page-builder sections from an addon

An active addon offers sections by adding a cms-sections.json file to its own directory, without changing the CMS or a theme:

{
  "schema": 1,
  "sections": {
    "ExampleOpeningTimes": {
      "title": "Opening Times",
      "description": "Today's opening times, from the add-on.",
      "category": "Example",
      "script": "cms/ExampleOpeningTimes.js",
      "template": "cms/ExampleOpeningTimes.tpl",
      "prepare": "WBAMS\\Extension\\Addon\\Example\\Website::openingTimes"
    }
  }
}
Name
The key is a JavaScript class name in the builder and is stored with each page. It must start with the addon’s name in class-name form — addon example gives Example…, my_shop gives MyShop… — followed by a capital letter or a digit and more letters and digits, up to 64 characters in all.
script
The builder’s editor for the section, an Editor.js tool, usually described with the section kit (WbamsSectionKit.define({...})). It is loaded after the core sections, and the shared Section design panel wraps it like any other.
template
A Smarty template for the website, given $block (the section’s saved data, as prepared), $blockkey, $section, $WEB_ROOT and $WLANG. Start it with {if $block.sechidden neq "true"} so the Show/Hide switch works, and reuse the CMS section classes (sec, container, sec-title…): addons do not add stylesheets to CMS pages.
prepare
Optional. A public static method in the addon’s own namespace, called as method(array $block, string $type) before the template is rendered. It returns the data the template prints, or null to leave the section out of the page. An exception leaves the section out and is written to the activity log.
title, description, category
What the Section Library shows. The title is required; the category defaults to Add-ons.

The script, the template and the prepare method must all be valid, and the files must be inside the addon’s directory, or the section is not offered. A name that two addons declare, or that a core section uses, is offered by neither. Only active addons are read. Data the builder needs for its fields, such as the choices of a select, is printed by the addon as a JavaScript global through the OnControlHeadOutput hook.

Checking settings and showing status

An addon can check its own settings on Settings › Addon Modules and show how it stands on its card, with three optional functions in its main file. They follow the pattern a gateway module follows on its own settings page.

<module>_preferences_validate(array $settings)
Runs before anything on the page is stored, with the values about to be saved. Throw an exception to refuse them: nothing on the page is saved, and the administrator reads the exception’s message, so write it for them.
<module>_preferences_saved(array $settings)
Runs once the settings are stored, with the earlier values in $settings['existing']. This is the place for a check that calls another service, such as a license or a connection test. Return ['status' => 'success'|'info'|'error', 'description' => '…'] to add a line to the save’s confirmation. An exception is shown as an error, and the settings stay saved.
<module>_preferences_status(array $settings)
Runs each time the page is drawn, for an active addon, with all its stored settings. Return null, or ['label' => '…', 'tone' => 'positive'|'neutral'|'warning'|'danger', 'detail' => '…']: the label is a pill beside Active on the card, and the detail a line under the card’s heading.

The first two run for the addon whose Save button was pressed, and for any other addon whose values change in the same save.

A status function must not call another service.

It runs on every view of the page. Keep the result of the check your post-save function makes, with your own settings, and report that. Tie it to the values it was made for, so that after a change the status reads as not checked rather than as the old answer, and never keep a key or password in it.

What an addon returns is shown as plain text. Tags are removed; a label is cut at 40 characters, a detail at 240 and a message at 500; an unknown tone shows as neutral. An error that is not an exception, such as a TypeError or a missing class, is written to the activity log with its details and shown to the administrator in general words. Anything the function prints is discarded.

function example_preferences_validate(array $settings): void
{
    if (($settings['api_key'] ?? '') !== '' && ($settings['account'] ?? '') === '') {
        throw new \WBAMS\Fault\Extension\InvalidPreferences('Enter the account that goes with the API key.');
    }
}

function example_preferences_status(array $settings): ?array
{
    if (($settings['api_key'] ?? '') === '') {
        return ['label' => 'Not connected', 'tone' => 'warning', 'detail' => 'Enter the API key, then save.'];
    }

    return ['label' => 'Connected', 'tone' => 'positive'];
}

Uploading a theme or an app

Since 1.13.8 a theme or an app is added from its zip file in the admin area, without the server, cPanel or FTP: Upload a theme on Setup › Website themes, and Upload an app on Setup › Addon Modules. It takes an administrator whose role has the Install Themes and Apps permission (Full Administrator gets it with the update), and WBAMS asks for that administrator's password again before the page opens. An update of a theme or app you uploaded is uploaded the same way.

  1. Choose the file.The theme's or app's zip, from its seller. Nothing is installed in this step.
  2. Check.WBAMS reads the zip without unpacking it and shows what it found: the name, version, who made it, its folder and size, and what it checked (its folder, its files, its size, the WBAMS it needs and its license). A file that fails is refused with the reason in plain words, and nothing on the website changes. A paid package can take its license key here, or later.
  3. Install.WBAMS checks the file again, keeps the installed copy first when this is an update, puts the files in place and writes each step to the activity log. When a step cannot finish, it stops before changing anything or puts the earlier copy straight back.

A new theme waits among your themes, and visitors keep the current one until you choose it with Use on the website. A new app is switched off until you activate it on the Apps page; an updated app that is switched on finishes its update the next time the Apps page opens.

Kept copies
Each update, put-back and removal keeps the copy it replaced, and Kept copies has Put back for each. The three newest of each theme or app are kept.
Remove
A theme that is not on the website, or an app that is switched off, can be removed; a copy is kept. Choose another theme, or deactivate the app, first.
Part of WBAMS
The themes and apps that come with WBAMS are kept up to date by WBAMS updates, so they cannot be removed, and an upload that uses one of their names is refused.

What a package holds

One folder
One theme or app, in a folder named after it, either at the top of the zip (aurora/…) or at its place in a site (themes/aurora/…, extensions/apps/example/…). Finder's __MACOSX folder and .DS_Store files are left out.
A theme
A theme.yaml that gives the theme its name, and header.tpl and footer.tpl unless it builds on another theme. Its folder name takes lower-case letters, digits, - and _.
An app
A PHP file with the folder's name inside the folder (example/example.php), described by its wbams.json. Its folder name takes lower-case letters, digits and _, starting with a letter.
Never in a package
.htaccess, .user.ini, .phar and .phtml files, programs, hidden files, links, password-protected entries, and any path that leaves the package's folder.
Size
Up to 64 MB zipped (and within the server's own upload limit), no file over 64 MB, 256 MB unpacked in all, 6,000 files, and 16 folders deep. The server's PHP needs its zip extension.
The WBAMS it needs
requires: { wbams: "1.13.8" } names the oldest WBAMS it works on; an older site is asked to update WBAMS first. A theme that builds on a theme the website does not have is refused.
# theme.yaml
name: "Aurora"
version: "1.0.0"                 # or a VERSION file beside theme.yaml
author: "Your company"
description: "A short line about the theme."
requires: { wbams: "1.13.8" }
license: { product: "aurora", option: "theme_aurora", name: "Aurora", buy: "https://example.com/aurora" }
config: { parent: "serepok" }    # only for a theme that builds on another
{
  "type": "wbams-addons",
  "version": "1.0.0",
  "description": { "name": "Example", "tagline": "A short line about the app." },
  "authors": [{ "name": "Your company" }],
  "requires": { "wbams": "1.13.8" },
  "licensing": { "product": "example", "option": "app_example", "name": "Example", "buy": "https://example.com/example" }
}

An app without a version in its wbams.json takes the one in its own <name>.php, where that file is plain PHP. Leave out license (a theme) or licensing (an app) for a free package.

A paid package names its license: product is the product on the WBAMS license service whose key unlocks it, option an option of a WBAMS license that includes it without a key of its own (either may be left out), and buy the page where it is bought.

Until it is licensed
A paid theme cannot become the website's theme, and a paid app stays switched off. A notice at the top of the admin area says when a theme chosen for the website or an app that is switched on has no license yet.
Preview on my site
Opens your website with a paid theme in your own browser only, with a bar to buy a license or leave the preview. Visitors, and anyone signed out, keep seeing the website's theme.
License keys
Theme licenses on Website themes and App licenses on the Apps page take the key from the order: Save the key, Check again and Remove the key. A package licensed through an option of the website's WBAMS license needs no key.
Encoded code
The Check step says how many of a package's PHP files are encoded, and notes a paid package whose PHP files are not.

The demo bar

For a website that shows off themes. The Demo bar card on Setup › Website themes puts a slim bar along the bottom of every page that tells visitors which theme they see, with its Buy button.

Show the demo bar to visitors
Turns the bar on. Visitors can hide it for the rest of their visit.
Themes visitors can try
Visitors switch between these in their own browser only; the website keeps its theme. Choose two or more for the switch to show.
Buy button address
Leave it empty to use each theme's own shop page, the buy address in its theme.yaml.

Gateway modules

A gateway module implements one payment provider. WBAMS 1.12.0 ships 20 of them: Stripe, Stripe ACH, Stripe SEPA and Stripe Dynamic Payments; PayPal, Credit/Debit Card (PayPal), PayPal Basic, PayPal Website Payments Pro, PayPal Pro Reference Payments and Payflow Pro; Authorize.net, Authorize.net CIM and Authorize.net Echeck; Helcim, Payment Express, PayJunction and Payments Gateway; and Bank Transfer and Mail In Payment. A gateway declares its configuration fields, renders the payment step, and receives the provider’s callback.

Callbacks are the part that breaks

A gateway callback is an unauthenticated request from a third party. It must verify the message is genuinely from the provider before acting on it, using whatever signature or verification call the provider offers.

Never trust a callback because it names a valid invoice.

Anyone can post an invoice ID. Verify the message against the provider before recording a payment.

  1. Confirm the callback URL the provider holds matches the System URL currently configured.
  2. Read the gateway log to see what actually arrived, rather than what the provider’s dashboard says it sent.
  3. Check the module log for what the module did with it.

Provider vocabulary is not yours to change

Payment providers define their own event names and status values, and WBAMS uses them verbatim. PayPal’s BILLING.SUBSCRIPTION.CANCELLED keeps the provider’s spelling even though WBAMS itself now uses Canceled. Respelling one of these to match house style stops the events matching.

Logging

Modules log their requests and responses to the module log. Log enough to diagnose a failure without logging credentials, card data or full customer records. A module that logs nothing is a module you cannot support.

Retiring a module

Deactivate the module before removing its files, so the product stops calling it. A module whose files are deleted while still active produces fatal errors on the pages that expected it, not a graceful absence.