Links with the Link Obfuscator

This page is about the Kiwa Link Obfuscator extension, which helps to create email, phone and SMS links that are protected from spam bots.

Introduction
Installation
Usage
Options

Introduction

Spam bots constantly crawl websites for email addresses and phone numbers. The Link Obfuscator protects those links by encrypting them with the Rot47 algorithm. The link is decrypted in the browser by JavaScript, which is added automatically.

Installation

This library is made for the use with Composer. Add it to your project by running

$ composer require kiwa/link-obfuscator

Usage

The library provides three classes: Mail, Phone and SMS. All of them are used in the same way: instantiate the class by passing the target address and its output will be the HTML link followed by the JavaScript code.

Email links

<?php

use Kiwa\LinkObfuscator\Mail;

/** Basically equal to <a href="mailto:hello@bitandblack.com">hello@bitandblack.com</a> */
echo new Mail('hello@bitandblack.com');

The output looks like this:

<a data-href="%3E2%3A%3DE%40i96%3D%3D%40o3%3AE2%3F53%3D24%3C%5D4%40%3E" data-id="_klo0">|||96%3D%3D%40o3%3AE2%3F53%3D24%3C%5D4%40%3E</a><script>...</script>

The link text can be defined individually:

<?php

use Kiwa\LinkObfuscator\Mail;

/** Basically equal to <a href="mailto:hello@bitandblack.com">Mail us</a> */
echo new Mail('hello@bitandblack.com', 'Mail us');

Additionally, a subject or a body can be added to the email:

<?php

use Kiwa\LinkObfuscator\Mail;

$mail = new Mail('hello@bitandblack.com', 'Mail us');
$mail->setSubject('Contact request');
$mail->setMailBody('Hello, I would like to get in contact with you.');

echo $mail;

Phone links

<?php

use Kiwa\LinkObfuscator\Phone;

/** Basically equal to <a href="tel:004971199528660">+49.711.995286-60</a> */
echo new Phone('004971199528660', '+49.711.995286-60');

SMS links

<?php

use Kiwa\LinkObfuscator\SMS;

/** Basically equal to <a href="sms:004971199528660">Write us an SMS</a> */
echo new SMS('004971199528660', 'Write us an SMS');

An SMS body can be added with setSMSBody(string $body):

<?php

use Kiwa\LinkObfuscator\SMS;

$sms = new SMS('004971199528660', 'Write us an SMS');
$sms->setSMSBody('Hello, I would like to talk to you.');

echo $sms;

Options

Attributes

All three classes accept a third argument with additional HTML attributes. You can pass them as a named array, which is the recommended way:

<?php

use Kiwa\LinkObfuscator\Mail;

echo new Mail(
    'hello@bitandblack.com',
    'Mail us',
    [
        'class' => 'btn btn--primary',
        'title' => 'Write us an email',
    ]
);

/** Basically equal to <a href="mailto:hello@bitandblack.com" class="btn btn--primary" title="Write us an email">Mail us</a> */

Encryption

The Link Obfuscator uses the Rot47 algorithm per default. You can change this by adding a custom algorithm implementing the EncryptionInterface:

<?php

use Kiwa\LinkObfuscator\AbstractLink;

AbstractLink::setEncryption(new MyCustomEncryption());

Please note that the algorithm needs to be available in JavaScript as well. The JavaScript of the encryption is generated by the getJavascript() method of the encryption class.

JavaScript

Every link has its own JavaScript code appended; the first link of a page also contains the shared functions which are needed to make the links work. If you want to keep your page DRY and handle the JavaScript on your own, you can disable these parts:

<?php

use Kiwa\LinkObfuscator\AbstractLink;

AbstractLink::disableAddingActionJS();
AbstractLink::disableAddingBasicJS();
AbstractLink::disableAddingEncryptionJS();

You can then import the code into your own JavaScript files instead, for example:

import { handleLink } from "/vendor/kiwa/link-obfuscator/src/Basic";
import { encrypt } from "/vendor/kiwa/link-obfuscator/src/Encryption/Rot47";

global.encrypt = encrypt;

const links = document.querySelectorAll("a[data-id^='_klo']");

links.forEach((link) => handleLink(link));

Unique IDs

Every link receives a unique ID which is stored in the data-id attribute, so the id attribute stays free for your own usage. The default prefix is _klo. You can change it with:

<?php

use Kiwa\LinkObfuscator\AbstractLink;

AbstractLink::setUidPrefix('myCustomPrefix');

You can also read the unencrypted link target at any point, which is useful for debugging:

<?php

use Kiwa\LinkObfuscator\Mail;

$mail = new Mail('hello@bitandblack.com');
echo $mail->getLinkHref(); /** Prints `hello@bitandblack.com`. */

You can find the source of the extension under bitbucket.org/wirbelwild/kiwa-link-obfuscator.