Operators handbook — modules

Backend modules are optional features shipped by the gsid/cms-core PHP bundle. They're the second sense of "module" the CMS uses — see the glossary. Toggle per-website on the admin's Modules tab; configure per-website on the Module settings tab (when the module ships configurable knobs).

The modules today:

The two discount modules are easy to mix up: discount is a code the customer types, catalog_discount is automatic repricing. They stack. See catalog-discount.md. A gift card is neither: it does not lower the price, it pays part of it. See giftcard.md.

Dependencies

Modules can depend on other modules. The toggle stays clickable, but the effective state stays off until every dependency is also on.

blog              (no deps)
catalog           (no deps)
customer          (no deps)
cart              requires catalog + customer
checkout          requires cart + catalog + customer
shipping          requires checkout
delivery_slot     requires checkout
discount          requires cart
catalog_discount  requires catalog
giftcard          requires cart
seo               (no deps)
landingpages      (no deps)
portfolio         (no deps)
faq               (no deps)
newsletter        (no deps)
review_request    requires checkout
abandoned_cart    requires checkout
vehicle_lookup    (no deps)
vehicle_stock     (no deps)
tax               requires checkout
google            (no deps)
meta              (no deps)
bol               requires checkout

The Modules tab shows two things side by side: the stored toggle (your intent) and the effective state (resolver's verdict). When you flip Cart on but Customer is off, the Cart toggle goes blue but the effective chip stays grey with a hint about which dependency is missing.

In practice: enable in dependency order — catalog + customer first, then cart, then checkout.

Why modules exist

Not every tenant runs an e-commerce site. A boutique services site needs Pages + Forms — that's it. Loading the Catalog admin tab, running stock-reservation cron jobs, or shipping the Cart Twig helpers into the sandbox would all be waste.

Modules carve those features into opt-in groups. The admin doesn't show the Catalog sidebar item until the catalog module is on, the module's routes 404, its scheduled jobs skip the site, and cms_products() answers with an empty list.

Cluster vs. per-tenant

The set of modules is cluster-wide — flipping one on across the cluster requires a cms-core release + composer update. What operators control is which tenants get which modules.

Per-website configurable knobs (when they exist) live on the module's own database table:

Settings rows are lazy — created the first time you save the panel. Read-paths treat "no row" as "all defaults", so a tenant who never opened the Module settings panel still has a working module (with safe defaults: shipping = 0, no payment methods enabled, mail- from inherited from the website default).

Theme helpers per module

Each module ships a *SandboxContributor that adds its Twig functions, filters and entity getters to the theme sandbox. The full per-module helper list is in ../../twig-helpers.md → module helpers.

The sandbox allowlist is cluster-wide, not per website. It is built once from every contributor compiled into cms-core, so the names are callable on every site. What the per-website toggle changes is the answer: each helper checks the module itself and returns an empty result where it is off.

Themes ask directly with is_module_enabled('<id>'), which answers the effective state, so a module whose dependency is missing reads as off. Use it to drop the surrounding markup (a cart badge, a nav link, a section wrapper) and not just the dynamic content.

The helpers themselves also gate: on a website without the catalog module, cms_products() returns [] rather than throwing.

Theme template overrides per module

Each module ships default templates for its public-facing pages (product detail, customer login, checkout, etc.). Themes override by mirroring the path under templates/ in the theme repo:

@GsidCmsCore/customer/login.html.twig    →  @website/customer/login.html.twig
@GsidCmsCore/checkout/index.html.twig    →  @website/checkout/index.html.twig
@GsidCmsCore/checkout/email/order_confirmation.html.twig
                                            →  @website/checkout/email/order_confirmation.html.twig

The full list of overridable templates is in each module's reference page below.

Enabling a module — step by step

For super-admins:

1. Module → Modules tab → flip the toggle for the module you want on.
2. If the module has dependencies that aren't on, flip those first. The effective-state chip on the row will stay grey otherwise.
3. Save the website.
4. The Modules tab reloads showing the new effective state. New sidebar items appear (Catalog / Customers / Orders) for whatever the module surfaces.
5. If the module ships configurable knobs (Checkout, Customer), open the Module settings tab and configure. See the per-module reference page.
6. Verify on the public site: visit a hostname and exercise the feature (add a product to cart, register an account, place an order).

Disabling a module

Same flow in reverse. Be careful: disabling Cart with active sessions in flight is harmless (cart is per-session, no payment state) but disabling Checkout while orders are in pending_payment will leave those orders unable to complete via the public site (the route is gone). Webhooks still process via Messenger as long as the worker is up.

Per-module reference

• blog.md
• catalog.md
• customer.md
• cart.md
• checkout.md
• shipping.md
• delivery-slot.md
• discount.md
• catalog-discount.md
• giftcard.md
• seo.md
• landingpages.md
• portfolio.md
• faq.md
• newsletter.md
• review-request.md
• abandoned-cart.md
• vehicle-lookup.md
• vehicle-stock.md
• tax.md