clankersupport-php

Render the Clanker Support widget embed from PHP and Laravel apps — an open-source, self-hostable, AI-powered support agent for your site.

The widget itself is client-side JavaScript served by the Clanker Support API (/widget.js); your backend's job is only to emit the <script> tag with the right data-* attributes. This package does that with strict validation and HTML-attribute escaping, mirroring the snippet the dashboard's Embed page generates.

Features

• One static method — ClankerSupport::scriptTag() returns the exact embed tag the dashboard generates
• Fails loudly in development — empty key, unknown mode/theme, or a non-positive escalation threshold throws InvalidArgumentException instead of silently shipping a broken widget
• XSS-safe — every attribute value is escaped with htmlspecialchars(ENT_QUOTES | ENT_SUBSTITUTE, "UTF-8")
• Laravel bridge — auto-discovered service provider, publishable config, and a @clankerSupport Blade directive driven by env vars
• Zero runtime dependencies — plain PHP >= 8.1; Laravel support activates only when illuminate/support is present

Tech stack

• PHP >= 8.1, strict_types, PSR-4 autoloading
• PHPUnit 10 test suite (contract tests mirroring the official Python SDK)
• Optional Laravel integration (service provider + Blade directive), no hard framework dependency

Getting started

composer require clankersupport/clankersupport-php

Plain PHP

<?php

use ClankerSupport\ClankerSupport;

// In your layout, just before </body>:
echo ClankerSupport::scriptTag('pk_your_project_key');

With options:

echo ClankerSupport::scriptTag(
    'pk_your_project_key',
    apiUrl: 'https://support-api.example.com', // self-hosted deployments only
    brandColor: '#4f46e5',
    mode: 'bubble',           // or 'inline'
    theme: 'auto',            // 'light' (default), 'dark', or 'auto'
    escalationThreshold: 5,   // visitor messages before "Talk to a human"
);

Get your key: app.clankersupport.com → your project → Embed.

Laravel

The service provider is auto-discovered — no manual registration. Publish the config if you want to customize it:

php artisan vendor:publish --tag=clankersupport-config

Set your env vars (only the key is required):

# Get your key: app.clankersupport.com → your project → Embed
CLANKER_PROJECT_KEY=pk_your_project_key
# Optional:
# CLANKER_API_URL=https://support-api.example.com
# CLANKER_BRAND_COLOR=#4f46e5
# CLANKER_MODE=bubble
# CLANKER_THEME=auto
# CLANKER_ESCALATION_THRESHOLD=5

Then drop the directive into your layout, just before </body>:

    @clankerSupport
</body>

When CLANKER_PROJECT_KEY is unset, the directive renders an HTML comment (<!-- Clanker Support: set CLANKER_PROJECT_KEY -->) instead of throwing, so a fresh install never breaks page rendering.

Options

Argument	Env (Laravel)	Default	Description
projectKey	CLANKER_PROJECT_KEY	— (required)	The project's public widget key. Safe to expose.
apiUrl	CLANKER_API_URL	https://api.clankersupport.com	API origin; set when self-hosting. Trailing slashes are stripped.
brandColor	CLANKER_BRAND_COLOR	widget default	Accent color for the launcher/header, e.g. #4f46e5.
mode	CLANKER_MODE	bubble	bubble (floating launcher) or inline (mounts in place).
theme	CLANKER_THEME	light	light, dark, or auto (follow OS).
escalationThreshold	CLANKER_ESCALATION_THRESHOLD	project setting	Visitor messages before "Talk to a human" appears (positive int).

Self-hosting

Clanker Support is open source (theopenco/llmchat) and self-hostable. Point apiUrl (or CLANKER_API_URL) at your own deployment's origin and the tag will load /widget.js from there.

Publishing to Packagist (maintainers)

1. Tag a release: git tag v1.0.0 && git push --tags.
2. Submit https://github.com/theopenco/clankersupport-php at packagist.org/packages/submit (first release only).
3. Enable the GitHub webhook (Packagist → package → "Settings") so future tags auto-update.

License

MIT