README

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 () 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)

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

License

MIT

clankersupport / clankersupport-php

Maintainers

Package info

Statistics

Security