Documentation

Installing and using the add-on is pretty simple: just install the package and you are ready to go. There is really nothing more you need to do, that is it!

However, some technical users might be interested in the inner workings of this add-on. This documentation explains how this add-on works. Also, for more advanced users, this add-on provides a few configuration options and also the possibility to customize the obfuscation method for your needs. These are also explained in this documentation.

Obfuscation methods

The following sections explain the obfuscation methods provided by this package by default.

HTML character references (default)

The default HTML character references obfuscation method works as follows:

  • @ letters will be replaced in all email addresses with (at)
  • The whole e-mail string, e.g. email(at)address.com, will be obfuscated with the HTML character references, so the example address would translate in the source to:
    • email@address.com
  • mailto-links will be modified to #MAIL:obfuscated_email_address. The default obfuscation method is the same as for the plain e-mail addresses.
  • For deobfuscation purposes, all email links (the <a> element) will be given class name "obfuscated-link"
  • The email addresses inside the link and also email addresses outside any links will be wrapped inside a <span> element with the class name "obfuscated-link-text"

This method is probably the weakest one obfuscation wise but it makes the add-on accessible and usable even without JavaScript enabled in the browser.

RTL form of the emails

If you want to use the rtl-obfuscation method you need to add the following to your application/config/app.php:

<?php

return array(
    // ... some other configurations ...
    'obfuscator' => array(
        'method' => 'rtl',
    ),
    // ... some other configurations ...
);

This method works as follows:

  • All the emails (e.g. email@address.com) are reversed so the result would be moc.sserdda@liame
  • For all the mailto-link hrefs, "mailto:" is replaced with "#MAIL:" so that users will not be trying to send mail to the wrong address
  • The JavaScript deobfuscator converts the rtl text back to normal text for easier copy pasting for users

This method is stronger than the default HTML character references method but it is not as good accessibility wise without JavaScript. The addresses are visible normally also without JavaScript through the magic of CSS (direction property) but if someone copies the address by highlighting it, it will be reversed when they paste it somewhere. The JavaScript deobfuscator fixes this problem, though.

Vigenère cipher

The Vigenère cipher obfuscation method is strong enough to fool any bots. Thanks to user mnakalay it is available also for the Automatic Email Obfuscator! He was also the first person to put the extendable obfuscation method architecture to the test.

More information about the encryption algorithm is available from Wikipedia.

This method does not work without JavaScript!

If you want to use the Vigenere cipher method you need to add the following to your application/config/app.php:

<?php

return array(
    // ... some other configurations ...
    'obfuscator' => array(
        'method' => 'vigenere',
    ),
    // ... some other configurations ...
);

This is by far the strongest of the obfuscation methods but also the weakest accessibility wise. If you are really worried about bots stealing email addresses from your site, use this method to sleep well at night.

Writing your own obfuscation method

Not pleased with the default obfuscation methods? You are welcome to easily write your own. It is done by writing your own email obfuscator class and overriding the 'automatic_email_obfuscator/obfuscator' service binding.

First, create your obfuscator class in the /application/src/EmailObfuscator folder. You can use one of the existing obfuscator classes (e.g. /packages/automatic_email_obfuscator/src/EmailObfuscator/HtmlObfuscator.php) as the basis for your own. Please note that you will need to change the namespace of the class when you copy it to the application folder. The class should look something like this:

>?php
// Example for /application/src/EmailObfuscator/YourObfuscator.php
namespace Application\Src\EmailObfuscator;

use Concrete\Core\Asset\AssetList;
use Concrete\Core\Http\ResponseAssetGroup;
use Concrete\Package\AutomaticEmailObfuscator\Src\EmailObfuscator\AbstractObfuscator;

class YourObfuscator extends AbstractObfuscator
{

    public function registerViewAssets()
    {
        // If your obfuscator needs client side deobfuscation, use the following
        // example to provide the asset to the view.
        // Defining this method is optional, remove it if you do not need client
        // side deobfuscation.
        $al = AssetList::getInstance();
        $al->register(
            'javascript', 'automatic_email_obfuscator/your', 'js/email_deobfuscator_your.js'
        );

        $r = ResponseAssetGroup::get();
        $r->requireAsset('javascript', 'automatic_email_obfuscator/your');
    }

    public function obfuscateMail($email)
    {
        // TODO: Write your obfuscation for the plain text emails
        return $email;
    }

    public function obfuscateMailtoLinkHref($href)
    {
        // TODO: Write your obfuscation for the <a> element's mailto-links
        return $href;
    }

}

If you register any client side deobfuscator scripts in your code, use the following example snippet to define the actual deobfuscation script:

// Example for /application/js/email_deobfuscator_your.js
(function($){

$(document).ready(function() {
    // All links with obfuscated mailto href-attributes can be fetched with the "obfuscated-link" class
    $("a.obfuscated-link").deobfuscateEmailLink();
    // All plain text email addresses are wrapped within span elements with the class name "obfuscated-link-text"
    $("span.obfuscated-link-text").deobfuscateEmailLink();
});
$.fn.deobfuscateEmailLink = function() {
    $(this).each(function() {
        // TODO: Write your deobfuscation method here
        // You can check example from the deobfuscator scripts included in the package.
    });
};

})(jQuery);

Once all this is done, all you need to do is to is to override the service binding for the 'automatic_email_obfuscator/obfuscator' service. This can be done in /application/bootstrap/app.php and the code you need to use in order to achieve this, is something like in the following example:

Core::bind('automatic_email_obfuscator/obfuscator', function() {
    return new \Application\Src\EmailObfuscator\YourObfuscator();
});