PHPackages                             stromcom/php-snippet - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility &amp; Helpers](/categories/utility)
4. /
5. stromcom/php-snippet

ActiveLibrary[Utility &amp; Helpers](/categories/utility)

stromcom/php-snippet
====================

PHP library for generating STROMCOM integration snippets

0.1.0(today)00MITPHPPHP ^8.4CI passing

Since Mar 21Pushed todayCompare

[ Source](https://github.com/stromcom/php-snippet)[ Packagist](https://packagist.org/packages/stromcom/php-snippet)[ RSS](/packages/stromcom-php-snippet/feed)WikiDiscussions master Synced today

READMEChangelog (2)Dependencies (4)Versions (2)Used By (0)

stromcom/snippet-php
====================

[](#stromcomsnippet-php)

PHP library for generating [STROMCOM](https://www.stromcom.cz) integration snippets. Generates the JavaScript code you embed on your page to load the STROMCOM chat widget, identify users, and attach threads. No runtime dependencies — pure PHP 8.2+.

Requirements
------------

[](#requirements)

- PHP **8.2+**

Installation
------------

[](#installation)

```
composer require stromcom/php-snippet
```

Quick start
-----------

[](#quick-start)

```
use Stromcom\Snippet\SnippetClientFactory;
use Stromcom\Snippet\Options\UserOptions;
use Stromcom\Snippet\Options\ThreadOptions;

$client = SnippetClientFactory::create(
    clientKey:      'your-client-key',
    clientSecret:   'your-bearer-token',
    codeHashSecret: 'your-app-secret',   // optional — auto-hashes user & thread codes
);

// 1. Loader — place once in  or before
echo $client->snippet()->getHTML();

// 2. Identify the logged-in user (optional but recommended)
//    The raw ID 'user-id-42' is automatically HMAC-hashed and base-62 encoded before output.
echo $client->user(new UserOptions(
    code:         'user-id-42',
    name:         'Jane Doe',
    emailAddress: 'jane@example.com',
    avatarURL:    'https://example.com/avatars/jane.png',
))->getHTML();

// 3. Embed a conversation thread
echo $client->thread('#support-chat', new ThreadOptions(
    code: 'order-12345',
    name: 'Order #12345',
    url:  'https://yourapp.com/orders/12345',
))->getHTML();
```

Environments
------------

[](#environments)

The default environment is **production**. Use `Environment::STAGING` for the staging CDN, or `CustomEnvironment` for any custom URL (testing, self-hosted, localhost).

```
use Stromcom\Snippet\Environment\Environment;
use Stromcom\Snippet\Environment\CustomEnvironment;

// Production (default)
$client = new SnippetClient('key', 'secret', Environment::PRODUCTION);

// Staging
$client = new SnippetClient('key', 'secret', Environment::STAGING);

// Custom / testing
$client = new SnippetClient('key', 'secret', new CustomEnvironment('http://localhost:8082/loader.js'));
```

You can also implement `EnvironmentInterface` yourself if you need custom logic (e.g. URL from a config service):

```
use Stromcom\Snippet\Environment\EnvironmentInterface;

class MyEnv implements EnvironmentInterface {
    public function getLoaderUrl(): string {
        return getenv('STROMCOM_LOADER_URL');
    }
}

$client = new SnippetClient('key', 'secret', new MyEnv());
```

Code hashing
------------

[](#code-hashing)

User and thread `code` values should be hard to guess. Instead of hashing IDs manually, enable automatic hashing and every `user()` / `thread()` call will HMAC-hash the code for you.

### Using the factory (recommended)

[](#using-the-factory-recommended)

The simplest way — pass `codeHashSecret` to `SnippetClientFactory::create()`:

```
use Stromcom\Snippet\SnippetClientFactory;
use Stromcom\Snippet\Options\UserOptions;
use Stromcom\Snippet\Options\ThreadOptions;

$client = SnippetClientFactory::create(
    clientKey:      'key',
    clientSecret:   'secret',
    codeHashSecret: 'your-app-secret',
);

// 'user-42' is automatically HMAC-hashed and base-62 encoded (~43 chars for SHA-256)
echo $client->user(new UserOptions('user-42'))->getHTML();

// Same for threads
echo $client->thread('#chat', new ThreadOptions('order-123'))->getHTML();
```

The default algorithm is **SHA-256**. You can switch to **SHA-1** via the `codeHashAlgo` parameter:

```
$client = SnippetClientFactory::create(
    clientKey:      'key',
    clientSecret:   'secret',
    codeHashSecret: 'your-app-secret',
    codeHashAlgo:   HashAlgorithm::SHA1,
);
```

#### Base-62 encoding (default)

[](#base-62-encoding-default)

By default the HMAC hash is encoded as a **base-62** string (`0-9 A-Z a-z`, ~43 chars for SHA-256) instead of the longer hex representation (64 chars). If you need the raw hex output, disable base-62:

```
$client = SnippetClientFactory::create(
    clientKey:       'key',
    clientSecret:    'secret',
    codeHashSecret:  'your-app-secret',
    codeHashBase62:  false,  // use raw hex output (64 chars for SHA-256)
);
```

You can also apply the decorator manually:

```
use Stromcom\Snippet\Hashing\HmacCodeHasher;
use Stromcom\Snippet\Hashing\Base62CodeHasher;

$hasher = new Base62CodeHasher(new HmacCodeHasher('your-app-secret'));
$client = new SnippetClient('key', 'secret', codeHasher: $hasher);
```

### Using the constructor with a custom hasher

[](#using-the-constructor-with-a-custom-hasher)

For full control, pass any `CodeHasherInterface` implementation to the `SnippetClient` constructor:

```
use Stromcom\Snippet\SnippetClient;
use Stromcom\Snippet\Hashing\CodeHasherInterface;

class MyCustomHasher implements CodeHasherInterface {
    public function hash(string $code): string {
        return hash('sha256', $code . getenv('APP_SECRET'));
    }
}

$client = new SnippetClient('key', 'secret', codeHasher: new MyCustomHasher());
```

Methods
-------

[](#methods)

MethodDescription`snippet()`Async loader script. Place once per page.`conf(ConfOptions)`SDK configuration (notification renderer, CSS, callbacks…).`user(UserOptions)`Identifies the current user.`thread(string $selector, ThreadOptions)`Embeds a thread into a DOM element.`home(string $selector)`Embeds the notification center into a DOM element.All methods return a `SnippetCode` object with:- `->getCode()` — raw JavaScript string
- `->getHTML()` — wrapped in `…`

Options reference
-----------------

[](#options-reference)

### `UserOptions`

[](#useroptions)

ParameterTypeRequiredDescription`code``string`✅Unique user identifier (hash of your internal user ID + salt). Max 100 chars, `[a-zA-Z0-9-_]`.`name``?string`Display name.`emailAddress``?string`Used for email notifications.`readOnly``?bool`When `true`, the user can read but not send messages.`avatarURL``?string`Full URL to the user's avatar image. See `AvatarStyle` helper below.### `ThreadOptions`

[](#threadoptions)

ParameterTypeRequiredDescription`code``string`✅Unique thread identifier. Cannot be changed later. Max 100 chars, `[a-zA-Z0-9-_]`.`name``?string`Display name shown in the thread header.`url``?string`Canonical URL of the page. A link appears in the thread header.`userHint``bool`Enable @mention suggestions. Default: `true`.### `ConfOptions`

[](#confoptions)

See the full list of parameters in [`src/Options/ConfOptions.php`](src/Options/ConfOptions.php). Notable options:

ParameterTypeDescription`notificationRenderer``?string`JS function for custom notification rendering.`onNotification``?string`JS callback for new message count changes.`pageCSSPath``?string`CSS file URL injected into the snippet iframe.`notificationElementTargetElement``?string`JS expression returning the target DOM element.`notificationElementPosition``?int`Icon position: 1=top-left, 2=top-right, 3=bottom-right, 4=bottom-left.Avatar helper
-------------

[](#avatar-helper)

`AvatarStyle` generates Gravatar URLs without any external dependency:

```
use Stromcom\Snippet\Helper\AvatarStyle;

$url = AvatarStyle::ROBOHASH->generateUrl('user@example.com');
// or pass a pre-computed MD5 hash
$url = AvatarStyle::ROBOHASH->generateUrl(md5('user@example.com'));

echo $client->user(new UserOptions('u1', avatarURL: $url))->getHTML();
```

Available styles: `ROBOHASH`, `IDENTICON`, `MONSTERID`, `WAVATAR`, `RETRO`.

Docs mode
---------

[](#docs-mode)

Pass `withDocs: true` to the constructor (or per method) to generate annotated code with inline JSDoc comments — useful for generating integration guides:

```
$client = new SnippetClient('key', 'secret', withDocs: true);

echo $client->user(new UserOptions('u1'))->getHTML();
// outputs: stromCom.initUser({ /** User unique code (required) */ "code": "u1", … });
```

###  Health Score

38

—

LowBetter than 86% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c06fedcdd2c8d3e1263cef9a8326e2ccc0d9bd8b872384ab802b3db2873a28af?d=identicon)[stromcom](/maintainers/stromcom)

---

Top Contributors

[![stromcom](https://avatars.githubusercontent.com/u/7324198?v=4)](https://github.com/stromcom "stromcom (2 commits)")

---

Tags

integrationjavascriptphpsnippet-generatorstromcomwidgetchatintegrationsnippetstromcom

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/stromcom-php-snippet/health.svg)

```
[![Health](https://phpackages.com/badges/stromcom-php-snippet/health.svg)](https://phpackages.com/packages/stromcom-php-snippet)
```

###  Alternatives

[romka-chev/yii2-swiper

Yii2 extension for Swiper slider

1840.6k](/packages/romka-chev-yii2-swiper)[coldtrick/widget_manager

Manage your widgets

214.3k](/packages/coldtrick-widget-manager)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
