Orocommerce Elfsight Bundle Laravel Package

Getting Started

Treat this like pulling in a Laravel package where the README is the only docs and the vendor tree is your real documentation source. It's a Symfony bundle on OroPlatform, so the mental map is: composer require ≈ composer require, bundle class ≈ service provider, Resources/config ≈ config/, Twig ≈ Blade, Doctrine entities ≈ Eloquent models, layout YAML ≈ your view composers.

Minimal path:

1. composer require ys-tools/orocommerce-elfsight-bundle — pin the version in composer.json. With 1 star and 0 dependents there is no compatibility matrix to lean on, so pin a tested version and commit the lock file.
2. Register the bundle. Add it to config/bundles.php (or Resources/config/oro/bundles.yml if your Oro version still uses that flow), matching the bundle's DependencyInjection namespace exactly as shipped.
3. Run the Oro install sequence, not just composer install:
   • php bin/console cache:clear
   • php bin/console oro:platform:update --force (migrations/fixtures if the bundle ships any)
   • php bin/console oro:assets:build if the bundle adds frontend assets
4. Look first at README.md, then Resources/config/ (DI parameters, oro/app.yml, layout YAML under Resources/views/layouts/) and Resources/views/ for the Twig entry point. The DI parameters are where the Elfsight app IDs / widget placement config will be defined.
5. First use case to prove integration end-to-end: drop a single Elfsight live chat or subscription popup into the storefront footer, confirm the platform.js script loads and the <div class="elfsight-app-<APP_ID>"> mount point renders, then expand to other placements.

Verify against the repo before assuming any specific config key — this is a low-traffic bundle and the README may lag the code.

Implementation Patterns

Placement through Oro layouts, not hardcoded Twig. OroCommerce storefront composition runs through layout YAML. Add the Elfsight block to the correct layout update — header, footer, product_view, shopping_list, checkout — rather than pasting <script> tags into theme templates. That keeps the placement theme-agnostic and upgrade-safe.

Config-driven widget identity. Each Elfsight widget has its own app ID. Keep IDs in system configuration or bundle parameters keyed per placement, so marketing can swap a widget without a code deploy. If the bundle exposes multiple block types, register them as Oro CMS content widgets so editors drag them into pages instead of developers editing YAML.

Typical embed shape (what the bundle will ultimately render, or what you write yourself if the block isn't covered):

<div class="elfsight-app-{{ elfsightAppId }}"></div>
<script src="https://static.elfsight.com/platform/platform.js" async defer></script>

Load the platform script once per page. If you're placing multiple widgets, hoist the <script> to a single layout position (e.g. before_content or head) and let only the <div class="elfsight-app-..."> mount points scatter across placements. Duplicate script tags will double-init and can blank out widgets.

Per-channel / per-storefront scoping. OroCommerce is multi-channel and multi-website by design. Gate rendering on the current website/channel (layout conditions or a Twig check against the current website) so you don't bleed a B2C popup into a B2B portal.

Consent and async. Wrap the embed in your cookie/consent gate when required in the target market. Elfsight loads client-side and injects an iframe, so it does not interfere with Oro's full-page cache — good, but it also means the widget cannot read server-side context. If the widget needs order/customer data, pass it via data- attributes or Elfsight's documented prefill mechanism, not through Twig-injected globals buried in the widget itself.

Theme inheritance. If you're overriding the bundle's Twig, do it from your own theme bundle under Resources/<ThemeName>/views/... so future bundle updates don't clobber customizations.

Gotchas and Tips

• Bus factor is the top risk. One star, zero dependents means you are effectively the maintainer. Read src/ before relying on documented behavior; budget time to fork if you need fixes.
• CSP will bite you. Elfsight loads from static.elfsight.com and its widgets pull further assets. If the storefront sends a Content-Security-Policy, whitelist the Elfsight domains or widgets will render empty with only console violations.
• Cache clearing is mandatory after install and after every config change. Oro caches the container aggressively; a "bundle isn't working" report is usually a stale cache. oro:platform:update then cache:clear is the reliable reset.
• Asset rebuild is separate. If you added Twig assets or overrides, run oro:assets:build — otherwise you'll debug a change that was never compiled.
• Debug the network tab, not PHP. The Symfony/Oro side just renders a div and a script. If the widget is blank, check the Elfsight API calls and the CSP console errors before touching Oro logs.
• Widget text and translations live in the Elfsight dashboard, not Oro's localization system. Content editors will ask why they can't translate the widget through OroCommerce — that's a product-level limitation, not a bug.
• Multiple widgets = performance hit. Each widget is an iframe plus scripts. On checkout and product pages, lazy-load or defer below-the-fold widgets; don't stack five popups on one page.
• Composer drift. There's no version constraint guidance from the maintainer. After upgrade, re-run the full install sequence and smoke-test every placement in a staging channel before touching production.
• Extension points are the standard Symfony/Oro ones: decorate services via services.yaml, override Twig in your theme bundle, and add layout updates in your own bundle rather than editing vendor. If the package lacks a needed hook, a small decorator around the block-rendering service is usually cheaper than a fork.