library url-campaignify

pixelistik/url-campaignify

A PHP class to help add web analytics campaigns to URLs.

, _(*1)

URL-Campaignify

Background

The open source web analytics tool Piwik can use campaigns and keywords for categorising incoming links. They work by appending additional GET params to your HTTP URLs:, _(*2)

http://my-site.tld/?pk_campaign=newsletter-5&pk_kwd=header-link

Read more about this technique in the Piwik docs, _(*3)

Google analytics and probably most other analytics tool do basically the same thing., _(*4)

What

This class aims to make it easier to dynamically append such parameters to URLs., _(*5)

Single URLs

Instead of worrying about ? and & you can just do this:, _(*6)

$uc = new UrlCampaignify();

$url = "http://some-blog.tld/cms.php?post=123&layout=default";

$newUrl = $uc->campaignify($url, "newsletter-5", "header-link");

The result has properly appended parameters:, _(*7)

http://some-blog.tld/cms.php?post=123&layout=default&pk_campaign=newsletter-5&pk_kwd=header-link

Text blocks

You can also throw entire blobs of text at the function. It will find and campaignify all HTTP URLs in it., _(*8)

$uc = new UrlCampaignify();

$text = "Look at http://my-site.tld especially".
        "here: http://my-site.tld/news.htm";

$newUrl = $uc->campaignify($text, "newsletter-5", "header-link");

If you are expecting HTML input, it makes sense to only change the URLs in href attributes. Use campaignifyHref() for this. It will turn, _(*9)

See <a href="http://site.tld">http://site.tld</a> for more information.

into, _(*10)

See <a href="http://site.tld?pk_campaign=foo">http://site.tld</a> for more information.

Have a look at the test cases to see which situations and edge cases have been covered -- or not., _(*11)

Auto-number URLs in text blocks

All campaignified URLs in a text block are counted (starting at 1). You can use the current number of a URL in your keyword in sprintf() style. This is useful if you want to differentiate between several identical URLs in one text., _(*12)

$uc = new UrlCampaignify();

$text = "Here comes the header link: http://my-site.tld".
        "here is a long and verbose text".
        "and another link at the end: http://my-site.tld";

$newUrl = $uc->campaignify($text, "news", "link-%d");

Will give you, _(*13)

Here comes the header link: http://my-site.tld?pk_campaign=news&pk_kwd=link-1
here is a long and verbose text and another link at the end:
http://my-site.tld?pk_campaign=news&pk_kwd=link-2";

Domains

It only makes sense to add campaigns if you actually analyse them. This implies that you control the site and its analytics tool. You can restrict UrlCampaignify to only work on URLs on a given Domain. Just pass it to the constructor, _(*14)

$uc = new UrlCampaignify('my-site.tld')

Note that subdomains are not automatically included, so the above instance will not touch URLs on www.my-site.tld. You can specify multiple domains as an array, though:, _(*15)

$uc = new UrlCampaignify(array('my-site.tld', 'www.my-site.tld', 'my-other-site.tld'))

Installation

Using composer

URL-Campaignify matches the PSR-0 file layout and is on packagist. You should be able to simply type, _(*16)

composer require  pixelistik/url-campaignify:dev-master
composer install

to get the latest code from the master branch included into your project., _(*17)

Just grabbing the file

You can also simply download the single file that provides the class: https://github.com/pixelistik/url-campaignify/raw/master/src/Pixelistik/UrlCampaignify.php, _(*18)