Luckily for me I discovered Laravel which is designed to be extendable. It also has an ever growing collection of bundles which allow users to easily share and install extensions from other users. As Campaign Monitor is a large international company I guessed other Laravel developers may want to use their API, so I spent an extra bit of time creating a neatly formed, easy to update bundle.

Getting to grips with the Campaign Monitor API PHP wrapper

Campaign Monitor very kindly provide various wrappers for their API but I was only interested in the PHP one. Normally I would consider starting from scratch and building a bundle/module from the ground up but as the wrapper from Campaign Monitor covers all the API requests possible and appears to be written in a decent enough fashion I decided to keep it in it's original state as it makes it easier to update if/when Campaign Monitor update it. Another reason for this is that I presume that it's well tested and the less work I do on it, the less chances I have of breaking it!

If you've looked at the PHP wrapper you'll see that Campaign Monitor have broken it down into 7 classes that deal with different sections of their system. The classes for campaigns, clients, lists, segments, subscribers and templates are all quite self-explanatory. The general just deals with everything else that doesn't fit into the previous 6 classes. The wrapper also contains a directory called class which is home to 'helper' utility classes that are used.

Setting the structure of the bundle

First things first - first things last would be stupid! lol! I created a directory in my application's bundle directory and gave it the incredibly imaginative name of campaignmonitor. Laravel is pretty flexible about where you stick any externally sourced libraries so I plonked them in a directory called vendor - I'm sure this is a habit I picked up from using Kohana PHP or CodeIgniter a few versions ago but I really can't remember! The only things left to do then was create an empty CampaignMonitor class in campaignmonitor.php and add a mapping to it in the start.php file so Laravel knows where to look for it. Both of these are in the root of the campaignmonitor bundle directory.

Creating the wrapper class

The first obverse thing to do was to split they Campaign Monitor API key into a separate file as each install would need to use a different key. I created a directory called config with a sample config file called campaignmonitor-sample.php in it for the API key to go in. (The idea is that you copy the template file campaignmonitor-sample.php to your applications config directory and rename it campaignmonitor.php.)

I wanted to be able to access all of the Campaign Monitor methods, across all the 7 classes, via a single point of entry that would be simple and flexible enough so if/when Campaign Monitor ever extended or altered their API classes it wouldn't require me to update much of my code - it would just be a case of replacing their files.

Revision #1

My first concept was to load a Campaign Monitor class like this - where CLASS_NAME would match one of the classes such as clients, lists or general:

CampaignMonitor::factory('CLASS_NAME');

This would use a single method, factory(), in my CampaignMonitor class to load the API key, include the correct Campaign Monitor file and return the initiated classes so that all the methods from with the classes could then be accesses like so:

// Example 1
$general = CampaignMonitor::factory('general');
$general->get_timezones();

// Example 2
CampaignMonitor::factory('clients', $client_id)->get_lists();

The issue I had with the way of doing it was mainly down to the second example above, as to access some libraries you needs to provide the id/key for the item - such as a client id for a client or a list id for a list.

This method of retrieving the data worked perfectly correctly but it just didn't seem to be as elegant as I'd have liked it to be so I had another think!

Revision #2

I decided to drop the factory method and make use of the __callStatic magic method instead. It would it use much of the same logic as the factory() method but would allow for clearer, more semantic coding when using the bundle. As you can see from the examples below you now choose the Campaign Monitor class with the method name rather than the first argument. You now only need pass in 1 argument if the Campaign Monitor classes requires a id.

// Example 3
$general = CampaignMonitor::general();
$general->get_timezones();

// Example 4
CampaignMonitor::clients($client_id)->get_lists();

I did start to try and implement a way of using the singulars for the method names, rather than plurals, as these would have been more semantically correct but I ran into the age old problem of list() being a native PHP function, and it was getting rather late and I wanted to go to bed so this was short lived!

And finally...

Now the bundle was all complete and committed into my GitHub account, all that was left to do was login to the Laravel Bundles site via GitHub, fill in a quick form and submit the bundle. Now it has its own special little page and can be installed by any Laravel user with one simple command...

$ php artisan bundle:install campaignmonitor

The way bundles are handled through Laravel are probably the best and easier way I've seen by a PHP framework. What I found was from the whole process is that, yet again, Laravel is kick-ass and does what I've been longing for a framework to do for ages - easy bundle creation and sharing in a way that just makes sense.

EXTRA NOTE: By the time I actually finished writing this blog post my bundle has been released for over a month and has had 86 installs at the time of publishing - I must of done something right!

