Maho Ecommerce Platform

The Maho Theme System uses a modern stack of Tailwind CSS 4 and DaisyUI 5. It is designed so that store owners can use industry-specific variants (like fashion or electronics) without needing Node.js, as these variants are provided as plain CSS.

Key Architectural Concepts

• No Template Forking: The system uses compiled CSS to style semantic class contracts in base/default templates. This means template fixes in base/default automatically propagate to all industry themes.
• Dual Stylesheet Loading: Every page loads two stylesheets:
  1. css/styles.css: The compiled global engine (shared by all themes).
  2. css/theme.css: The identity/palette of the active theme.
• Theme Fallback: Industry themes (e.g., fashion/) inherit templates from base/default/. They primarily provide css/theme.css to override CSS variables.
• Composer Integration: When installed via Composer, the maho-composer-plugin copies the theme files into your project's public/ directory. Never edit files in base/default directly in a child project, as they are overwritten during updates. Instead, create your own theme.

Maho implements several safeguards to protect sensitive data, but certain configurations can increase exposure:

Default Protections

• No Sensitive Headers/Bodies: HTTP request/response bodies, headers, query strings, and CLI arguments are never exported.
• No PII in Commerce Events: Span events use maho.* attributes which contain no PII. Users are identified only by enduser.id.
• Exception Safety: Failed spans include the exception class in error.type, but the exception message is only included in the standard OTel exception event. Treat your OTLP backend as a location that holds whatever is in your exception messages.

High-Exposure Settings

• Query Statement: By default, the SQL statement is included in every query span. Because Maho uses quoteInto() rather than parameter binding, the statement contains actual values (e.g., customer emails, search terms, or password reset tokens). Disable this if your backend must not hold customer data.
• Export Logs: Enabling log export ships Monolog records verbatim. Anything written to the logs by any module will be sent to your OTLP backend.

Maho supports distributed tracing across different components:

• Outgoing HTTP Requests: Requests made via \Maho\Http\Client::create() automatically include a traceparent header. The baggage header (containing maho.store and maho.currency) is only sent to hosts explicitly listed under Baggage Hosts in the admin.
• Queue Messages: When a message is dispatched to a queue, the current trace context is stored on the message row. The consumer handler's spans will join the original request's trace.
• Upstream Traces: By default, Maho does not continue traces started by upstream callers. To enable this, activate Trust Incoming Trace Headers in the admin. This should only be done behind a trusted proxy. The headers read depend on OTEL_PROPAGATORS.
• Frontend Correlation: Enabling the Server-Timing Response Header exposes the W3C trace context (trace id, span id, and sampled flag) to the browser, allowing correlation between frontend RUM tools (like Grafana Faro) and backend traces.

Maho themes use CSS variables to define identity. The default maho identity is defined in default/src/_theme.css as a DaisyUI theme, while industry themes use plain CSS variables in css/theme.css.

Dark Mode Implementation: Dark mode is handled via @media (prefers-color-scheme: dark).

• Some themes (like food and kids) are pinned to light mode by setting color-scheme: light inside the dark media block.
• Merchants can disable dark mode via the admin: System > Configuration > Design > Theme Settings > Dark Mode. When disabled, the html element receives data-color-scheme="light", and dark rules are scoped using :where() to maintain cascade order.

Customizing Colors:

1. Use the Admin settings for basic color changes.
2. Override variables in your theme's css/theme.css.
3. To use a DaisyUI stock theme (e.g., dracula), use Option B (a custom build) and name it in a @plugin "daisyui" block.

Maho automatically instruments several layers of the application. Tracing begins only when the request root span opens to avoid scattered single-span traces during bootstrap.

Trace Categories

Commerce Moments

Commerce events are recorded as span events with maho.* attributes (no PII):

• maho.order.placed
• maho.cart.add
• maho.checkout.success
• maho.customer.login

Logged-in users are tagged with the pseudonymous enduser.id.

Use this approach for defining a brand identity (colors, fonts, shapes) without writing custom templates or using Tailwind classes. This is the method used by Maho's industry themes.

1. Create public/skin/frontend/[base]/[theme_name]/css/theme.css.
2. Override design tokens within the :root selector. These tokens control everything from typography to component shapes and product tile backgrounds.
3. Add custom CSS below the tokens. Because theme.css is unlayered, your selectors will always win over the compiled framework.

Key Design Tokens:

• --color-primary, --color-base-100, --color-base-content (Core colors)
• --font-display, --font-body (Typography)
• --radius-field, --radius-box (Shapes)
• --product-tile-bg, --product-cutout-shadow (Product presentation)
• --footer-bg, --footer-ink (Footer identity)

Example css/theme.css structure:

:root {
    --font-display: 'Figtree', sans-serif;
    --color-primary: #0e7a5f;
    --color-base-100: #ffffff;
    --radius-field: 0.5rem;
    /* ... other tokens ... */
}

/* Custom overrides */
.btn { border-radius: 9999px; }