Clippy For Laravel Laravel Package

Getting Started

• Install with composer require for the package, then publish its config and assets (php artisan vendor:publish) and pick a tag for the Clippy/agent assets. Commit or gitignore the published assets deliberately — they are part of your app's public surface now.
• Drop the package's Blade directive/component into your main layout (typically just before </body>), or into the specific views where you want the assistant. It renders the agent markup plus the script tags for jQuery and clippy.js.
• Look first at: the published config file (agent name, speech text, sound/animation toggles), the Blade directive/component signature, and public/vendor/<package>/ for the bundled jquery.min.js and clippy.js/agent assets.
• First use case: a one-off onboarding or confirmation line — e.g. after a form save, flash a session message and render the assistant with that string. That exercises the whole path (config → view → JSON-encoded speech payload → browser) in a few lines.
• If you are upgrading from a pre-5.1.0 install, republish assets before doing anything else. Composer will not overwrite the stale jQuery 1.7 and mutable-branch clippy.js already sitting in public/vendor/. Use --force for the asset tag, then hard-refresh and check the network tab.

Implementation Patterns

• Treat speech as data, not markup. Since 5.1.0 the package JSON-encodes speech before embedding it in the generated script, so you can safely pass user-influenced strings (a first name, a product title, a validation message) through the package's helper/directive. Do not pre-wrap those values in quotes or manually JSON-encode them again — you'll double-encode.
• Config-driven copy. Put the default greeting and recurring hints in the config file rather than scattering literals through Blade. Makes it trivial to change tone or disable the assistant per environment ('enabled' => env('CLIPPY_ENABLED', false) in local/CI).
• Session flash → speech. A small view composer or @if (session('status')) block that hands session('status') to the assistant is the highest-value pattern: you get contextual feedback without touching every controller.
• Validation errors. Pass $errors->first() (or a summarised count) — the JSON encoding makes this safe, which was the historical reason people avoided it.
• Conditional rendering. Gate the directive behind auth and a per-user "dismissed" flag so you don't nag returning users; keep the component out of admin/print/email views entirely.
• Multiple messages. If the package supports a queue/array of speech items, prefer that over re-rendering the component, and keep the list short — the agent is a nudge, not a notification centre.
• Asset delivery. Decide early whether you serve the published assets directly from public/vendor/... or copy them into your Vite pipeline. If you use Vite, be explicit about it — mixing the package's script tags with a bundler is the most common source of "agent loads in staging, not production".
• Don't double-load jQuery. The package now pins jQuery 3.7.1 and ships it. If your app already loads its own jQuery, pick one owner of that global and make sure the package isn't clobbering or being clobbered by it.

Gotchas and Tips

• The jQuery jump from 1.7 to 3.7.1 is the real breaking change, not the version number. Any custom agent/theme/plugin code you wrote against 1.7 will break: .live(), .die(), $.browser, $.fn.load() as an event shortcut, jQuery.fn.size(), and the removed jQuery.boxModel/$.support shims are all gone. Audit anything in public/ or your own JS that touches the assistant, and test with the browser console open — 3.x fails loudly, which is helpful, but only on the code path you actually exercise.
• Republish, don't assume. Because assets live in public/, composer update alone leaves the old jQuery and old clippy.js in place. Add a deploy step (vendor:publish --tag=... --force) or a check in your release notes; otherwise the security fix ships in vendor/ and never reaches users.
• JSON encoding closes the script-breakout hole, not every injection path. If you also render speech into an HTML attribute, a data- attribute, a tooltip, or via {!! !!}, escape it yourself. Only the generated <script> payload is covered.
• CSP still matters. JSON encoding prevents content from terminating the script block, but the block is still inline. Under a strict Content-Security-Policy you still need a nonce or hash — expect the agent to silently not appear if you've just tightened CSP, and check the console rather than the package.
• Debugging "nothing appears": in order — is the config enabled, was the directive actually rendered (view source), did the assets publish, is there a 404 on the vendored JS, is jQuery loaded exactly once, is CSP blocking the inline script, is the agent z-index buried under a modal/overlay.
• clippy.js is now pinned to an exact upstream commit. Good for reproducibility; the trade-off is no upstream bug fixes or agent additions without a deliberate bump. Record the SHA in your notes and treat it like any other pinned dependency — schedule a periodic review, and vendor/fork it if you need a patch before the package cuts a release.
• The PHP 7.0 syntax floor persists. If you override package classes or write companion code you intend to keep compatible across the advertised Laravel 5.1–13 matrix, avoid arrow functions, nullsafe operators, named arguments, and constructor property promotion. It's easy to break this accidentally in a service provider subclass.
• Laravel 13 support is asserted by the test matrix, not by every code path in your app. Verify package auto-discovery resolves on your version and re-run your own smoke test after the upgrade; the matrix proves the package boots, not that your customisations survive.
• Extension points to prefer: config keys, the directive/component arguments, and published views. Monkey-patching the vendored JS or editing public/vendor/ directly means the next --force publish wipes your work — extend via a separate file that runs after the package's script.
• Everything spoken is client-side. Never pass tokens, internal URLs, unreleased feature names, or PII into speech strings; the payload is visible to anyone with dev tools.