The almighty - Wordpress

I wanted the core of my site to be a blog so where better to start looking then at everybody's friend - Wordpress. I was actually quite excited about using Wordpress. Even though I've been a web developer for over 5 years I never needed to use it so I was eager to see what all the fuss was about. I should of known better!

I spend my days ensuring all my code is keep neat and tidy. I keep the front-end stuff (HTML, CSS and javascript) as separate as possible from the functional PHP. I try to write re-usable code that is regularly (and sensibly) refactored so that classes and methods that sound like they should do the same thing - do the same thing! Anyway, enough ranting about what Wordpress doesn't do - as you might be able to tell I wasn't really impressed!

NOTE: I feel like I should mention that Wordpress isn't all bad. It is a well tested, well supported and feature rich blogging platform. It's just to messy and bulky for what I was after.

The familiar - PHP Frameworks

I've used various PHP frameworks nearly everyday through-out my working life. They are amazing. I can't speak highly enough about them. With this in mind I thought I may as well quickly knock up a quick blog using one and Twitter Bootstrap for the admin skin.

I thought I'd keep it interesting and start using one that I hadn't used at work. FuelPHP and Laravel seemed like a couple of good options as they are similar to my work staples of CodeIgniter and Kohana and have a good buzz surrounding them.

I started this process with great enthusiasm until I realised that at 11pm every night (which is the only time I get to work on personal stuff) I couldn't really be bothered to try get my head around a new framework and the whole thing was starting to feel abit like work!

The saviour - Kirby

I can't actually remember how I can across Kirby. I presume it was because I was trying to find a markdown-based cms and I just stumbled over it. I flicked through a few of the example site and saw that the vast majority where simple and minimal blog-style sites - just what I was after. I downloaded the free trail from GitHub and had a look through the codebase. Everything looked neat and lovingly looked after. I created a couple a test pages and a test template and everything worked just as it said it would.

I browsed through the documentation and started thinking of how I could construct a blog from the file-based approach it used. I though I'd have a click around the Kirby site to see what sort of stuff was possible. When I clicked on the Tutorials I was expecting, maybe, 3 or 4 very basic getting started guides, as is normally the case. I was pleasantly surprised to find that not only everything I was trying to do was possible, but it was all already accurately documented for me to follow. Perfect for late night coding!

A few tutorials and a couple of well thought out snippets and plugins later, I had a fully functioning blog with a nice clean HTML template to start styling. To complete all of the setup and development work for the blog it probably took less than an hour. Now I had plenty of time to style it and get it live before I would normally get fed up.

I raise my hat (if I had one) to the guys who made Kirby - it really does what it says on the tin (well, homepage) "Easy to setup, easy to use, flexible as hell".

The solution

My solution works by splitting the string, on the search variable, into an array and then joining the array values back into a string on the replace variable. Essentially it looks like this:

string.split(search).join(replace);

There are many arguments about extending the DOM prototype, which I am not going to go into here, so I've provided two varieties of the same solution - just use which ever one you agree with!

Extending the DOM prototype

This code should be put near the beginning of your javascript files as it needs to be loaded before the function can be called. The first argument is the string to be searched for and the second argument is the string to replace it with.

String.prototype.str_replace = function(search, replace) {

    return this.split(search).join(replace);

}

Example usage

This example will only work if used after the prototyping code above.

var string = 'this-is-a-test-string';

string = string.str_replace('-', '_');

console.log(string); // Should output 'this_is_a_test_string'

Normal functions instead of extending

The method above uses the prototype object to add extra functionality to the String object. If you prefer to just use basic functions then it could be written like the example below. Please note: Because the string variable needs to be passed as an argument to the function the search and replace arguments are now second and third - instead of first and second - respectively.

function str_replace(string, search, replace) {

    return string.split(search).join(replace);

}

Example usage

This example should work with the str_replace() function placed anywhere in an accessible namespace.

var string = 'this-is-a-test-string';

string = str_replace(string, '-', '_');

console.log(string); // Should output 'this_is_a_test_string'

Case sensitivity

The function IS case sensitive, which is fine for the example above which replaces hyphens with underscores, but you may need it to be case insensitive if you're replacing actual human readable text. In order to make is case insensitive you can pass a regular expression to search argument, as shown in the example below.

var string = 'this is a case sensitive string';

string = string.str_replace(/SENSITIVE/i, 'INsensitive');  // Extending
string = str_replace(string, /SENSITIVE/i, 'INsensitive');  // Non-extending

console.log(string); // Should output 'this is a case INsensitive string