Olark Bundle Laravel Package

Getting Started

rgsystemes/olark-bundle is a Symfony bundle, not a Laravel package — v2.0.3 is a maintenance release (symfony/framework-bundle 5.4 support + a legal brand-name correction), so nothing here changes how you consume it. There is no service provider, no auto-discovery, and no config/olark.php to publish.

Install (Symfony):

composer require rgsystemes/olark-bundle

Register the bundle in config/bundles.php, add your site ID under config/packages/olark.yaml, then render the provided Twig template/extension in templates/base.html.twig.

Install (Laravel): don't. Pulling a Symfony bundle into a Laravel app gains you a Twig template you cannot render and a container extension Laravel will ignore. Instead read the repo once and port the ~15 lines of Olark bootstrapping JS into a Blade partial — that is the whole of what the bundle does.

Where to look first, in order:

1. DependencyInjection/Configuration.php — the only real API surface (site ID, and possibly identity/visitor fields).
2. Resources/views/ — the JS snippet you actually care about.
3. Resources/config/ — service wiring, useful only if you plan to decorate it.
4. composer.json — confirm the constraint. v2.0.3 targets Symfony 5.4; verify it resolves against your framework version before assuming 6.x/7.x works.

First use case: drop the chat widget into your base layout on production only, keyed off an env var, and verify the Olark script tag appears exactly once in the rendered HTML.

Implementation Patterns

Symfony (native path). Configure the site ID from an environment variable rather than hardcoding it, and render the widget from your base layout so it inherits on every page:

# config/packages/olark.yaml
olark:
    site_id: '%env(OLARK_SITE_ID)%'

Then include the bundle's template in base.html.twig. Keep it in base and not in individual pages, or you'll get duplicate script tags on composed pages.

Laravel (ported path). Mirror the bundle's config shape in a Laravel config file and a Blade partial, so the mental model stays transferable if you ever move to Symfony:

// config/olark.php
return ['site_id' => env('OLARK_SITE_ID')];

{{-- resources/views/partials/olark.blade.php --}}
@if (config('olark.site_id') && app()->isProduction())
    <script>
        ;(function(o,l,a,r,k,y){/* Olark loader, verbatim from the bundle */})(window,document,'https://static.olark.com/jsclient/loader0.js','olark');
        olark.identify('{{ config('olark.site_id') }}');
    </script>
@endif

Two patterns that pay off daily:

• Conditional rendering by audience. Chat is noise for logged-in admins and for users who haven't consented. Wrap the include in an @auth/role check and a consent check rather than shipping it globally and hiding it with CSS — the script still loads and still sets cookies.
• Visitor identification. If you pass name/email after login, do it through Olark's identify API in a small Blade partial or a Livewire/Alpine hook, not by editing the bundle's template. Overriding vendor templates means re-porting on every release.

Integration tip: if you're on Symfony and want the site ID to vary per tenant, decorate the bundle's Twig extension (or its config-consuming service) rather than adding a second template. That keeps one render path.

Gotchas and Tips

• v2.0.3 changed a legal brand name. The PR title is "legal brand name," which in practice often touches the vendor prefix, bundle alias, copyright header, or service ID — not just a README line. After upgrading, grep -ri the old name across your config/ and any template overrides. If the bundle alias changed, config/bundles.php and your olark: config key will silently stop matching and the widget renders empty instead of erroring.
• Symfony 5.4 is the announced ceiling. The release note says "support Symfony 5.4," not "6.x/7.x." Check the composer.json constraint before upgrading a project on a newer framework; a ^4.4|^5.4 style constraint will block the install and, if you force it, the container wiring may still break.
• "Widget doesn't appear" is almost always one of four things: empty site ID, script rendered twice, a Content-Security-Policy blocking static.olark.com, or the layout never including the base template. Check View Source for the script tag before touching config.
• SPA-style navigation kills it. Livewire, Inertia, Turbo, and htmx swaps don't re-run the bootstrap script. Olark survives navigation in most cases, but if the chat button vanishes after a partial reload, re-init in a livewire:navigated/turbo:load listener rather than including the partial again.
• Config caching. In Symfony, bin/console cache:clear after any olark.yaml change — the site ID is compiled in. In Laravel, php artisan config:clear. An unchanged widget after editing .env is a cache problem nine times out of ten.
• Consent ordering matters. Load the script only after consent, not before with a display:none. Olark sets cookies on load; gating the render is the only defensible pattern under GDPR.
• Debugging hook. Once loaded, window.olark is the live API object. In the console, confirm typeof olark === 'object' and inspect olark('api.chat.getState') before assuming a server-side problem.
• Extension points are thin, and that's fine. Override the template, or decorate the Twig extension in services.yaml. Prefer decoration — template overrides are the first thing to break on a patch release like this one.
• Don't expect features from patch releases here. The project moves slowly and is essentially a maintained snippet. If you need proactive chat triggers, offline forms, or analytics wiring, budget for custom JS on top rather than waiting on the bundle.