PHPackages                             cleantalk/contacts-encoder - 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 & Helpers](/categories/utility)
4. /
5. cleantalk/contacts-encoder

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

cleantalk/contacts-encoder
==========================

CleanTalk ContactsEncoder class

2.0.19(1mo ago)01.5k↑340%GPL-3.0-or-laterPHPCI passing

Since Mar 30Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/CleanTalk/contacts-encoder)[ Packagist](https://packagist.org/packages/cleantalk/contacts-encoder)[ RSS](/packages/cleantalk-contacts-encoder/feed)WikiDiscussions master Synced 2w ago

READMEChangelogDependencies (13)Versions (24)Used By (0)

Contacts Encoder - Quick Start Guide
====================================

[](#contacts-encoder---quick-start-guide)

Overview
--------

[](#overview)

The Contacts Encoder protects email addresses and phone numbers from spam bots. It requires **4 essential components** to work properly:

1. PHP backend with encoder configuration
2. Server-side encoding of HTML content
3. Frontend CSS/JS assets
4. AJAX decode endpoint

Since **2.0.19**, decode requests are validated via built-in `checkRequest()` → `Cleantalk::checkBot()` (`cleantalk/antispam` is installed automatically as a dependency).

[![Demo page with encoded email test cases](assets/images/demo-page.png)](assets/images/demo-page.png)

*Example: a stand-alone demo page with multiple email encoding scenarios. Click an obfuscated contact to decode it.*

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

[](#requirements)

- PHP 7.4+ (OpenSSL recommended for encryption)
- Composer
- A valid CleanTalk access key (`api_key`)

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

[](#installation)

```
composer require cleantalk/contacts-encoder
```

This also installs `cleantalk/antispam` (^1.6) for bot validation on decode.

Complete setup in 4 steps
-------------------------

[](#complete-setup-in-4-steps)

### Step 1: PHP backend setup

[](#step-1-php-backend-setup)

#### 1.1 Configure parameters

[](#11-configure-parameters)

```
use Cleantalk\Common\ContactsEncoder\Dto\Params;

$params = new Params();
$params->api_key = 'your_cleantalk_api_key'; // REQUIRED for encryption and checkBot
$params->obfuscation_mode = Params::OBFUSCATION_MODE_BLUR;
$params->do_encode_emails = true;
$params->do_encode_phones = true;
$params->is_logged_in = false; // true skips checkBot for logged-in users
```

#### 1.2 Optional: platform-specific class

[](#12-optional-platform-specific-class)

Extend `ContactsEncoder` only when you need custom UI text. Built-in `checkRequest()` is used by default since 2.0.19.

```
use Cleantalk\Common\ContactsEncoder\ContactsEncoder;
use Cleantalk\Common\ContactsEncoder\Dto\Params;

class YourPlatformContactsEncoder extends ContactsEncoder
{
    public static function createParams(): Params
    {
        $params = new Params();
        $params->api_key = 'your_cleantalk_api_key';
        $params->obfuscation_mode = Params::OBFUSCATION_MODE_BLUR;
        $params->do_encode_emails = true;
        $params->do_encode_phones = false;
        $params->is_logged_in = false;

        return $params;
    }

    protected function getTooltip()
    {
        return 'Click to decode protected contact';
    }
}
```

Override `checkRequest()` only if you need custom validation instead of the default `checkBot` flow.

### Step 2: Encoding content

[](#step-2-encoding-content)

```
$encoder = ContactsEncoder::getInstance($params);
// or: YourPlatformContactsEncoder::getInstance(YourPlatformContactsEncoder::createParams());

$protectedHtml = $encoder->runEncoding($yourHtmlContent);

echo $protectedHtml;
```

### Step 3: Frontend assets

[](#step-3-frontend-assets)

Include assets from `vendor/cleantalk/contacts-encoder/assets/` at the end of ``:

```

```

### Step 4: JavaScript configuration

[](#step-4-javascript-configuration)

#### 4.1 Create config object

[](#41-create-config-object)

```
const encoderConfig = {
    decodeContactsRequest: (encodedNodes) => {
        return fetch('/your-ajax-endpoint', {
            method: 'POST',
            body: encodedNodes,
        }).then((response) => response.json());
    },

    texts: {
        waitForDecoding: 'Decoding contact...',
        decodingProcess: 'Please wait',
        gotIt: 'Got it',
        clickToSelect: 'Click to select the email',
        originalContactsData: 'Full address:',
        blocked: 'Access denied',
    },

    serviceData: {
        brandName: 'Your Site Name',
    },
};
```

#### 4.2 Initialize on frontend

[](#42-initialize-on-frontend)

```
new ContactsEncoder(encoderConfig);
```

**Important:** do **not** wrap `new ContactsEncoder()` in `DOMContentLoaded`. The library registers its own `DOMContentLoaded` listener internally. If you create the instance inside another `DOMContentLoaded` handler, click handlers may never attach.

Load scripts at the end of ``.

Decode endpoint
---------------

[](#decode-endpoint)

Create an AJAX endpoint that calls `runDecoding()`:

```