Skip to content

PHP 8.4 / Magento 2.4.8+ compatibility, beacon + CSP fixes, encrypted token & docs - #13

Open
allrude wants to merge 4 commits into
basicrum:mainfrom
allrude:chore/php84-magento248-compat-and-docs
Open

PHP 8.4 / Magento 2.4.8+ compatibility, beacon + CSP fixes, encrypted token & docs#13
allrude wants to merge 4 commits into
basicrum:mainfrom
allrude:chore/php84-magento248-compat-and-docs

Conversation

@allrude

@allrude allrude commented Jul 6, 2026

Copy link
Copy Markdown
Collaborator

Summary

Brings the module up to date for modern Magento, fixes two functional bugs in the
beacon integration, adds an encrypted token field, and ships a complete user guide.

The public config paths (basicrum/general/*) are unchanged, so existing
configuration keeps working after upgrade.

Why

  • The Composer PHP constraint (^8.1|^8.2|^8.3) excluded PHP 8.4, blocking
    installation on Magento 2.4.9.
  • The frontend built a Boomerang config object but never called init, so the
    beacon URL and plugin settings were inert.
  • There was no CSP handling, so beacons were blocked on strict-CSP 2.4.x stores.
  • The "Consent Settings" admin UI was shown but never actually did anything.

What's in this PR

Functional fixes

  • Initialise Boomerang for real — push ["init", config] through BOOMR_mq so the
    configured beacon_url / cookie flags / plugins actually take effect.
  • Deferred send via the public API — replace the never-registered custom
    WaitAfterOnload plugin with autorun: false + a delayed BOOMR.page_ready().
  • Dynamic CSP — new Model/Csp/BeaconPolicyCollector adds the configured beacon
    origin to connect-src + img-src, registered in CompositePolicyCollector.
    No manual csp_whitelist.xml needed since the endpoint is admin-configurable.

New feature

  • Encrypted "Beacon Token / Site Key" field (basicrum/general/token,
    obscure + Encrypted backend). When set, it is decrypted and appended to the
    beacon URL as &token=… (URL-encoded, respecting an existing query string).

Compatibility

  • composer.json: PHP ~8.3.0 || ~8.4.0; replace * wildcards with bounded
    ranges; add the modules actually used (module-config, module-backend, module-csp).
  • etc/module.xml: declare <sequence> for Store / Config / Backend / Csp.
  • PageTypeDetector: inject App\Response\Http (the base ResponseInterface
    doesn't declare getStatusCode()), strict === 404, map cms_noroute_index, memoise.

Cleanup & security

  • ViewModel exposes a typed, null-safe API; template renders nothing when unconfigured,
    standardises on $escaper->escapeJs, keeps the CSP-safe SecureHtmlRenderer.
  • Trim PageTypeDetectorInterface to the method in use; add return types to admin
    blocks; move the Logo field's markup out of PHP into a template + CSS.
  • Beacon Endpoint field validates as a URL.
  • Centralise the Boomerang version in Model\Boomerang; rename the vendored file to
    a version-agnostic boomerang.min.js.
  • Add a real LICENSE (MIT + BSD-3-Clause notice for bundled Boomerang); fix the
    README (previously claimed PHP 7.2 / Magento 2.3).

Docs

  • Self-contained docs/user-guide.html (install, endpoint/token, config, CSP,
    verification, FAQ, troubleshooting), plus CHANGELOG.md.

Behaviour changes

  • Minimum requirements raised to PHP 8.3 / Magento 2.4.8.
  • Removed the non-functional consent group (consent/enabled, consent/mode)
    and its ConsentMode source model — they were never read by any code. Real consent
    gating can be reintroduced as a proper feature later.

How to test

  1. composer require the branch, bin/magento module:enable BasicRum_Analytics,
    setup:upgrade, cache:flush.
  2. Set Enable = Yes and a Beacon Endpoint (optionally a Token), save, flush.
  3. Load a storefront page → in DevTools Network a beacon fires to the endpoint with
    p_type + p_gen=mage2 (and &token=… if set).
  4. With CSP in restrict mode, confirm no CSP violation for the beacon host.

Notes

  • The vendored library is release build 815, "cutting-edge" plugin flavour
    (bundles Continuity) — a plugin-set name, not an unstable channel; npm latest
    (1.815.1) is the same build. Kept as-is; only the filename/version bookkeeping changed.

allrude and others added 4 commits July 6, 2026 20:55
Compatibility, correctness, security and cleanup pass on the fork, plus full
user documentation. Public config paths (basicrum/general/*) are unchanged.

Functional fixes:
- Initialise Boomerang for real. The template built basicRumBoomerangConfig
  but never passed it to Boomerang, so beacon_url / cookie flags / plugin
  settings were inert. Now pushes ["init", config] through BOOMR_mq.
- Reimplement the "send after onload" delay with the public API
  (autorun:false + delayed BOOMR.page_ready) instead of a custom plugin that
  was never registered in the Boomerang build.
- Add dynamic CSP: Model/Csp/BeaconPolicyCollector adds the configured beacon
  origin to connect-src + img-src, registered in CompositePolicyCollector.
  Without this, beacons are blocked on strict-CSP 2.4.x stores.

Compatibility:
- composer.json: PHP ~8.3||~8.4 (was ^8.1|^8.2|^8.3, excluded 8.4); replace
  "*" wildcards with bounded ranges; add module-config/backend/csp deps.
- module.xml: declare <sequence> for Store/Config/Backend/Csp.
- PageTypeDetector: inject Response\Http (interface lacked getStatusCode()),
  strict ===404, map cms_noroute_index, memoise.

Cleanup / security:
- Footer ViewModel: typed, null-safe getBeaconEndpoint(); path constant.
- footer.phtml: render nothing when endpoint empty; standardise on
  $escaper->escapeJs; drop redundant view-model re-fetch; keep SecureHtmlRenderer.
- Trim PageTypeDetectorInterface to getPageType(); add return types to admin
  blocks; move Logo markup to an admin template + CSS (no inline styles).
- Centralise Boomerang version in Model\Boomerang; rename vendored file to
  version-agnostic boomerang.min.js (it is release build 815, "cutting-edge"
  plugin flavor — a plugin-set name, not an unstable channel).
- Beacon Endpoint field: validate-url + CSP comment.
- Remove non-functional consent group + ConsentMode source model.
- Add LICENSE (MIT + BSD-3 notice for Boomerang); correct README.

Docs:
- docs/user-guide.html: self-contained setup guide (cards, <details>,
  <dialog>) covering install, endpoint/token, config, CSP, verification, FAQ
  and troubleshooting.
- CHANGELOG.md and IMPROVEMENT_PLAN.md documenting what/why.

Verified: php -l clean on PHP 8.4; composer validate clean; setup:upgrade
succeeds; Magento-bootstrapped runtime check confirms DI resolution, ViewModel
null-safety, and that the CSP collector emits the correct policies and is
registered. Browser-level beacon/CSP check left for the operator.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- system.xml: new optional "Beacon Token / Site Key" field
  (basicrum/general/token), type=obscure + Encrypted backend model.
- Footer ViewModel: decrypt the token and expose getBeaconUrl(), which
  appends the token to the endpoint as &token=... (URL-encoded, respecting an
  existing query string). Template now uses getBeaconUrl().
- CSP collector unaffected (token is in the query string, not the host).
- docs/user-guide.html: remove the three feature-card emoji icons; increase
  spacing between section headings and cards; change the hero's purple to a
  dark green; document the new Token field (setup step, settings table, FAQ,
  example dialog).
- CHANGELOG: note the new token field.

Verified: php -l clean; runtime test confirms token append + URL-encoding for
plain, existing-query, blank-token and no-endpoint cases.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Hero uses a single dark-green color instead of a blue→green gradient.
- Increase top padding under the sticky nav so the first section isn't
  cramped; add scroll-margin-top so anchor links don't hide headings under
  the sticky nav.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
`main` also carries class="wrap", so `.wrap{padding:0 20px}` (class
selector) beat `main{padding:52px 0 60px}` (element selector) on specificity
and the top padding never applied. Target `main.wrap` so the top space sticks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@allrude
allrude requested a review from ceckoslab July 6, 2026 19:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant