I recently worked on a widget that displayed a live feed of songs from one of our radio station’s playlist. The system that runs our radio station outputs XML which is then fed to a database. A program turns that data into feeds that get pulled by other programs.

It’s common to use XML to share data between servers that use different technologies. The system that generates the playlist is proprietary, so XML provides an easy format through which this data can be shared.

What is XML?

The eXtensible Markup Language is a way to structure your data for sharing across sites. Some of the technologies that are crucial to the web like RSS (Real Simple Syndication) and Podcasts are special flavors of XML. The beautiful thing about XML is that you can easily roll your own for anything you need.

XML is easy to create because it’s a lot like HTML…except you can make up your own tags. Let’s say, for example that you’re putting together a feed for a list of songs playing at your own radio station. We’ll keep this simple, so we’ll just encode the name of the artist, the title of the song, plus the time when the song was played. We make up a couple of tags called <title> and <artist> and wrap each of them around a <song> tag. We’ll create a dateplayed attribute for each song with the date and time the song was played. You might encode something like that in this manner.

<songs>
    <song dateplayed="2011-07-24 19:40:26">
        <title>I left my heart on Europa</title>
        <artist>Ship of Nomads</artist>
    </song>
    <song dateplayed="2011-07-24 19:27:42">
        <title>Oh Ganymede</title>
        <artist>Beefachanga</artist>
    </song>
    <song dateplayed="2011-07-24 19:23:50">
        <title>Kallichore</title>
        <artist>Jewitt K. Sheppard</artist>
    </song>
</songs>

There’s some rules that you have to adhere to when creating XML data. If you’re familiar with XHTML…you’ll be right at home with some of these, but let’s review them:

• XML is case sensitive so <Title>` is not the same as <title>.
• All XML elements must have closing tags.
• XML requires a root element (the <songs> tag above serves as our root element)
• Attributes must be quoted
• Special characters (like & (&) and < (<) and > (>) signs) must be encoded.

XML is a bit more strict than HTML, but is real easy to create and deal with.

Introducing simpleXML

With simpleXML, it’s as easy as reading the XML and then accessing it’s contents through an easy to read object. Assuming we’ve got our XML file above saved as a file called songs.xml in the same folder as our php file, we can read the whole feed into an object with the following code.

<?php 
    $mysongs = simplexml_load_file('songs.xml');
?>

That’s it! The file can even be the URL of a feed on the web and not just a file on your hard drive. We now have an object that is a representation of our file. The songs object has been absorbed into the $mysongs variable. If we want to output the name of the first artist in our list we can refer to it like this:

<?php 
    $mysongs = simplexml_load_file('songs.xml');
    echo $mysongs->song[0]->artist;
?>

Notice that our XML tags are mapped as part of the object so we can get to any element simply by typing it’s name. Remember that arrays are 0 indexed in PHP so our first title would be our 0th title. Now, let’s output the third song title.

<?php 
    $mysongs = simplexml_load_file('songs.xml');
    echo $mysongs->song[2]->title;
?>

Working with Attributes

In order to get to our dates, we’ll need to know how to access attributes, the notation is slightly different than with tags, but just as easy. As a matter of fact, it works just like accessing an array element. Let’s see how you would take a look at the second song’s date.

<?php 
    $mysongs = simplexml_load_file('songs.xml');
    echo $mysongs->song[1]['dateplayed'];
?>

Making a list of songs

So now that we’ve got the basics of accessing elements, let’s write the code to make a complete list of our songs parsed by interpreting our XML file.

<?php 
    $mysongs = simplexml_load_file('songs.xml');
    echo "<ul id=\"songlist\">\n";
    foreach ($mysongs as $songinfo):
        $title=$songinfo->title;
        $artist=$songinfo->artist;
        $date=$songinfo['dateplayed'];
        echo "<li><div class=\"title\">",$title,"</div><div class=\"artist\">by ",$artist,"</div><time>",$date,"</time></li>\n";
    endforeach;
    echo "</ul>";
?>

We’re using a foreach statement here to go through each song and then parsing the information into a simple HTML list. You can use that in a regular HTML document or use it as a widget to display a list of songs.

Parsing a Flickr feed from a set

There are lots of XML feeds available for you to parse online. We can, for example, get a feed from a Flickr set for inclusion on a website. That way, when you update your Flickr set, the widget will automatically display this on your site. I’ve prepared a special set with some pictures of kittens. In order to get the XML for this feed, we can go to our page on Flickr and look for the XML icon at the bottom left of the screen.

We want to examine the feed to determine it’s structure. You can right click on that feed’s link on the flickr page and save it to your hard drive, then rename the file photoset.xml and open it up with your browser.

I’ve opened the XML file with Safari, which lets me take a look at the structure (Safari will normally try to push an RSS link to it’s built in reader, so saving it, giving it an XML extension and opening it will let us view the structure). I can see that each photo is stored as an <entry> tag in our XML. Inside this tag, there are two <link> tags. The first one has a link to our image on Flickr. The second one has a link to a medium sized version of our image.

I’m going to modify the code slightly and make an adjustment on the second link to get a small thumbnail of all of our images. Before I do that, I’ll go back to Flickr and right click on the link to the XML file and this time copy it to the clipboard, then adjust the code:

<?php 
    $mypix = simplexml_load_file('http://api.flickr.com/services/feeds/photoset.gne?set=72157627229375826&nsid=73845487@N00&lang=en-us');
    foreach ($mypix->entry as $pixinfo):
        $title=$pixinfo->title;
        $link=$pixinfo->link['href'];
        $image=str_replace("_b.jpg","_s.jpg",$pixinfo->link[1]['href']);    
        echo "<a href=\"",$link,"\"><img src=\"",$image,"\" alt=\"",$title,"\" /></a>\n";
    endforeach;
?>

We’re going to use the <title> tag as the alt text of our <img> tag. We’re also going to use the first of the <link> tags as the href attribute of our anchor tag. Getting to our second link will be a bit trickier. We can use the array notation to get to the second link’s href attribute ($pixinfo->link[1]['href']). However, that will give us a much larger picture than we’ll need. I’m using a simple str_replace function to change the end of our link url from _b.jpg, to _s.jpg. That will give us thumbnails, which gives you something like this.

Conclusion

SimpleXML is super easy and even fun to use to parse complicated feeds like the example from Flickr. Notice that it had no problems getting to the second instance of the <link> tag inside the <entry> tag. This would have been really difficult to do with previous versions of PHP. There’s a lot more to simpleXML, which you can read in the PHP manual. If you’re interested in an object oriented approach, PHP5 also provides the SimpleXMLElement class.

If you’d like to learn more PHP, feel free to head over to the Think Vitamin Membership PHP course.

PHP is an amazing language. Powerful enough to be at the core of the biggest blogging platform (WordPress), deep enough to run the largest social network (Facebook) yet easy enough to be a beginner’s first server side language. It’s available in even the cheapest shared hosting services and with tools like WAMP and MAMP, it’s easy to install on a local machine. The language has rich libraries of pre-built functions that make it easy for developers to get things done. A great place to get started is the rich ‘date’ functions since working with dates is at the core of many projects.

Setting up

PHP is a server side language, which means that unlike regular HTML, you can’t preview it in your machine’s browser by default unless you use a solution like WAMP or MAMP to run a a copy of the services on your machine. Before you preview these example on a browser, make sure you’ve set up a good testing environment.

PHP code is often embedded onto an existing HTML page which is almost always saved with a .php extension. The .php extension tells the server that it needs to process the php in the file before it sends it to the client. The client won’t see any of the PHP code, they see the results of the processed code.

Getting a simple date

We’re going to use the echo command to output something to our client’s browser…in this case, the date. We’ll do this in a basic page with the following code.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <title>Getting started with dates in php5</title>
</head>
<body>
    <?php echo "Today is ",date('l'); ?>
</body>
</html>

If you’ve set things up correctly, you should see something like this on your browser:

Today is Sunday

The function outputs the text for the name of the day of the week. The date function takes at least one parameter…a string that tells the function how to format the current date.

Trying out different formats

If you look at the manual for the PHP date function, you’ll see that there are many ways to format dates. So, to get a date that would work as input for a MySQL database, you might use.

<?php echo "Today is ",date('Y-m-d'); ?>

Which yields

Today is 2011-06-26

There are some dates that are so common so there’s a few constants you can use. For example to get a date for your cookies you can use:

<?php echo "Today is ",date(DATE_COOKIE); ?>

Which gives you something like:

Today is Sunday, 26-Jun-11 16:26:22 EDT

Note that the quotes are gone when using constants.

What about time?

If you want to output the current time, you can use date() with a different formatting string.

<?php echo "The time is ",date('g:i:sa'); ?>

Gives you:

The time is 6:06:25pm

Localizing your time zone

If you notice that the time you got back from the code above is not the right time, then more than likely, it’s due to a the fact that your server is set up for a different timezone. If you need the time to correlate to a specific location, then you can use something like this:

<?php 
    date_default_timezone_set('America/New_York');
    echo "The time is ",date('g:i:sa');
?>

This will set the time to Eastern Standard Time in the US. This is a PHP5 function (so be careful with older versions of PHP) and there are a number of strings you can use here to convert the time to your local timezone. If you need this on a more permanent basis, you should probably change your php.ini file.

Getting other dates

Often, you’ll need to do something with a date other than the current date. When you create a date with the date() function, the system uses the Unix system time, which is calculated as the number of seconds from January 1 1970 00:00:00 GMT, otherwise known as the Unix Epoch time.

To specify that the date function return something other than the current date, you can simply feed it the number of seconds since that date as the second parameter to the function:

<?php echo "Today is ",date('Y-m-d', 1309133434); ?>

Which results in:

Today is 2011-06-26

That doesn’t seem particularly useful, but it means that you can use the date functions to do calculations. But before you do that, you need an easier way to creating dates.

Creating Dates

There’s a couple of ways to do that. We can use the mktime() function to create times from a number of parameters we feed this function.

<?php 
    $mytime=mktime(9, 23, 33, 6, 26, 2011);
    echo "Today is ",date('Y-m-d g:i:sa', $mytime);
?>

This results in the following:

Today is 2011-06-26 9:23:33am

You can tell from the example that the parameters you pass stand for the hour, minute, seconds, month, day and year you want to create. This is a good way of creating dates but there’s an even cooler way to do it.

Getting a date from a string

You can use the strtotime() function to have php convert a human readable string to a Unix time. PHP is quite smart about converting this string to a date so you can plug in a variety of values. Here’s an easy example:

<?php 
    $mytime=strtotime("7:50pm June 26 2011");
    echo "Today is ",date('Y-m-d g:i:sa', $mytime);
?>

Will output:

Today is 2011-06-26 7:50:00pm

PHP is quite clever about interpreting the string, but it’s not perfect, so make sure you test the string you put in there. This is a great way to convert MySQL or other types of strings let’s you use english-like instructions. So you can do things like:

$nextfriday=strtotime("next Friday"); //next friday
$nextmonth=strtotime("+1 Month"); //On month from today
$lastchristmas=strtotime("-1 year dec 25"); //last christmas

Getting a date range

The values strtotime returns are converted to numbers that can be compared with simple arithmetic, so you can do interesting things with them. Let’s say, for example, that you’re teaching a class for the next 16 weeks starting next Tuesday. You’re not sure when 16 weeks from now is, plus, you’d like to get the date of each of your classes so you can start preparing your curriculum. You can do something like this.

<?php 
    $startdate=strtotime("next Tuesday"); 
    $enddate=strtotime("+16 weeks",$startdate); //16 weeks from the starting date
    $currentdate=$startdate;
 
    echo "<ol>";
    while ($currentdate < $enddate): //loop through the dates
        echo "\t<li>",date('M d', $currentdate),"</li>";
        $currentdate = strtotime("+1 week", $currentdate); //increment the current date
    endwhile; // calculate date range
    echo "<ol>";
?>

This will show something like this:

 1. Jun 28
 2. Jul 05
 3. Jul 12
 4. Jul 19
 5. Jul 26
 6. Aug 02
 7. Aug 09
 8. Aug 16
 9. Aug 23
10. Aug 30
11. Sep 06
12. Sep 13
13. Sep 20
14. Sep 27
15. Oct 04
16. Oct 11

Notice this line $currentdate = strtotime("+1 week", $currentdate). On this line, you can see that strtotime can if you specify a date number as the second parameter, strtotime will use than instead of the default (today) for it’s calculations.

Days until a certain date

When working on a calendar, a common calculation is to find out the amount of days until a certain date. You can easily calculate the days until next thanksgiving in the US, which is on the fourth thursday in November.

<?php 
    $someday=strtotime("3 weeks thursday November 1");
    $daysuntildate=ceil(($someday-time())/60/60/24);
    echo "There are ",$daysuntildate," until Thanksgiving";
?>

First, we started by calculating the thanksgiving date which was 3 weeks after the first thursday from November 1st (or the same thing as the fourth thursday). Then we used some simple arithmetic to calculate the difference between that date and the current time. When we do a comparison, we use the time() function because it gives us the current date in seconds from the Unix Epoch date.

That number is the number of seconds between those two dates. We do a simple calculation to divide that number by the minutes/hours/days (60/60/14) and we get the number of days between the two numbers. We need to use the ceil function which rounds any fractions we’re left over after our calculation.

Having fun with dates

If you’re just getting started with PHP, working with dates is a great way to get the feel of the language. There’s quite a lot of fun things you can do. Dig around the Date and Time related functions in the PHP manual and share what you can do.

This video is from Think Vitamin Membership, a high-quality video training site, curated by us at Carsonified and Think Vitamin, with hundreds of short videos on topics like …

• Accessibility
• CSS3
• Design
• Django
• HTML & CSS
• HTML5
• JavaScript
• jQuery
• NoSQL
• PHP
• Ruby
• Ruby on Rails
• SASS
• UX
• Version Control
• WordPress Theme Design

10 new videos are added every week, so it’s a great way to stay up-to-date on all the latest technology and methods. Browse the entire library of videos.

In this 8-minute video tutorial on PHP Password Hashing, you’ll learn how to improve your authentication code by taking passwords out of cleartext.

This video is from Think Vitamin Membership, a high-quality video training site, curated by us at Carsonified and Think Vitamin, with hundreds of short videos on topics like …

• Accessibility
• CSS3
• Design
• Django
• HTML & CSS
• HTML5
• JavaScript
• jQuery
• NoSQL
• PHP
• Ruby
• Ruby on Rails
• SASS
• UX
• Version Control
• WordPress Theme Design

10 new videos are added every week, so it’s a great way to stay up-to-date on all the latest technology and methods. Browse the entire library of videos.

This video is from Think Vitamin Membership, a high-quality video training site, curated by us at Carsonified and Think Vitamin, with hundreds of short videos on topics like …

• Accessibility
• CSS3
• Design
• Django
• HTML & CSS
• HTML5
• JavaScript
• jQuery
• NoSQL
• PHP
• Ruby
• Ruby on Rails
• SASS
• UX
• Version Control

10 new videos are added every week, so it’s a great way to stay up-to-date on all the latest technology and methods. Browse the entire library of videos.

As Wired reported back in March Twitter’s Evan Williams promised @Anywhere would “reduce friction.”

“You could be reading your favourite columnist [and] you can easily tweet from the column itself if […] you may just want to follow the columnist […] without going back to Twitter.”

Amongst the launch partners for @Anywhere were Digg, Huffington Post and The New York Times. And one of the most high profile users the little known Follow Finder from The Mighty Google.

But alas, it was more a fizzle than a firework and like many at the time I was rather nonplussed.

I’m pleased to say I’ve been completely converted. Not only is playing with Twitter inherently a cool thing to do, it can add real power to your website and more importantly your web applications. Indeed, it’s the scope for easily including Twitter functionality in web applications that’s really exciting.

So let’s take a look at some of this functionality and how you can use it. You’ll be up and running in just minutes, and after briefly looking at some of the simpler methods we’ll dive straight in to integrating Twitter right into your web app.

Registering for @Anywhere

The first thing you need to do is register for an Application ID. It’s ridiculously simply to get, but perhaps worth some explaining to the uninitiated. First head on over to http://dev.twitter.com/anywhere and click on the ‘Start using it now’ button.

You’ll be swiftly taken to a one-page form where you register your app. The first question, particularly to those new at this whole API game, is ‘what if I don’t have an app?’.

Let’s say you just want to use hovercards on your blog. Or let’s say you want your users to be able to tweet about your blog articles by providing them a tweet box at the footer of each page. Not really an ‘app’ is it? More of a feature, a widget perhaps.

Well, in the big wide world of APIs what you have is a web app my friend and you need to accept it! Even the humble ‘Linkify’ method (automatically turning all Twitter usernames into links to their profiles) makes your humble blog post a web application of sorts. Deal with this fuzzy distinction and move on. We need that app ID!!

NB: For the rest of this article I’ll use the term app/application, but it equally applies to your site/blog

Completing the Form

Application Name

Name your application wisely because users will see this name when they are asked to authorise your app; although it’s worth noting that certain functionality, like linkifying and hovercards, doesn’t require users to see this name.

Callback URL

If you intend to use some of the @Anywhere functionality which requires users to authenticate your app then Twitter needs to know which page to send the API response to (which includes lots of handy data about the user that we can tap into using JavaScript!). The callback URL is most likely the very same page that has called the authentication.

If you’re only using simple @Anywhere methods like linkify you can just put your site’s homepage in here.

Default Access Type

This defaults to Read-only, but we want to use some advanced @Anywhere methods so make sure you change this to Read & Write.

Basic functions

Okay, we’ve filled up this car with petrol/gas so it’s time to take it out for a spin! Open a new HTML document and in the <head> of the document include the following line of code:

1

<script src="http://platform.twitter.com/anywhere.js?id=YOUR-APP-ID-GOES-HERE&v=1"></script>

Don’t forget to add your app ID into the URL.

Before I go on I feel I must address those of you who now resemble Yosamite Sam, with steam coming out of their ears at the idea of ever including a JavaScript file at the top of a page. But including the anywhere.js file in the head makes a lot of sense for a number of reasons, outlined by Twitter themselves:

• It’s small. Less than 3kb to be exact, gzipped up into a tiny package.
• All dependencies for @Anywhere features are loaded asynchronously, so you only get what you need when you need it.
• Most importantly, when a user logs in and authenticates your app the Twitter login page redirects back to the callback URL. This happens in a pop-up window, so if anywhere.js is at the bottom of the page it’ll mean that the user sees your site in that pop-up before it disappears. Which looks bad and, as Twitter put it, ‘is a poor user experience’.

So leave it in the <head> and let’s move on. Now we need to initialise the a global @Anywhere object which we do with:

1
2
3

<script>
twttr.anywhere();
</script>

For those who have tried to run that script, you’ll see that nothing happens. That’s because we need to give it a callback function of some sort. For example, to linkify every Twitter username on a page you simply need:

1
2
3
4
5

<script>
twttr.anywhere(function(T) {
T.linkifyUsers();
});
</script>

What’s with the capital ‘T’? Well that’s just Twitter’s convention so we’ll stick with it, but you’re welcome to change it to a more descriptive name. An instance of the API client is passed into T for us to then call methods on, just as we’ve done above.

Run that puppy on a page which has a username in the markup and watch it magically turn into a link. It was roughly about now that I gave up on @Anywhere earlier this year, but stick with me here – it get’s better.

Hovercards

Another method that works in a similar way is Hovercards, which work in the same way.

1
2
3
4
5

<script>
twttr.anywhere(function(T) {
T.hovercards();
});
</script>

With linkifying and hovercarding under our belts its worth looking at another couple of handy features.

Scope

You can limit the scope of a method by passing in a CSS selector. A lot of you will spot that this looks a lot like jQuery and that’s because it’s using the same Sizzle selection engine.

For example, to linkify usernames only in the DIV with an ID of ‘sidebar’ you could use the following code

1
2
3
4
5

<script>
twttr.anywhere(function(T) {
T(‘#sidebar’).linkifyUsers();
});
</script>

Configuration Options

There are a number of option that we can pass to these methods, which we do in an object literal. Again, if you’ve used jQuery before then this will be nothing new to you:

1
2
3
4
5

<script>
twttr.anywhere(function(T) {
T(‘#sidebar’).hovercards({ expanded: true});
});
</script>

Adding {expanded: true} does exactly what it says – it renders the Hovercard in it’s expanded form from the off, rather than waiting for the user to click ‘more’.

Moving Swiftly On

I’m going to skip a bit here, which relates to some of the other configuration options you can use with the various “Anywhere methods. I highly recommend Twitter’s own documentation which you can find at http://dev.twitter.com/anywhere/begin.

Getting more Advanced

If you’ve spent much time surfing the interweb you’ve at some point seen that pop-up window asking you if you authorise an app or a site to play with your Twitter account.

If, like me, you blindly click yes you give that site direct access to lots of your personal (albeit public) information. Normally this isn’t a problem, but with great power comes great responsibility – as James Cunningham of Twifficiency fame (more at TechCrunch).

There are a couple of ways @Anywhere uses this connectivity. The first is with built in functions like the Tweet Box and the Follow button. Both need the user to login to Twitter and authorise your app, so both will cause the authorisation pop-up. We can call both like so:

1
2
3
4
5
6

<script>
twttr.anywhere(function(T) {
T('#follow-button').followButton("richardshepherd");
T('#tweet-box').tweetBox();
});
</script>

This places a follow button in the element with an ID of ‘follow-button’ (and which is set to follow my Twitter account!), and a tweetbox in the element with an ID of ‘tweet-box’.

You’ll can find further details of the Tweet Box and Follow Buttons in the official documentation, but I think it get’s much more exciting to look at connecting your app with someone’s Twitter account and pulling information from their public profile. So let’s go ahead and crank things up! It’s surprisingly simple.

1
2
3
4
5

<script>
twttr.anywhere(function(T) {
T(‘#connect’).connectButton({ size: “medium” });
});
</script>

And that’s it. Try it out, and you’ll see the familiar pop-up asking for you to authorise your app (the name you gave it when you signed up). You can change the size be replacing ‘medium’ with ‘small’, ‘large’ or ‘xlarge’.

Medium is the default, so if you’re happy with that you can remove it from the code. But how about your own custom connect button – how cool would that be? It turns out that the Twitter API has a signIn method which we can attach to any element: text, image or whatever you fancy.

Let’s say you have created your own CSS rollover button, applied to a span with and ID of twitterLogin. Here’s how you’d use JavaScript and the Twitter API to hook the signIn method to that span:

1
2
3
4
5
6
7

<script>
twttr.anywhere(function(T) {
document.getElementById(‘twitterLogin’).onclick = function() {
T.signIn();
}
});
</script>

We are now freed from the shackles of Twitter’s own graphics and buttons, which makes it possible to create a unique experience for your own app or site. If the user is logged in, the pop-up window will simply ask them to authorise your app. If they aren’t logged in to Twitter it will also ask them for their login details.

I Can Haz your Details?

So your web app now has a connect button, and let’s assume your user has clicked it and logged in/authorised your app. Sweet. What next?

You should have set the Twitter callback URL to the same page as your web app, which means the pop-up will disappear and your page will be sent a bunch of new data (think of it as an AJAX request and response). This means you can use Javascript to check if the user is connected with the rather handy isConnected method. And, assuming it’s all gone to plan, the currentUser property contains lots of handy information.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<script>
twttr.anywhere(function(T) {
if (T.isConnected()) {
// This user is connected. Awesome!
var user = T.currentUser;
var screenName = user.data(‘screen_name’);
alert(‘Hi there ‘ + screenName);
} else {
// the user isn’t connected, so probably best to show them
// a connect button!
T(‘#twitterLogin’).connectButton();
}
});
</script>

Admittedly the use of a JavaScript alert here is almost criminal, but you get the idea. Include jQuery and you can start injecting the DOM with lots of Twitter goodness, personalising the user’s experience.

So what other properties can we access, apart from Screen Name? Well, pretty much all of the user’s public profile information is up for grabs. Here are some of the most useful:

• description
• followers_count
• following
• profile_image_url
• location
• name
• time_zone

And you can check out a full like at http://dev.twitter.com/anywhere/begin#user-properties

So using our example above you could access the profile image with:

1

var imageHTML = ‘<img src=”’ + user.data(‘profile_image_url’) + ‘“ />’;

What Next?

Of course @Anywhere is no substitute for server side integration with the Twitter API, but it’s a lean way of enhancing your web app/web sites experience for Twitter users.

Have you started to use @Anywhere? If so, tell us how and whether you think it’s enhanced your web application or site. And which features would you like to see in @Anywhere in future releases?

Further reading

Have you been bitten by the @Anywhere bug? If so, here are some great places to find out more…

• http://www.slideshare.net/toddkloots/anywhere/
• http://platform.twitter.com/js-api.html

I also really like this integration of Twitter Hovercards into a WordPress blog comments

• http://www.binarymoon.co.uk/2010/05/integrate-twitters-wordpress-comments/

Today we’ll take a tour of some of the advanced concepts that we haven’t covered yet, and this will give you a complete toolbox for working with OOP using PHP.

Autoloading

This is a very key concept for actually using classes in PHP 5. Autoloading is a mechanism where you can specify where the code should look for a class name that follows a particular pattern. Once you have set this up, usually very early in the script when everything gets configured, then you can simply instantiate classes without having to expressly include their declaration files.

The autoload()function takes the name of the class and attempts to guess where to look for it, and it is common to split names by an underscore, which is why you see so many PHP classes with crazy long names like Zend_Auth_Adapter_DbTable – each underscore is a directory level, so this class declaration would be found in a file named DbTable.php in the Zend/Auth/Adapter directory.

To declare our own autoload function, we would do something like this:

1
2
3
4
5
6

function __autoload($classname) {
    $path = str_replace('_', DIRECTORY_SEPARATOR, $classname) . '.php';
    require_once($path);
}
 
$class = new My_Example_Penguin();

All our function does is replace the _ with the relevant directory separators, add a .php and then require the file. We could do much more complicated things here though, such as use a regex to check for different prefixes, add a library directory, whatever we need to. We can then load any of our classes that match the structure from anywhere in our code once we have declared the autoload – very handy!

Interfaces

Now that we can load our class definitions from any context in our application, this seems like an ideal time to discuss another advanced feature of OOP – Interfaces.

PHP does not have multiple inheritance, so each object can only have one parent, and the top-level parent of all objects is of type StdClass. However PHP does support interfaces, which allows polymorphism (one class which can look like another) in PHP.

Let’s start off straight away by looking at an example and how the syntax works:

1
2
3
4
5
6
7
8
9
10
11
12

interface Audible {
    function speak();
}
 
class Sheep implements Audible {
    function speak() {
        echo "baaa!";
    }
}
 
$sheep = new Sheep();
$sheep->speak();

In this example, we first declared our interface Audible, with a single method called speak(). This behaves like an abstract method – we can prototype it here but we must declare it in any class which implements this interface. If we don’t, we get an error just as we did with the abstract classes we saw in an earlier post in this series. When we call $sheep->speak() at the end of the script, we see the output “baaa!”

An important thing to note about interfaces is that it allows us to specify a subset of behaviours and then apply them to objects that need not necessarily be related to one another by inheritance. We can use interfaces to check than an object is capable of what we are about to ask it to do, before we actually do it.

Keeping with the noisy animals examples, consider this example containing the same interface as before with some additional animals.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

interface Audible {
    function speak();
}
 
class Sheep implements Audible {
    function speak() {
        echo "baaa!";
    }
}
 
class Fish {
}
 
class Dog implements Audible {
    function speak() {
        echo "woof woof!";
    }
}
 
$sheep = new Sheep();
if($sheep instanceOf Audible) {
    $sheep->speak();
} else {
    echo "*stares blankly*";
}

Notice here we’re using the instanceOf to check the type of the object. This will return true if the Object passed in is either the same type as the class name, a child type of that class, or if it or any of its parents implement the class name as an interface. This means that although our $sheep is of type Sheep, it will also appear to be of type Audible.

In the code example, our Sheep does implement the Audible interface, as does the dog so either of those animals would speak. If we instantiated a fish though, this does not implement Audible and so we would fall through to the other part of the conditional and see the output *stares blankly” … which sounds about right for a fish!

It is also worth noting that if, for example, the dog did have a method called speak() but was not declared to implement the Audible interface, it would fail the type check and the dog would then also stare blankly, so to speak.

Type Hinting

In the example above, we used the instanceOf comparison operator to check that an object with the correct capabilities had been received, but we can make this simpler by using type hinting in our functions and object methods. We can adapt the earlier example to illustrate how this works, like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

interface Audible {
    function speak();
}
 
class Sheep implements Audible {
    function speak() {
        echo "baaa!";
    }
}
 
class Fish {
}
 
class Dog implements Audible {
    function speak() {
        echo "woof woof!";
    }
}
 
function makeHeard(Audible $animal) {
    $animal->speak();
}
 
makeHeard(new Sheep());
makeHeard(new Dog());
makeHeard(new Fish());

Both sheep and dog speak as expected, but the fish causes PHP to throw errors since we did not pass the correct Object type. Type hinting is a very powerful tool in OOP, in all reusable code but especially when creating libraries or frameworks.

By specifying what kind of an object is expected, you can protect against mis-use of the function. This is less about controlling what people do with your precious code and more about making it clear what the method was expecting to receive, in object type and/or in the capabilities of the incoming item.

Fluent Interfaces

This is a neat trick that can often be seen in particular in framework code, so it is worth a mention here. A “fluent interface” is one where you can chain the methods together, useful especially where you would be calling a sequence of methods on the same object.

For this to work, each method to be chained needs to return the object it belongs to, so a class would look something like this (a jumper, the obvious progression from a sheep):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

class Jumper {
    public function setSize($size) {
        if($size >= 8 && $size size = $size;
        }
        return $this;
    }
 
    public function fold() {
        // fold the jumper
        return $this;
    }
 
    public function sell() {
        $this->sold = true;
        return $this;
    }
}

We could interact with our class using code that looks like this:

1
2
3
4

$blue_jumper = new Jumper();
$blue_jumper->setSize(12);
$blue_jumper->fold();
$blue_jumper->sell();

But with the fluent interface in place, we can alternatively do exactly the same thing using the method chaining:

1
2

$blue_jumper = new Jumper();
$blue_jumper->setSize(12)->fold()->sell();

You’ll often see this notation used in settings such as the database interfaces in frameworks (both Zend Framework and CodeIgniter spring to mind) and really anywhere else where you could be calling multiple methods on the same object in quick succession. Hopefully this makes it clear what is going on when you see all those arrows in a row!

Parting Thoughts on OOP and PHP

We’ve been through a whole host of OOP concepts in PHP, illustrating that the object model in PHP has much more functionality than the urban myths would have you believe. (In the defence of urban myths, when PHP first got “objects” in PHP 4, the result was neither pretty or complete, so there was some truth to that rumour 5+ years ago!)

This series of articles has been intended to give a good overview of the main features along with some examples on actually using these in your own applications and working with them when you see them in the wild.

If you’re still hungry for more then some interesting next topics would be reflection and the SPL extension in PHP – both give opportunities for doing some very nice tricks with PHP and objects.

If you are using objects, share your applications and ideas with us in the comments, we love to hear what you think of our posts and for you to share what you are building with these techniques!

Don’t forget to check out the video library for free videos as well as learning more about our new membership service.

Today Jim looks at getting started with the popular programming language PHP. In this 8 minute video he shows you how to install PHP and write your first lines of PHP code.

What are Exceptions?

Exceptions are the PHP 5 way of flagging up an unexpected event. They contain an information message, and can be extended just like any other object. Exceptions are thrown rather than warnings in newer PHP extensions, although you do still see extensions returning errors.

When an exception is thrown, we either catch it where it happens, or it causes the code to return to its calling context. If it isn’t caught there, it returns again, and so on. As usual it is easier to explain with examples than words!

Here is an example in which DateTimeZone objects are created, first with a valid timezone string of ‘Europe/Amsterdam’, then another with an invalid timezone ‘nonsense’:

1
2
3
4

$timezone = new DateTimeZone('Europe/Amsterdam');
var_dump($timezone);
 
$timezone2 = new DateTimeZone('nonsense');

As the documentation explains, DateTimeZone throws an exception when called with unexpected data. This indeed happens if you run the above script, and the exception appears as an error message from PHP, looking something like this:

Exception: DateTimeZone::__construct(): Unknown or bad timezone (nonsense) in /...../exception1.php on line 6

We don’t want our entire application to stop and spit out errors over a nonsense timezone, and working with exceptions means we can do so much more with these situations than we can with errors. We “catch” exceptions and can use the information in the exception itself and in the context of the current scope to decide how best to react.

This is a great improvement on the previous situation of having a few different error levels and only being able to choose whether to display, log or ignore each level as was the situation before PHP 5.

Handling Exceptions

We handle exceptions with a try/catch block like this:

1
2
3
4
5
6
7

try {
    $timezone2 = new DateTimeZone('nonsense');
    echo "time!";
} catch(Exception $e) {
    echo "Oops!  Something bad happened!";
    print_r($e);
}

The “try” bit goes around the code that you would normally write, but which contains operations which can cause an exception. The “catch” bit states what kind of exception to catch, and contains the code to execute if we do catch anything.

If you ran this script with a valid timezone as the argument to the DateTimeZone constructor, you would see the “time!” output and never enter the code inside the “catch” block. However in our example, an exception will be caused and so we jump straight into this block, without echoing “time!”.

This is a fairly key concept – the code in the try block actually stops and we jump into the catch block and start executing from there. Any code after the point at which the exception is throw simply isn’t run.

Inside an Exception

Exceptions can hold all sorts of information. If we inspect our Exception thrown by DateTimeZone’s constructor using print_r, we’d see something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

Exception Object
(
    [message:protected] => DateTimeZone::__construct(): Unknown or bad timezone (nonsense)
    [string:private] =>
    [code:protected] => 0
    [file:protected] => /home/lorna/data/personal/publish/thinkvitamin/exceptions/exceptions2.php
    [line:protected] => 4
    [trace:private] => Array
        (
            [0] => Array
                (
                    [file] => /home/lorna/data/personal/publish/thinkvitamin/exceptions/exceptions2.php
                    [line] => 4
                    [function] => __construct
                    [class] => DateTimeZone
                    [type] => ->
                    [args] => Array
                        (
                            [0] => nonsense
                        )
 
                )
 
        )
 
    [severity] => 2
)

Walking through the object, there are many useful elements here:

• message This contains a useful and relevant information message
• code By default this is zero but we can use this to include a numeric error code with our exception
• file Path to the file where this exception was thrown
• line Line number where the exception was thrown
• trace This is the stack trace, so you can see the stack of calls which were made before this exception was thrown

This is all valuable information and we can use it to inform how we handle errors in the catch block in our code. In addition we’ll take a look at how we can set these ourselves by making our own exceptions a little later on.

Throwing Exceptions

It isn’t only PHP itself that can throw exceptions, we can use exactly the same functionality in our own code. Here is a really simple example, taken directly from the PHP manual itself, of how to throw an exception manually.

1
2
3
4
5
6

function inverse($x) {
    if (!$x) {
        throw new Exception('Division by zero.');
    }
    else return 1/$x;
}

We simply throw a new Exception object, that we create as we need it. The string passed into the constructor becomes the object’s message property, and we can also pass a second argument to the constructor if we want to set the code property as well.

It is usual to throw exceptions in functions or methods, and then catch them from the location they are called – this lets the calling code decide what to do in the context of what it intended and is much more flexible than simple errors or having your methods return false and set an error string somewhere, which I’m sure is how I solved this before exceptions were introduced in PHP 5.

Extending Exceptions

The Exception object by itself is great, but we can extend it so that we can return additional information and different types of exceptions – so if one of a number of different scenarios actually happens, we can respond differently. Consider this script and in particular the takeTwoNumbers function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

class BigNumberException extends Exception { }
class FavouriteNumberException extends Exception { }
 
function takeTwoNumbers($a, $b) {
    if($a > 15 || $b > 15 || ($a + $b) > 20) {
        throw new BigNumberException('Keep it simple with smaller numbers');
    } elseif($a != 3 && $b != 3) {
        throw new FavouriteNumberException('But three is my favourite number!');
    } else {
        return $a + $b;
    }
}
 
try {
    echo takeTwoNumbers(3,9) . "\n";
    echo takeTwoNumbers(4,16) . "\n";
    echo takeTwoNumbers(7,5) . "\n";
} catch(Exception $e) {
    echo $e->getMessage() . "\n";
}

The function accepts two numbers, checks the values, and if there are any problems, throws a relevant exception. If the values are OK (and yes, this is a totally contrived example, in an effort to illustrate the concept without any complicating factors like the real world getting involved!) then the function simply adds them together and returns them.

Our calling script calls the function 3 times, with different number sets. The first one executes fine and the numbers get added together. However the second includes a large number and so an error is thrown, causing our code to jump to the “catch” block, and so the third function call is never made.

Although we declared empty classes to extend Exception here and so only the class name changed, you can do all sorts of things to help record the information you need. We would set custom error messages here (remember the helpful error message returned by DateTimeZone?), set error codes, or even set new properties of our own.

It depends on your application which of these is helpful but having the custom exception classes makes it very nice and tidy to do so. The differing class names let us detect what *kind* of a problem occured and what we want to do in response. When we catch an exception, we can state what kind of an exception we wanted to catch – so we can narrow ourselves down to only dealing with a known situation. We can also use multiple catch blocks, like this:

1
2
3
4
5
6
7
8
9

try {
    echo takeTwoNumbers(3,9) . "\n";
    echo takeTwoNumbers(4,16) . "\n";
    echo takeTwoNumbers(7,5) . "\n";
} catch(BigNumberException $e) {
    echo "Big Number: " . $e->getMessage() . "\n";
} catch(FavouriteNumberException $e) {
    echo "Favourite Number: " . $e->getMessage() . "\n";
}

In this example, we can handle the two types of exception differently. If any other type of exception were to occur, it wouldn’t be caught here, but instead would “bubble” up the stack, getting returned from the end of the second catch block to wherever this code was called from – in this very simple example we are in a simple PHP file but if we were nested in functions, the code would keep on returning until PHP caught the exception, or until it reached the top at which point it would show an error like the one we saw at the start of this post.

Uncaught Exceptions

So if an exception is thrown in a method, and not caught, it returns from the function to where that function is called from. If it isn’t caught here, it returns to where this code was called from, and so on until it reaches the top of the stack. If it gets to the top of the stack, uncaught, we’ll see the error we saw at the beginning of the post.

We can also give PHP instructions about how to handle any exceptions that get this far, using set_exception_handler. Many frameworks will do this and return nicely formatted messages, often logging the detail of the error so that users do not see it but developers can do so.

Here’s an example of a catch-all exception handling function:

1
2
3
4
5
6
7

function my_exception_handler($exception) {
  error_log("Uncaught " . get_class($exception) . " exception: " . $exception->getMessage() . "\n");
}
 
set_exception_handler('my_exception_handler');
 
throw new Exception('Oooops!');

All we need to do is declare our exception handling function and then tell PHP to use it for uncaught exceptions. This simple example simply passes a string to error_log function, which you can configure to behave however you need it to for your system. In a real-world application you might want to notify administrators of the problem or perhaps provide some nice feedback to the user in addition to logging the error.

Exceptions in Your Applications

Hopefully this has given some insight into what you can do with exceptions and how they interact with the rest of your object-oriented application. Even functional code needs awareness of exceptions since some core language elements now throw them, so it is worth making sure you have the exception handler declared alongside your existing error handler even if you don’t need to be extending or throwing exceptions yourself.

Are you extending the Exception class? What do you use this for? I’m really interested to hear about the various applications of this theory so let me know in the comments!

That was then. Now, at (long) last, we are able to give some of this control back to the client. Or, if you’re using WordPress for your own site, you’re able to take control of your menu system with a wonderful new drag-and-drop GUI rather than diving into the code.

New Menu System

The menu system is based on WooNavigation, a custom menu system used by the ubiquitous WooThemes in the latest versions of their custom framework. Although much of the code was rewritten for WordPress 3, the similarities are still clear.

Adii Pienaar from WooThemes recently told me:

“The new menu system that WooThemes contributed is firstly long overdue and is a massive benefit to every single WordPress user. In essence, this is such a basic feature of any CMS, but due to it being a benefit to all WP users, I think this is a significant new addition.”

Chris Coyier from CSS Tricks agrees:

“Personally I think this is a big step forward because, together with Custom Post Types, it is migrating WordPress towards a fully fledged CMS. The more power we can give the end user, the easier it is for developers and designers with an understanding of PHP to use WordPress as a content management solution.”

So, without further ado, let’s take a look at how it all works. Grab yourself a WordPress 3 install with a bunch of pages and a refreshing beverage. It’s thirsty work.

Activating a Custom Menu

If you’re using WordPress 3 with the (brand new) default Theme TwentyTen installed this next bit won’t apply, because it’s already set up to use custom menus, so let’s assume you’re working with an older theme or perhaps even building your own. When you log into WordPress, go to Appearance > Menus.

If your current theme doesn’t support custom menus you’ll see this error message:

This means we need to head over to functions.php and get our hands a little dirty with some code. Open up functions.php and add in the following code:

add_action('init', 'register_custom_menu');
 
function register_custom_menu() {
register_nav_menu('custom_menu', __('Custom Menu'));
}

register_nav_menu has two parameters here, the first is the slug we’ll use in our code and the second is the name our menu will have in the WordPress admin area.

Now before we head back over to the menu screen, let’s stay in the source code and tell WordPress wear to put this menu. The most likely place will be in header.php, but of course there is no reason you can’t put a menu anywhere on your page. To keep things simple for our first menu let’s open header.php and, at whatever point makes sense in your theme, add the following line:

<?php wp_nav_menu(array('menu' => 'custom_menu')); ?>

With just the default ‘About’ page in our theme, if we look at our site we’ll see the following in the source code:

<div>
<ul>
<li><a href="the-link-in-here" title="About">About</a></li>
</ul>
</div>

And that’s all there is to it! Of course, we can add in a bunch of options into that array. You can check out the details over at the WordPress codex and here are a few of the more important ones explained:

• menu – which menu to call. In our example we only have one but you can set up as many menus as you like
• container – what element is wrapped around the menu. The default is a standard <div> but if you’re playing with the new kids over at HTML5 you could always change this to <nav>
• container_class – the css class given to this container, helpful for custom styling
• menu_class – the css class given to the <ul> that is rendered. The default is ‘menu’, and again this is helpful for custom styling.
• depth – How many levels should the menu display. The default is 0′ which means all levels, but you can set this to perhaps 1′ or 2′ to limit how far a drop-down menu will render. Handy stuff!

That’s probably enough for our purposes, but it’s definitely worth checking out the WordPress codex because there are many options you can set, like adding text before and after menu items and links.

Using the GUI

So let’s get cracking with the user interface, where much of the magic happens.

The first thing we need to do is create our first menu (remember, we can have multiple menus) so I’ll imaginatively create one called ‘Our First Menu’. Type that in to the Menu Name field and hit the Create Menu Button.

Did you spot the check-box ‘Automatically add new top-level pages’? Well, do you?

Normally I don’t, because I figure if we’re going to the trouble of making a custom menu we probably don’t want it doing anything automatically. After all, we want complete control over our menu, so I don’t want WordPress dropping in a new page every time we create one. Maybe you do, and that’s okay with me too :)

Excellent! Our first menu is empty but we’re well on our way. Over on the left we’re told that our theme currently only supports one menu so we best make sure we’re using ‘Our First Menu’. Select it in the drop-down, and click Save.

Adding Pages to our Menu

So we’ve created a place in our theme for the menu, and now we’ve created the menu itself. Trouble is, there’s probably nothing in it. WordPress gives us three easy ways to add content to the menu, and the great news is that it doesn’t have to be content that sits in the WordPress site. For example, the first box on the left you’ll see is for Custom Links.

You could perhaps link to your twitter account like I have in the screen-shot above, and just click ‘Add to Menu’. It might be your portfolio, which you’ve hosted elsewhere, or links to live client sites. It might even be links to your favourite news sites. Whatever you choose, it’s great to know your menu can take your visitors anywhere.

The second (and probably most often used) way to add content to the menu is in the Pages’ box, under ‘Custom Links’.

As you can see, I’m working on a fresh install of WordPress 3 which gives me just two pages – Home, and About. Now ‘Home’ strictly speaking isn’t a page in the default configuration (although you can change that). For me, ‘Home’ is whatever resides at and in index.php.

Notice the tabs at the top of the ‘Pages’ box, which allow you to hunt around through content rich sites for exactly the pages you want. If you’re setting up your menu for the first time you might want to look in the ‘View All’ tab, or if you’re just adding in a page you might want to ‘Search’ for it.

I’m going to select both Home and About so I’ve got something to play with. If I hit ‘Add to Menu’ you can see that my menu is really starting to shape up.

Finally we have the ‘Categories’ box, which acts in much the same way as the ‘Tabs’ box. Again, as this is the default install of WordPress I only have one category, the much maligned ‘Uncategorized’.

I’m going to select it (most of my posts often accidentally end up in uncategorized!) and ‘Add to Menu’. This is what we now have:

Now before we move on you need to ‘Save Menu’, so go ahead and click it.

To prove that this has worked we can load up my simple blog (which has the TwentyTen theme installed) and marvel at it’s glory.

Menu Hierarchy

That’s cool but it’s also only the beginning. The next thing to look at is ordering your menu hierarchy. So far the menu items have just appeared in the order we added them, but we probably want to change this. The good news is that this the whole system is drag-and-drop, so go ahead and move things around.

What you’ll also notice is that you can create a hierarchy by dragging items onto other items. I’ve added a few more pages and created something that looks like this:

You can see I’ve created a hierarchy of pages as indicated by their indents, and I’ve also changed the name of ‘uncategorized’ to ‘The Blog’. If we whizz on over to the actual site, we can also see that WordPress has created a funky drop down menu for me.

Now it’s worth noting that TwentyTen is designed to style the menu as a drop-down, and that the actual HTML WordPress generates looks like this:

<div>
<ul id="menu-our-first-menu"><li id="menu-item-5"><a title="The home page" href="http://localhost/">Home</a></li>
<li id="menu-item-6"><a href="http://localhost/?page_id=2">About</a>
<ul>
<li id="menu-item-23"><a href="http://localhost/?page_id=9">Our Company</a>
<ul>
<li id="menu-item-21"><a href="http://localhost/?page_id=13">The Team</a></li>
</ul>
</li>
<li id="menu-item-22"><a href="http://localhost/?page_id=11">Our Products</a></li>
</ul>
</li>
<li id="menu-item-20"><a href="http://localhost/?page_id=15">Get in Touch</a>
<ul>
<li id="menu-item-19"><a href="http://localhost/?page_id=17">Office Locations</a></li>
<li id="menu-item-4"><a href="http://twitter.com/richardshepherd">My Twitter Stream</a></li>
</ul>
</li>
<li id="menu-item-8"><a href="http://localhost/?cat=1">The Blog</a></li>
</ul>
</div>

A Few More Options

You should also be able to see in the Menus admin that each menu has a drop-down arrow. Click on it, and you’ll see there are a few things you can tinker with.

• URL - The url which the menu item links to
• Navigation Label - What it will actually say in the menu
• Title Attribute - Useful for making your menu accessible, and you could also use some jQuery to grab this and create a piece of ‘description’ text
• Remove/Cancel - No prizes here

Menu Widgets

There’s one more thing we’ll look at in this introductory tutorial, and that’s the menu widget. So far all we’ve done is actually create a menu in our header and stick ‘Our First Menu’ into that hook. There is one other thing Custom Menu’s do out-of-the-box. In the WordPress admin head on over to Appearance > Widgets and we can take a look at the Custom Menu Widget.

It should be sitting under Available Widgets, so drag it over to one of your widgetized areas and let’s take a look at the options:

As you can see, there aren’t many! You can give the widget a title (I’ve called mine ‘Our Menu Widget’) and then select which menu you have created to use. Now we only created one menu in this tutorial, but you could of course create a second and drop it in here. Click ‘Save’, head on over to your site and you should see something like this:

And that’s it! Great for a sitemap-like feature, just remember that if your menu doesn’t automatically update when you add new pages neither will this widget.

Just the Beginning

As you can probably tell, there’s a lot going on with the Custom Menu feature. I’ve tried to stick to the basics here and focus on the GUI, but there is a lot more going on under the hood that is also worth looking into. If you feel confident with PHP then start playing – there’s so much more you can do.

If all you are looking for is a simple way to create and manage menus for you and your clients, we hope this overview gets you started. As always, we welcome your comments and look forward to seeing Custom Menus on your WordPress sites!

“They just got named poorly because they live in the Posts table in the database. Think of them more like custom objects/content types.”

Cool – it’s just custom content. What’s the point of that then? Can’t we just categorise blog posts and order our pages in nice hierarchies? Can’t we use conditionals to spit out different CSS stylesheets? Well yes, we could. But admit it – it’s not fun.

And hands up if you’ve ever tried to explain to a client what a custom field is. Hurts, doesn’t it? So thank goodness for wonderful people like Jane who have given us a solution.

What is it and What it isn’t

Everyone’s talking about them. I recently asked Chris Coyier from CSS-Tricks what excited him about WP3 and he replied custom post types:

“Think of how Tumblr works – how you can publish photos, quotes, links and whatever else. You could create those same types now with WordPress, and build themes to support and have special styles for them. This is fantastic stuff for building custom sites!”

Make sense? Well according to Jane, Chris misinterpreted their goal:

“Custom post types aren’t really meant for that use […] Custom post types are great for things that are more or less catalogued: products (in an e-commerce site), listings for a real estate site, etc. For regular content creation as described [by Chris], you can already do [that] by using custom taxonomies and/or stylesheets to make post templates.”

Now I’m going to go out on a limb here and say that Chris made a interesting suggestion. I say this for two reasons: firstly because I think the great thing about WordPress is we can use it in the way we feel it should be used. There might be a different or better way, but there is no wrong way to do something (unless it doesn’t work!). Secondly I refuse to believe that many designers would read up on something as scarily titled as ‘custom taxonomies‘.

Indeed I expect to see WordPress themes cropping up all over the place that mimic the way Tumblr themes look and work. WooThemes have already released three.

Get your Hands Dirty

Now before we dig in I want to say this – custom post types make things a lot easy for non-technical people to use the WordPress admin to enter content. However the designer/developer still needs to have a reasonable grasp of PHP and needs to be prepared to get their hands dirty (unless they opt for a plugin that does the job for you like http://wordpress.org/extend/plugins/custom-post-template/ or http://wordpress.org/extend/plugins/custom-post-type-ui/)

For our tutorial we’re going to be editing functions.php which is your theme directory. We’re simply adding to this file, so feel free to start at the top or at the bottom – just don’t change any of the code that’s already there. For the more confident of you out there you could adapt this code into a plugin.

With a few edits we are going to create a custom post type for our portfolio, and a template which will use this information. We’ll end up with a new panel in the admin menu which looks like this:

A new overview page called “My Portfolio”:

And a new place to enter our content:

Step 1

Here’s the first bit of code we need to add to functions.php, which I’ll review below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

add_action('init', 'portfolio_register');
 
function portfolio_register() {
 
	$labels = array(
		'name' => _x('My Portfolio', 'post type general name'),
		'singular_name' => _x('Portfolio Item', 'post type singular name'),
		'add_new' => _x('Add New', 'portfolio item'),
		'add_new_item' => __('Add New Portfolio Item'),
		'edit_item' => __('Edit Portfolio Item'),
		'new_item' => __('New Portfolio Item'),
		'view_item' => __('View Portfolio Item'),
		'search_items' => __('Search Portfolio'),
		'not_found' =>  __('Nothing found'),
		'not_found_in_trash' => __('Nothing found in Trash'),
		'parent_item_colon' => ''
	);
 
	$args = array(
		'labels' => $labels,
		'public' => true,
		'publicly_queryable' => true,
		'show_ui' => true,
		'query_var' => true,
		'menu_icon' => get_stylesheet_directory_uri() . '/article16.png',
		'rewrite' => true,
		'capability_type' => 'post',
		'hierarchical' => false,
		'menu_position' => null,
		'supports' => array('title','editor','thumbnail')
	  ); 
 
	register_post_type( 'portfolio' , $args );
}

Anyone who’s worked with WordPress before will recognise the structure here. We’re adding an action when the WP Admin initialises to call the function portfolio_register(). In that function we create two arrays, $labels and $args, and then use register_post_type to pull it all together. In doing so we name the new custom post type ‘portfolio’ and tell it to use the arguments from $args.

The devil is in the detail, so let’s run over some of those arguments. A full list can be found at http://codex.wordpress.org/Function_Reference/register_post_type. First let’s look at $labels:

• name – this is the (probably plural) name for our new post type
• singular_name – how you’d refer to this in the singular (such as ‘Add new ****’)

You can probably work out the rest of $labels for yourself, as they simply refer to different circumstances in which the name of your custom post type would be used.

And now $args:

• public – should they be shown in the admin UI
• show_ui – should we display an admin panel for this custom post type
• menu_icon – a custom icon for the admin panel
• capability_type - WordPress will treat this as a ‘post’ for read, edit, and delete capabilities
• hierarchical – is it hierarchical, like pages
• rewrite – rewrites permalinks using the slug ‘portfolio’
• supports – which items do we want to display on the add/edit post page

That’s the first simple step, and it should be enough to see your new custom post time in the WordPress admin. Save functions.php and take a look!

Step 2

The next thing we need to do is register a taxonomy. Or, in English, create categories for this new content type.

For example, in our portfolio we want to include the names of technologies and software used to create our work. I’m going to call this taxonomy ‘Skills’, and populate it with things like HTML, CSS and jQuery.

It’s just one line of code:

1

register_taxonomy("Skills", array("portfolio"), array("hierarchical" => true, "label" => "Skills", "singular_label" => "Skill", "rewrite" => true));

The first item here is the taxonomy name, ‘Skills’. The second is the name of the object type we’re applying it to, in our case the custom post type ‘portfolio’ (which is an array). Finally our arguments; you can find a full list at http://codex.wordpress.org/Function_Reference/register_taxonomy, and here we’re using just three which have the same meaning as described in Step 1.

Add that line of code in and you should now see:

You can then enter new ‘skills’ just like you’d enter categories for blog posts. It looks like this:

Step 3

The third step is to add custom data fields to the add/edit post page.

For our portfolio we can add things like the year the piece was published and details on who designed, built and produced the site/design.

There’s a bit more code here, but read through it in order and it should make sense:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

add_action("admin_init", "admin_init");
 
function admin_init(){
  add_meta_box("year_completed-meta", "Year Completed", "year_completed", "portfolio", "side", "low");
  add_meta_box("credits_meta", "Design & Build Credits", "credits_meta", "portfolio", "normal", "low");
}
 
function year_completed(){
  global $post;
  $custom = get_post_custom($post->ID);
  $year_completed = $custom["year_completed"][0];
  ?>
  <label>Year:</label>
  <input name="year_completed" value="<?php echo $year_completed; ?>" />
  <?php
}
 
function credits_meta() {
  global $post;
  $custom = get_post_custom($post->ID);
  $designers = $custom["designers"][0];
  $developers = $custom["developers"][0];
  $producers = $custom["producers"][0];
  ?>
  <p><label>Designed By:</label><br />
  <textarea cols="50" rows="5" name="designers"><?php echo $designers; ?></textarea></p>
  <p><label>Built By:</label><br />
  <textarea cols="50" rows="5" name="developers"><?php echo $developers; ?></textarea></p>
  <p><label>Produced By:</label><br />
  <textarea cols="50" rows="5" name="producers"><?php echo $producers; ?></textarea></p>
  <?php
}

First of all we call the add the admin_init function to the queue when the WordPress admin initialises, and within that function we add two meta boxes – places to enter our data. The context for these two statements is

1

<?php add_meta_box( $id, $title, $callback, $page, $context, $priority ); ?>

The only difference between the two is where we place them on the screen. The ‘year completed’ is placed in the sidebar using ‘side’ whilst the ‘credits’ are placed in the main flow of the page using ‘normal’.

Within the two functions there is some vanilla WordPress PHP code and HTML to help define our old friend custom fields. Make sure to include

1

global $post;

…so that we can then query the current post using

1

$custom = get_post_custom($post->ID);

Once the two new meta boxes have been added it looks like this:

The final thing to do in step 3 is to make sure we then save these values with this post. I do this with

1

add_action('save_post', 'save_details');

and

1
2
3
4
5
6
7
8

function save_details(){
  global $post;
 
  update_post_meta($post->ID, "year_completed", $_POST["year_completed"]);
  update_post_meta($post->ID, "designers", $_POST["designers"]);
  update_post_meta($post->ID, "developers", $_POST["developers"]);
  update_post_meta($post->ID, "producers", $_POST["producers"]);
}

There’s nothing too tricky here. Again we’re adding an action, this time to the ‘save_post’ event. It fires the function save_details() which uses update_post_meta (http://codex.wordpress.org/Function_Reference/update_post_meta) to save the relevant data.

Step 4

A nice little touch is to rejig the layout of the My Portfolio page to display some of this information. If you’ve followed through the article so far this should all make sense to you:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

add_action("manage_posts_custom_column",  "portfolio_custom_columns");
add_filter("manage_edit-portfolio_columns", "portfolio_edit_columns");
 
function portfolio_edit_columns($columns){
  $columns = array(
    "cb" => "<input type=\"checkbox\" />",
    "title" => "Portfolio Title",
    "description" => "Description",
    "year" => "Year Completed",
    "skills" => "Skills",
  );
 
  return $columns;
}
function portfolio_custom_columns($column){
  global $post;
 
  switch ($column) {
    case "description":
      the_excerpt();
      break;
    case "year":
      $custom = get_post_custom();
      echo $custom["year_completed"][0];
      break;
    case "skills":
      echo get_the_term_list($post->ID, 'Skills', '', ', ','');
      break;
  }
}

Here we’re adding two more functions to the WordPress Admin. The first, portfolio_edit_columns($columns), simply defines the columns. The first two arguments “cb” and “title” are part of the core so don’t play with those too much (you can of course rename “Portfolio Title”). It’s the next three that come from our custom post type, “description”, “year” and “skills”.

We have one more function to tell WordPress where to get this data from – portfolio_custom_columns($column). Using a simple switch/case we can define what data to actually show in the column layout. For the “description” we use the_excerpt(), for “year” we get the custom field data using get_post_custom(), and for “skills” we get a comma separated list of the terms/taxonomies/categories using get_the_term_list().

With that we have our customised columns:

One final touch

Be default custom post types will display using single.php, or index.php as a fallback. The great thing is we can create our own custom template using the filename single-xxxxxx.php. In our case this is single-portfolio.php. Just create your template file in your theme directory and the custom post type will use it. How you display the data is totally up to you.

Hey, did you also notice the ‘Featured Image’ option on the add/edit page. That works out-of-the-box thanks to the ‘thumbnail’ part of:

1

'supports' => array('title', 'editor', 'thumbnail')

You just need to make sure to include the following line of code in functions.php:

1

add_theme_support('post-thumbnails');

For more details check out this excellent post by Mark Jaquith.

Rewrite Problems?

There are a few reported problems out there about the rewriting of custom URLs; in short, they sometimes don’t work. However, if you’re experiencing this problem there are a couple of easy fixes.

First, simply go to the Settings > Permalinks page, which will flush the permalinks (assuming that your WordPress install can write to the .htaccess file). This should clear up most problems related to permalinks, custom post type related or not.

If that doesn’t work you can add a line of code after you register the post type:

1
2

	register_post_type( 'portfolio' , $args );
        flush_rewrite_rules();

This worked for me on a particularly problematic install.

Conclusion

And there we have it! That is a whistle-stop tour of custom post types which I hope gives you the appetite to explore further.

The best thing is to experiment with the code, read through the documentation in the WordPress Codex, and share your ideas with others. Like any new feature I’m sure it will evolve as users create new and exciting ways to use it, and we’d love to hear about how you’re using custom post types here at Think Vitamin.

The “magic” methods are ones with special names, starting with two underscores, which denote methods which will be triggered in response to particular PHP events.

That might sound slightly automagical but actually it’s pretty straightforward, we already saw an example of this in the last post, where we used a constructor – so we’ll use this as our first example.

__construct

The constructor is a magic method that gets called when the object is instantiated. It is usually the first thing in the class declaration but it does not need to be, it a method like any other and can be declared anywhere in the class.

Constructors also inherit like any other method. So if we consider our previous inheritance example from the Introduction to OOP, we could add a constructor to the Animal class like this:

class Animal{

  public function __construct() {
    $this->created = time();
    $this->logfile_handle = fopen('/tmp/log.txt', 'w');
  }

}

animal.php

Now we can create a class which inherits from the Animal class – a Penguin! Without adding anything into the Penguin class, we can declare it and have it inherit from Animal, like this:

class Penguin extends Animal {

}

$tux = new Penguin;
echo $tux->created;

If we define a __construct method in the Penguin class, then Penguin objects will run that instead when they are instantiated. Since there isn’t one, PHP looks to the parent class definition for information and uses that. So we can override, or not, in our new class – very handy.

__destruct

Did you spot the file handle that was also part of the constructor? We don’t really want to leave things like that lying around when we finish using an object and so the __destruct method does the opposite of the constructor. It gets run when the object is destroyed, either expressly by us or when we’re not using it any more and PHP cleans it up for us. For the Animal, our __destruct method might look something like this:

class Animal{

  public function __construct() {
    $this->created = time();
    $this->logfile_handle = fopen('/tmp/log.txt', 'w');
  }

  public function __destruct() {
    fclose($this->logfile_handle);
  }
}

animal2.php

The destructor lets us close up any external resources that were being used by the object. In PHP since we have such short running scripts (and look out for greatly improved garbage collection in newer versions), often issues such as memory leaks aren’t a problem. However it’s good practice to clean up and will give you a more efficient application overall!

__get

This next magic method is a very neat little trick to use – it makes properties which actually don’t exist appear as if they do. Let’s take our little penguin:

class Penguin extends Animal {

  public function __construct($id) {
    $this->getPenguinFromDb($id);
  }

  public function getPenguinFromDb($id) {
    // elegant and robust database code goes here
  }
}

penguin1.php

Now if our penguin has the properties “name” and “age” after it is loaded, we’d be able to do:

$tux = new Penguin(3);
echo $tux->name . " is " . $tux->age . " years old\n";

However imagine something changed about the backend database or information provider, so instead of “name”, the property was called “username”. And imagine this is a complex application which refers to the “name” property in too many places for us to change. We can use the __get method to pretend that the “name” property still exists:

class Penguin extends Animal {

  public function __construct($id) {
    $this->getPenguinFromDb($id);
  }

  public function getPenguinFromDb($id) {
    // elegant and robust database code goes here
  }

  public function __get($field) {
    if($field == 'name') {
      return $this->username;
    }
}

penguin2.php

This technique isn’t really a good way to write whole systems, because it makes code hard to debug, but it is a very valuable tool. It can also be used to only load properties on demand or show calculated fields as properties, and a hundred other applications that I haven’t even thought of!

__set

So we updated all the calls to $this->name to return $this->username but what about when we want to set that value, perhaps we have an account screen where users can change their name? Help is at hand in the form of the __set method, and easiest to illustrate with an example.

class Penguin extends Animal {

  public function __construct($id) {
    $this->getPenguinFromDb($id);
  }

  public function getPenguinFromDb($id) {
    // elegant and robust database code goes here
  }

  public function __get($field) {
    if($field == 'name') {
      return $this->username;
    }
  }

  public function __set($field, $value) {
    if($field == 'name') {
      $this->username = $value;
    }
  }
}

penguin3.php

In this way we can falsify properties of objects, for any one of a number of uses. As I said, not a way to build a whole system, but a very useful trick to know.

__call

There are actually two methods which are similar enough that they don’t get their own title in this post! The first is the __call method, which gets called, if defined, when an undefined method is called on this object.

The second is __callStatic which behaves in exactly the same way but responds to undefined static method calls instead (only in new versions though, this was added in PHP 5.3).

Probably the most common thing I use __call for is polite error handling, and this is especially useful in library code where other people might need to be integrating with your methods.

So for example if a script had a Penguin object called $penguin and it contained $penguin->speak() ... the speak() method isn’t defined so under normal circumstances we’d see:

PHP Fatal error:  Call to undefined method Penguin::speak() in ...

What we can do is add something to cope more nicely with this kind of failure than the PHP fatal error you see here, by declaring a method __call. For example:

class Animal {
}
class Penguin extends Animal {

  public function __construct($id) {
    $this->getPenguinFromDb($id);
  }

  public function getPenguinFromDb($id) {
    // elegant and robust database code goes here
  }

  public function __get($field) {
    if($field == 'name') {
      return $this->username;
    }
  }

  public function __set($field, $value) {
    if($field == 'name') {
      $this->username = $value;
    }
  }

  public function __call($method, $args) {
      echo "unknown method " . $method;
      return false;
  }
}

penguin4.php

This will catch the error and echo it. In a practical application it might be more appropriate to log a message, redirect a user, or throw an exception, depending on what you are working on – but the concept is the same.

Any misdirected method calls can be handled here however you need to, you can detect the name of the method and respond differently accordingly – for example you could handle method renaming in a similar way to how we handled the property renaming above.

__sleep

The __sleep() method is called when the object is serialised, and allows you to control what gets serialised. There are all sorts of applications for this, a good example is if an object contains some kind of pointer, for example a file handle or a reference to another object.

When the object is serialised and then unserialised then these types of references are useless since the target may no longer be present or valid. Therefore it is better to unset these before you store them.

__wakeup

This is the opposite of the __sleep() method and allows you to alter the behaviour of the unserialisation of the object. Used in tandem with __sleep(), this can be used to reinstate handles and object references which were removed when the object was serialised.

A good example application could be a database handle which gets unset when the item is serialised, and then reinstated by referring to the current configuration settings when the item is unserialised.

__clone

We looked at an example of using the clone keyword in the second part of my introduction to OOP in PHP, to make a copy of an object rather than have two variables pointing to the same actual data. By overriding this method in a class, we can affect what happens when the clone keyword is used on this object.

While this isn’t something we come across every day, a nice use case is to create a true singleton by adding a private access modifier to the method.

__toString

Definitely saving the best until last, the __toString method is a very handy addition to our toolkit. This method can be declared to override the behaviour of an object which is output as a string, for example when it is echoed.

For example if you wanted to just be able to echo an object in a template, you can use this method to control what that output would look like. Let’s look at our Penguin again:

class Penguin {

  public function __construct($name) {
      $this->species = 'Penguin';
      $this->name = $name;
  }

  public function __toString() {
      return $this->name . " (" . $this->species . ")\n";
  }
}

penguin5.php

With this in place, we can literally output the object by calling echo on it, like this:

$tux = new Penguin('tux');
echo $tux;

I don’t use this shortcut often but it’s useful to know that it is there.

More Magic Methods

There is a great reference on the php.net site itself, listing all the available magic methods (yes, there are more than these, I just picked the ones I actually use) so if you want to know what else is available then take the time to check this out.

Hopefully this has been a useful introduction to the main ones, leave a comment to let us know how you use these in your own projects!

According to founder Matt Mullenweg, WordPress now runs an estimated 8.5% of all sites on the internet. This is a staggering amount – almost one in every ten sites is sitting on what was once just ‘blogging software’.

Put another way, there are 20 million eager WordPressers looking forward to the long awaited upgrade from 2.9.2 to WordPress 3.0.

The first release candidate is now available and most of the new features are well-known and have been described in detail. Others, like custom post types, are leaving some users scratching their heads. But what does the new version of WordPress mean for the millions of web designers that use it every day?

A CMS by any Other Name

“Version 3 is absolutely a step forward for designers”, argues Chris Coyier from CSSTricks”

“For one thing, I think it will finally squelch the ‘WordPress is a blogging platform, not a CMS’ argument. With custom post types becoming a core feature, it is straight up CMS territory.”

We’ll come back to custom post types later, but the point that Chris makes about WordPress becoming a true Content Management System (CMS) has lots of support.

Elliot Jay Stocks is a well-known designer who uses WordPress, and he’s also excited about this development towards a true CMS:

“It’s definitely a step forward. It’s moving further and further away from its roots as a blogging engine and incorporating powerful tools that make it a viable CMS.”

Jeff Starr, who co-wrote ‘Digging into WordPress’, believes that:

“WordPress 3 is custom everything, and it’s awesome. These features provide greater control and flexibility in terms of content organisation, presentation, and management. Custom content types take us beyond the days of posts and pages. Custom taxonomies take us beyond tags and categories.”

Adii Pienaar from WooThemes agrees:

“I’m very excited about custom post types as this makes WordPress even more of a fully-fledged CMS”

So let’s take a look at some of these features in more depth, and just how they will affect web professionals designing sites for the WordPress platform.

Custom Post Types – Simpler than it Sounds

Perhaps the feature that causes the most confusion, or at least the most questions, is custom post types. At its heart it’s a relatively simple concept – instead of just posts and pages you can now specify your own type of entry.

Admin screen for a custom post type of “Video”

Chris from CSSTricks explains the concept well:

“Think of how Tumblr works – how you can publish photos, quotes, links and whatever else. You could create those same types now with WordPress, and build themes to support and have special styles for them. This is fantastic stuff for building custom sites!”

Fantastic stuff indeed, and it’s interesting to hear Chris mention Tumblr. WordPress’s nimbler, younger cousin continues to grow at a phenomenal rate and has many fans out there. Indeed, some designers have ditched WordPress altogether for Tumblr.

Others, like Corbus Bester, have designed amazing WordPress sites that look and feel like Tumblogs. Perhaps there is some mileage in this fusion of styles; it’s certainly now possible – and considerably easier – with custom post types.

Chris Spooner from SpoonGraphics also sees the benefit this new feature will bring:

“As someone who uses WordPress for almost every website I build, I’d say it would be really useful to be able to create a new entry for a particular section of a website that’s different to the usual post and page layouts. A new portfolio entry springs to mind as a good use of this feature.”

The Community Gives Back

One of the other highly publicised additions, thanks in no small part to the goodwill and marketing genius of those WooThemes folk, is the new Navigation System.

Admin screen for the new menu system

It is, in short, a master-stoke. It also blurs the line between the open-source platform and its profit-making community. Adii Pienaar explains:

“I’m happy to be a bit biased, but the new menu system that WooThemes contributed is long overdue and a massive benefit to every single WordPress user, In essence, this is such a basic feature of any CMS, but due to it being a benefit to all WordPress users I think this is a significant new addition” he adds.

Chris Coyier believes:

“The menu building tools are going to be huge for designers as well, and unquestioningly a step forward. Building dynamic menus in the past has involved using WordPress functions in the theme code itself with a bunch of parameters. Nerdy stuff, and not for the average site owner or even for many designers.”

WooThemes designer Magnus Jepson agrees:

“The navigation system will let designers concentrate on setting up the menu instead of hard coding it.”

So how does it work? Chris explains:

“The new menu builder puts a GUI on [menu building], putting menu control in the admin where it should be and where anybody can intuitively control it.”

Other Features

Of the myriad other features on offer with version 3.0, the more noteworthy include:

• The long awaited integration of WordPress MU with the core WordPress code, a project that has taken the WordPress team over a year;
• The new default theme TwentyTen, and the promise of a new theme every year;
• New author templates, allowing the easier customisation of pages for individual authors; and
• A new installation system, ditching the known security issue that is the ubiquitous ‘admin’ user.

The new default theme “TwentyTen” home page

WordPress 3 for Designers

So will these new features make a difference for designers? Adii argues:

“Not necessarily for designers, I think the new features are probably more geared to end-users, like the menu system, or developers, for example custom post types.”

He has a point. The level of comfort and experience you have with PHP really does affect how much you can squeeze from the WordPress system; HTML and CSS are simply not enough. Elliot touches on this:

“I hope it becomes easier to work with template files. Less PHP wizardry required and more functionality built in from the start.”

Chris Spooner thinks that others will benefit from the upgrade:

“I see the upgrades more suited to the everyday end user. The extra customisation options will also allow the non-tech user to add their own touch to their blog.”

Others, like Jeff Starr, believe that WordPress 3 will bring benefits to designers as well:

“[It is] definitely a step forward. A huge step. In addition to better content management, its integration of WPMU makes it that much easier to create entire networks of sites with a single installation. WordPress 3 also features bulk updates for plug-ins and themes, saving users even more time.”

And it’s that hacking that keeps WordPress, even version 3.0, out of the reach of anyone without a basic grounding in PHP (and, arguably, jQuery). Elliot argues:

“It still doesn’t look as powerful as Expression Engine, But for ease-of-setup and ease-of-use, WordPress remains my favourite CMS. My only beef with WordPress is that it can take a lot of hacking to get what you want, and I’m hoping that WordPress 3 will solve this problem.”

The future for WordPress

So just what does the future hold for WordPress? Is it too early to speculate what we’ll see in WordPress 4?

“I’d actually vote for it not to develop too much,” said Adii from WooThemes. “WordPress is great because it has never been the most complex or complicated system to use. I am however in favour of adding functionality that will make WordPress a more complete CMS, even if that means having different ‘flavours’ of the platform i.e. blogging vs. CMS.”

Perhaps WordPress.com will remain as the hosted solution for casual bloggers, and a ‘WPLite’ version will also become available.

We then might see an offshoot, the more powerful CMS version, which caters for the needs of its considerable and growing user-base of web designers looking for a back-end system.

It makes sense, and it could see an opportunity for Automattic to further monetise part of its software-as-service stable. But who exactly would profit? And who would pay?

When asked about the future or WordPress, Jeff focuses on usability for designers:

“Make it fast, make it secure, and make it easy on the server. Go for lean and mean, and deprecate the fluff that nobody uses.”

This sentiment is echoed by Magnus:

“I hope that WordPress will develop to be faster and more secure than it is today, and also that it adopts the most widely used functions into the core for all to use. Maybe wishful thinking to have both new functions and faster system, but everything is possible.”

Chris Coyier also offers some thoughts about the future:

“As far as the software itself, I hope it continues to have a big community and have a good, smart, quick core team. There are no particular ‘features’ that I’m pining for anymore, mostly just a wish that the team keeps my WordPress nice and secure as we move forward.”

There’s a nice turn of phrase here from Chris, “My WordPress”. The wonderful thing about WordPress is that it’s us, the users, the designers and the developers that help create its ultimate direction. And it’s our creative and unique implementations of this powerful system that will guide its future development.

Want More on WordPress 3.0?

Over the coming weeks we will be taking a more code based look at some of the new features in WordPress 3.0. Watch out for our first article which will focus on “Custom Posts” in the next few weeks.

This time around we’ll look at some more advanced concepts and some more practical examples of building code, covering use of constructors and how to add access modifiers in to control how calling code can operate on your objects.

We’ll also show off how to create static methods and properties and, perhaps more importantly, illustrate applications of these features.

Constructors

Let’s start at the very beginning, and look at what happens when we create an object. When a class is instantiated and used to create an object, a particular function is run and this is called the constructor. The way this is done changed between PHP version and so can be a bit confusing.

In PHP 4, the constructor was a function with the same name as the class itself – and although PHP 4 is dead and gone (deprecated and no longer supported even for security fixes), that behaviour has been preserved in PHP 5 to preserve backwards compatibility, and you will still see it in code which transitioned between the language versions. Here is an example:

class Penguin {

public function penguin($name) {
$this->name = $name;
$this->type = "penguin";
return true;
}

}

penguin_deprecated.php

So in PHP 5, this would still work, but really we want to use the magic methods introduced in that version, where the constructor is called __construct() and our class would then look like this:

class Penguin {

public function __construct($name) {
$this->name = $name;
$this->type = "penguin";
return true;
}

}

penguin.php

The PHP 5 version makes more sense because the method can then be inherited, rather than having to redeclare a same-named function and call the function which matches the name of the extending class? Confused? Me too :) Always use __construct() is the main message here.

The Static Keyword

So far we’ve looked at fairly classic OO concepts, but to take full advantage of the functionality on offer, there are some more tricks we can learn. One of my favourites (in fact I probably use it too much!) is the static keyword.

The static keyword can be applied to both properties and methods, and we literally mean “static” in this case as to mean “the opposite of dynamic”. When we use static properties and methods, we use the class as it stands, without instantiating it. Sounds a bit strange so let’s take a look at some examples.

Static Properties

A static property is something we can set on an object, either from inside it or from outside, and retrieve it later. It is almost like a constant, something we use for reference, except that it isn’t constant and we can change it at any time.

If you are familiar with using static variables in procedural PHP, then this is a concept that will come easily to you. An example:

class Message {
public static $system_name = 'Default';
}

message.php

This is a very simple class, with a single static property declared. As with all class properties, these can be created and used on the fly since there is no requirement to declare these in PHP.

To access this property, we do not need to instantiate an object of this type. Instead we use the class name followed by the “scope resolution operator” which is two colons, and then the usual dollar sign and variable name we want, like this:

include('message.php');

echo Message::$system_name;

We can modify this variable from outside as shown in the following example, which also illustrates that this property is NOT set on an object instantiated from this class definition:

include('message.php');

Message::$system_name = 'Social Network Messaging';

$msg = new Message();
var_dump($msg->system_name);

echo Message::$system_name;

This script outputs NULL followed by “Social Network Messaging”, as we’d expect.

Static Methods

Static methods follow the same sort of ideas as static properties. They are declared using the static keyword alongside the access modifier (traditionally after it but either order is valid), and they do not require the class to be instantiated.

Static methods are useful for situations where you don’t need any other information to perform the task. For example they are common in the search methods on an object; “findItemByProductId” could be a static method that retrieves some data and then instantiates an object and returns it.

Here’s an example of a simple inflector method; we might want to keep a bunch of these methods together but we don’t need an instantiated object to use them:

class Inflector {
public static function pluralise($word) {
if($word == "sheep") {
$plural = "sheep";
} elseif (substr($word, -1) == 'y') {
$plural = substr($word,0,-1) . 'ies';
} else {
$plural = $word . 's';
}

return $plural;
}
}

inflector.php

When we use this static method we once again use the scope resolution operator:

include('inflector.php');

echo Inflector::pluralise('tree') . "\n";
echo Inflector::pluralise('story') . "\n";
echo Inflector::pluralise('sheep') . "\n";

This script outputs “trees”, “stories” and “sheep” as we’d expect – we don’t need any settings on the objects itself so we never use $this, which is why this makes a good example of using a static class.

Objects, Storage and References

A big change between earlier versions of PHP and PHP 5 is that objects are always passed by reference now, in fact every object is stored simply as a pointer.

This is useful since any changes made to an object passed into a function will persist without us having to pass it back, but it does mean that we can sometimes be tripped up when working with objects and particularly copying them.

Using Clone

So look at this example, what would you expect the output to be?

$a = new stdClass();
$a->name = 'Alice';
$b = $a;
$b->name = 'Beatrice';

echo $a->name;

In fact this example prints “Beatrice”. This is because when we do $b = $a we aren’t copying the values. We’re telling $b that it should point to the same collection of data that $a is pointing to, because objects are just references.

If we want $b to be separate from $a then we will need to make use of the clone keyword, as shown here, only the line where we create $b changes.

$a = new stdClass();
$a->name = 'Alice';
$b = clone($a);
$b->name = 'Beatrice';

echo $a->name;

This time the script outputs “Alice” – our changes to $b don’t affect the values in $a.

As I mentioned before, this change of handling happened between PHP 4 and PHP 5 – and certainly caused some headaches for those that upgraded. However the current behaviour really does work well so it was a good decision in the longer term.

Comparing Objects

Having just said that objects are purely references, we need to bear this in mind when we compare objects – because objects with the same properties set to the same values evaluate differently to two variables pointing to the same object.

For two objects that are of the same types and have all the same property values, we can use the comparison operator “==“. To identify where the same object is being referred to, we can use a strict comparison “===” to evaluate this.

A Question of Class

If you have an object and you want to assess what kind of an object it is, you can do this using the InstanceOf operator. If we go back and use our penguin class from earlier, we can try this out:

include('penguin.php');

$tux = new Penguin("Tux");

if($tux InstanceOf Penguin) {
echo "I'm a penguin\n";
} else {
echo "I don't know what I am\n";
}

Note that since it is an operator, it goes between the object we are assessing and what we want it to be, just like the other operators, such as the less than. Objects will return true to InstanceOf evaluation if they are of that class, implement that class, or extend that class – a very powerful way of identifying if a class will match your needs.

In Conclusion

This article has covered some tools for use of OOP in PHP which I hope will bring you to a point where you feel ready to use this in applications of your own.

A lot of the concepts covered here you might not need every day – but they might catch you out so bookmark this article for reference and refer back any time you need a quick reminder. If you’re using these techniques then do share your tips with other readers in the comments!

Nowadays that very procedural approach is less common in PHP, so this article takes a look at some of the basic object oriented features available in the language and shows some examples of using them with code examples.

Using OOP (Object Orientated Programming) enables us to architect our systems much more clearly, and to make them more manageable and more maintainable. This technique also allows us to separate form from function to create clean, navigable codebases with plenty of opportunities to reuse code, apply design patterns and bring in concepts from other brances of computer science.

Objects vs Classes

While the terms “object” and “class” are often used almost interchangeably in the world of software, there is a definite conceptual difference between the two. A class is the blueprint or recipe; it describes what the object should be, have and do. So a class might look like this:

class Elephpant {
    public $colour;

    public function dance() {
        echo "elephpant dances!\n";
        return true;
    }
}

elephpant.php

An object, on the other hand, is an actual instantiation of the class – its an actual thing, with values and behaviours. In the example below, $ele is the object:

include('elephpant.php');

$ele = new Elephpant();

We can inspect $ele to make sure that it is, in fact, an object of the class Elephpant, using the print_r command. Adding this to our code sample as shown, we see the output below:

include('elephpant.php');

$ele = new Elephpant();
print_r($ele);

Elephpant Object
(
    [colour] =>
)

This output shows an object, of type Elephpant, and with a single empty property named “colour”. For more information about the objects exact properties and their values, you can also use var_dump, which gives a more detailed output showing in detail the datatypes of each property. This is particularly useful for spotting empty strings, nulls and false.

Using Objects, Their Properties and Methods

Our class, Elephpant, has a property and a method (OO-speak for “function”) already defined inside it, so how can we interact with these? Let’s start by setting the colour property; we use the object operator which is a hyphen followed by a greater than sign.

include('elephpant.php');

$ele = new Elephpant();

// set the colour property
$ele->colour = "blue";

// now use that property
echo "The elephpant is " . $ele->colour;

The output of this script reads “The elephpant is blue”. The property will remain set on the object until the object is destroyed, or the property overwritten or unset. Objects are a great way of keeping things together that belong together, for example information about an elephpant!

Similarly we can call the method using the same operator – the brackets after the call let PHP know its a method rather than a property, and if we had parameters to pass in they’d go between the brackets. Something like this:

include('elephpant.php');

$ele = new Elephpant();

// call the dance method
$ele->dance();

Look back at the class declaration for Elephpant and you’ll see the dance method actually echoes from within it. Indeed when we run the code example here, we see “elephpant dances!” as our output. It is a very trivial example but I hope it does show how to call methods against our objects. An alternative approach (and probably a better one within an actual application) would be to create the string and use it as the return value for the function. Then the calling code can take the string and echo it, or do whatever else it needs to, in a more flexible way.

Inheritance

Now we know how to create and interact with objects, let’s step things up a bit and look at how we can create objects which are similar in some ways and different in others, using inheritance. If you are accustomed to OOP from any other programming languages then this will seem very familiar to you, so here is a quick look at how this can be done in PHP. We already have our Elephpant class declared, so let’s add a Penguin class as well. They will both inherit from the parent class Animal, which looks like this:

class Animal{

    public $type = "animal";

    public function dance() {
        echo $this->type . " dances!\n";
        return true;
    }
}

animal.php

The animal has a “type” property, and a dance() method. It uses the type property in the dance() method to create the output, using $this to refer to the current object. In PHP, $this is a special keyword which refers to the current object from within its own class.

Now we can create a Penguin class that inherits from this general Animal class, by using the extends keyword to denote its parent:

class Penguin extends Animal {
    public $type = "penguin";
}

penguin.php

The penguin class would inherit the type property set to “animal” if we didn’t override it by setting the property again in this class. However even without declaring a dance() method, the penguin can dance!

include('animal.php');
include('penguin.php');

$tux = new Penguin();

// make tux dance
$tux->dance();

The above example gives the output “penguin dances!” – using the dance() method from the Animal class, which is available because the Penguin class extends it, and the type property set separately in the Penguin class itself.

Access Modifiers

Take a look at the previous example. The type is set in the class, but we could easily set it from our main code if we wanted to. Imagine if we put $tux->type = “giraffe” before we asked him to dance! Sometimes this is the desired behaviour, and sometimes it isn’t. To allow us to control whether properties can be changed outside a class, PHP gives us access modifiers. An example of these are the “public” keywords you see in the classes shown above. To prevent the type property being edited from outside the class, we can declare the Penguin type to be private, so the class now looks like this:

class Penguin extends Animal {
    private $type = "penguin";
}

private_penguin.php

The following code listing shows us trying to set the now-private type property, and is followed by the resulting output.

include('animal.php');
include('private_penguin.php');

$tux = new Penguin();

// change the type
$tux->type = "linux penguin";
// make tux dance
$tux->dance();

Fatal error: Access level to Penguin::$type must be public (as in class Animal) in /home/lorna/.../OOP/private_penguin.php on line 5

The resulting message feeds back to the user that the type property can’t be modified, and even includes the detail that the property was public in the parent class. Access modifiers are pretty powerful, we should look at them in more detail.

Access modifiers can be applied to properties and to methods and to properties. The options are public, private and protected. In PHP4, these weren’t available and everything is public. As a result, and to maintain backwards compatibility, if an access modifier isn’t specified then the property or method defaults to being public. This isn’t recommended practice however, and it is best to be explicit about which is intended.

Public: The public access modifier means that properties and methods can be accessed from anywhere, within the scope of the object itself, and also from outside code operating on an object.

Private: The method or property is only available from within the scope of this specific class. Before using this option, read on to find out about the “protected” access modifier.

Protected: The method or property is available from within this class, and from within any classes with extend or implement this class. This is ideal where you don’t want external code to change the class, but you do want to be able to extend the class later and take advantage of this property or method. Protected is more flexible than private and almost always the better choice.

Using these access modifiers we can control where our class methods and properties can be accessed from. We looked at an example of properties and this works in the same way for method calls – they cannot be accessed from outside of the class definition unless they are declared to be public. It can be very useful indeed to declare methods as protected, where they are internal helper methods used by other class methods but not intended to be accessed directly. In PHP4 there was no support for this and so the internal methods were sometimes named with an underscore to hint that this was their intended use – it is still possible to see this naming convention in use today, although it is not needed.

Using OOP in PHP: Practical Example

Object Oriented design is particularly useful where you have data objects that relate to one another – so it is very common for example to have OOP used to deal with data. PHP 5 has the PDO (PHP Data Object) classes which are a great way to talk to a backend database, either mysql or any other kind of database, and using the object oriented interface offered by this extension ties in well with the usage I have shown here.

A common mistake for those coming to OO for the first time is to declare methods inside a class but then instantiate a single copy of that and pass in data such as the ID of the data to each method. Here’s an example of a user class that does this:

class User {
    /**
     * getDisplayName
     *
     * @param int $user_id the user_id of the user in the database table
     * @access public
     * @return string Display name of this user
     */
    public function getDisplayName($user_id) {
        $sql = 'select display_name from users where user_id = '.$user_id;
        $results = mysql_query($sql);
        $row = mysql_fetch_array($results);
        return $row['display_name'];
    }

    /**
     * getFriends
     *
     * @param int $user_id the user_id of the user in the database table
     * @access public
     * @return array An array of friend_ids
     */
    public function getFriends($user_id) {
        $sql = 'select friend_id from user_friends where user_id = '.$user_id;
        $results = mysql_query($sql);
        $friends = array();
        while($row = mysql_fetch_array($results)) {
            $friends[] = $row['friend_id'];
        }
        return $friends;
    }
}

user.php

And some code that uses it:

include('user.php');
mysql_connect('localhost','root','');
mysql_select_db('test');

$user = new User();
echo "User known as: " . $user->getDisplayName(1) . "\n";

$friends = $user->getFriends(1);
echo "Friends with: " . implode(', ',$friends) . "\n";

If you want to run this code yourself, then you can set up the database tables using this script:

CREATE TABLE `user_friends` (
  `user_friend_id` int(11) NOT NULL AUTO_INCREMENT,
  `user_id` int(11) NOT NULL,
  `friend_id` int(11) NOT NULL,
  PRIMARY KEY (`user_friend_id`)
)
INSERT INTO `user_friends` VALUES (1,1,3),(2,1,5);

CREATE TABLE `users` (
  `user_id` int(11) NOT NULL AUTO_INCREMENT,
  `first_name` varchar(20) DEFAULT NULL,
  `last_name` varchar(50) DEFAULT NULL,
  `display_name` varchar(50) DEFAULT NULL,
  PRIMARY KEY (`user_id`)
)
INSERT INTO `users` VALUES (1,'Lorna','Mitchell','lornajane');

user.sql

This is more like a function library than an actual object, and although it works perfectly well and does have its applications, it can be better to aim to take advantage of more object oriented features. To do this, a new object should be created for each item the system handles, and if it has an ID and perhaps some other properties, these should be set as part of the object. Then rather than creating a single user object and doing getFriends(42) on it, you’d have a user with ID 42 which did $user->getFriends().

Here’s a follow up example with a class and how to use it, this will give better performance and enable you to clearly see which data goes with which object where there are multiple items on a page:

class User {
    /**
     * getUserById
     *
     * @param int $user_id the id of the user row in the table
     * @access public
     * @return true if the user was found
     */
    public function getUserById($user_id) {
        $sql = 'select first_name, last_name, display_name from users where user_id = ' . $user_id;
        $results = mysql_query($sql);
        $row = mysql_fetch_array($results);
        $this->user_id = $user_id;
        $this->first_name = $row['first_name'];
        $this->last_name = $row['last_name'];
        $this->display_name = $row['display_name'];

        // in real life, there would be escaping and error handling and we'd only return true if we got data
        return true;
    }

    /**
     * getDisplayName
     *
     * @access public
     * @return string Display name of this user
     */
    public function getDisplayName() {
        return $this->display_name;
    }

    /**
     * getFriends
     *
     * @access public
     * @return array An array of friend_ids
     */
    public function getFriends() {
        $sql = 'select friend_id from user_friends where user_id = '.$this->user_id;
        $results = mysql_query($sql);
        $friends = array();
        while($row = mysql_fetch_array($results)) {
            $friends[] = $row['friend_id'];
        }
        return $friends;
    }
}

user2.php

include('user2.php');
mysql_connect('localhost','root','');
mysql_select_db('test');

$user = new User();
// populate the object
$user->getUserById(1);
echo "User known as: " . $user->getDisplayName() . "\n";

$friends = $user->getFriends();
echo "Friends with: " . implode(', ',$friends) . "\n";

In Summary

This has been a very introductory look at some of the object oriented features available in PHP, to get you started out with the basics of working with OO code and also writing your own. If this has helped you take your first OOP steps, then let us know by leaving a comment and let us know what you built! In the next post there will be some more in-depth content including using constructors, access modifiers and working with the static keyword in PHP – taking your skills to the next level.

This article breaks down the fundamentals of debugging in PHP, helps you understand PHP’s error messages and introduces you to some useful tools to help make the process a little less painful.

Editor’s Note: We’ll be running workshops like “How to Build a Web App from A-Z” at The Future of Web Apps London.

Doing your Ground Work

It is important that you configure PHP correctly and write your code in such a way that it produces meaningful errors at the right time. For example, it is generally good practice to turn on a verbose level of error reporting on your development platform. This probably isn’t such a great idea, however, on your production server(s). In a live environment you neither want to confuse a genuine user or give malicious users too much information about the inner-workings of your site.

So, with that in mind lets talk about the all too common “I’m getting no error message” issue. This is normally caused by a syntax error on a platform where the developer has not done their ground work properly. First, you should turn display_errors on. This can be done either in your php.ini file or at the head of your code like this:

<?php
ini_set('display_errors', 'On');

Tip: In these code examples I omit the closing (?>) PHP tag. It is generally considered good practice to do so in files which contain only PHP code in order to avoid accidental injection of white space and the all too common “headers already sent” error.

Next, you will need to set an error reporting level. As default PHP 4 and 5 do not show PHP notices which can be important in debugging your code (more on that shortly). Notices are generated by PHP whether they are displayed or not, so deploying code with twenty notices being generated has an impact upon the overhead of your site. So, to ensure notices are displayed, set your error reporting level either in your php.ini or amend your runtime code to look like this:

<?php
ini_set('display_errors', 'On');
error_reporting(E_ALL);

Tip: E_ALL is a constant so don’t make the mistake of enclosing it in quotation marks.

With PHP 5 it’s also a good idea to turn on the E_STRICT level of error reporting. E_STRICT is useful for ensuring you’re coding using the best possible standards. For example E_STRICT helps by warning you that you’re using a deprecated function. Here’s how to enable it at runtime:

<?php
ini_set('display_errors', 'On');
error_reporting(E_ALL | E_STRICT);

It is also worth mentioning that on your development platform it is often a good idea to make these changes in your php.ini file rather than at the runtime. This is because if you experience a syntax error with these options set in your code and not in the php.ini you may, depending on your set up, be presented with a blank page. Likewise, it is worth noting that if you’re setting these values in your code, a conditional statement might be a good idea to avoid these settings accidentally being deployed to a live environment.

What Type of Error am I Looking at?

As with most languages, PHP’s errors may appear somewhat esoteric, but there are in fact only four key types of error that you need to remember:

1. Syntax Errors

Syntactical errors or parse errors are generally caused by a typo in your code. For example a missing semicolon, quotation mark, brace or parentheses. When you encounter a syntax error you will receive an error similar to this:

Parse error: syntax error, unexpected T_ECHO in /Document/Root/example.php on line 6

In this instance it is important that you check the line above the line quoted in the error (in this case line 5) because while PHP has encountered something unexpected on line 6, it is common that it is a typo on the line above causing the error. Here’s an example:

<?php
ini_set('display_errors', 'On');
error_reporting(E_ALL);


$sSiteName = "Think Vitamin"
echo $sSiteName;

In this example I have omitted the semi-colon from line 5, however, PHP has reported an error occurred on line 6. Looking one line above you can spot and rectify the problem.

Tip: In this example I am using Hungarian Notation. Adopting this coding standard can aid with debugging code while working collaboratively or on a piece of code you wrote some time ago. The leading letter denoting the variable type means that determining a variable type is very quick and simple. This can aid in spotting irregularities which can also help highlight any potential logic errors.

2. Warnings

Warnings aren’t deal breakers like syntax errors. PHP can cope with a warning, however, it knows that you probably made a mistake somewhere and is notifying you about it. Warnings often appear for the following reasons:

1. Headers already sent. Try checking for white space at the head of your code or in files you’re including.
2. You’re passing an incorrect number of parameters to a function.
3. Incorrect path names when including files.

3. Notices

Notices aren’t going to halt the execution of your code either, but they can be very important in tracking down a pesky bug. Often you’ll find that code that’s working perfectly happily in a production environment starts throwing out notices when you set error_reporting to E_ALL.

A common notice you’ll encounter during development is:

>Notice: Undefined index: FullName in /Document/Root/views/userdetails.phtml on line 55

This information can be extremely useful in debugging your application. Say you’ve done a simple database query and pulled a row of user data from a table. For presentation in your view you’ve assigned the details to an array called $aUserDetails. However, when you echo $aUserDetails['FirstName'] on line 55 there’s no output and PHP throws the notice above. In this instance the notice you receive can really help.

PHP has helpfully told us that the FirstName key is undefined so we know that this isn’t a case of the database record being NULL. However, perhaps we should check our SQL statement to ensure we’ve actually retrieved the user’s first name from the database. In this case the notice has helped us rule out a potential issue which has in turn steered us towards the likely source of our problem. Without the notice our likely first stop would have been the database record, followed by tracing back through our logic to eventually find our omission in the SQL.

4. Fatal Errors

Fatal Errors sound the most painful of the four but are in fact often the easiest to resolve. What it means, in short, is that PHP understands what you’ve asked it to do but can’t carry out the request. Your syntax is correct, you’re speaking its language but PHP doesn’t have what it needs to comply. The most common fatal error is an undefined class or function and the error generated normally points straight to the root of the problem:

Fatal error: Call to undefined function create() in /Document/Root/example.php on line 23

Using var_dump() to Aid Your Debugging

var_dump() is a native PHP function which displays structured, humanly readable, information about one (or more) expressions. This is particularly useful when dealing with arrays and objects as var_dump() displays their structure recursively giving you the best possible picture of what’s going on. Here’s an example of how to use var_dump() in context:

Below I have created an array of scores achieved by users but one value in my array is subtly distinct from the others, var_dump() can help us discover that distinction.

<?php
ini_set('display_errors', 'On');
error_reporting(E_ALL);


$aUserScores = array('Ben' => 7,'Linda' => 4,'Tony' => 5,'Alice' => '9');
echo '<pre>';
var_dump($aUserScores);
echo '</pre>';

Tip: Wrap var_dump() in <pre> tags to aid readability.

The output from var_dump() will look like this:

array(4) {
  ["Ben"]=>
  int(7)
  ["Linda"]=>
  int(4)
  ["Tony"]=>
  int(5)
  ["Alice"]=>
  string(1) "9"
}

As you can see var_dump tells us that $aUserScores is an array with four key/value pairs. Ben, Linda, and Tony all have their values (or scores) stored as integers. However, Alice is showing up as a string of one character in length.

If we return to my code, we can see that I have mistakenly wrapped Alice’s score of 9 in quotation marks causing PHP to interpret it as a string. Now, this mistake won’t have a massively adverse effect, however, it does demonstrate the power of var_dump() in helping us get better visibility of our arrays and objects.

While this is a very basic example of how var_dump() functions it can similarly be used to inspect large multi-dimensional arrays or objects. It is particularly useful in discovering if you have the correct data returned from a database query or when exploring a JSON response from say, Twitter:

<?php
ini_set('display_errors', 'On');
error_reporting(E_ALL);


$sJsonUrl = 'http://search.twitter.com/trends.json';


$sJson = file_get_contents($sJsonUrl,0,NULL,NULL);
$oTrends = json_decode($sJson);


echo '<pre>';
var_dump($oTrends);
echo '</pre>';

Useful Tools to Consider when Debugging

Finally, I want to point out a couple of useful tools that I’ve used to help me in the debugging process. I won’t go into detail about installing and configuring these extensions and add-ons, but I wanted to mention them because they can really make our lives easier.

Xdebug

Xdebug is a PHP extension that aims to lend a helping hand in the process of debugging your applications. Xdebug offers features like:

• Automatic stack trace upon error
• Function call logging
• Display features such as enhanced var_dump() output and code coverage information.

Xdebug is highly configurable, and adaptable to a variety of situations. For example, stack traces (which are extremely useful for monitoring what your application is doing and when) can be configured to four different levels of detail. This means that you can adjust the sensitivity of Xdebug’s output helping you to get granular information about your app’s activity.

Stack traces show you where errors occur, allow you to trace function calls and detail the originating line numbers of these events. All of which is fantastic information for debugging your code.

Tip: As default Xdebug limits var_dump() output to three levels of recursion. You may want to change this in your xdebug.ini file by setting the xdebug.var_display_max_depth to equal a number that makes sense for your needs.

Check out Xdebug’s installation guide to get started.

FirePHP

For all you FireBug fans out there, FirePHP is a really useful little PHP library and Firefox add-on that can really help with AJAX development.

Essentially FirePHP enables you to log debug information to the Firebug console using a simple method call like so:

<?php
$sSql = 'SELECT * FROM tbl';
FB::log('SQL query: ' . $sSql);

In an instance where I’m making an AJAX search request, for example, it might be useful to pass back the SQL string my code is constructing in order that I can ensure my code is behaving correctly. All data logged to the Firebug console is sent via response headers and therefore doesn’t effect the page being rendered by the browser.

Warning: As with all debug information, this kind of data shouldn’t be for public consumption. The downside of having to add the FirePHP method calls into your PHP is that before you go live you will either have to strip all these calls out or set up an environment based conditional statement which establishes whether or not to include the debug code.

You can install the Firefox add-on at FirePHP’s website and also grab the PHP libs there too. Oh, and don’t forget if you haven’t already installed FireBug, you’ll need that too.

In Conclusion …

Hopefully during the course of this article you have learned how to do your ground work by preparing PHP for the debugging process; recognise and deal with the four key PHP error types and use var_dump() to your advantage. Likewise, I hope that you will find Xdebug and FirePHP useful and that they will make your life easier during your development cycle.

As I’ve already mentioned, and I really can’t say this enough, always remember to remove or suppress your debug output when you put your sites into production after all there’s nothing worse than all your users being able to read about your errors in excruciating detail.

Got a great debugging tip to share? Do you use a great little PHP extension that makes your bug trapping life easier? Please tell us about them in comments below!

In the first part of this series we went over how a cookie works and what can be done to secure them. In this section we’re going to go over ways to add additional security to the session beyond the cookie itself.

By the end of this article we will written our own wrapper class for “session_start” that protects our session from a number of attacks while taking into account some of the unique challenges presented by modern ajax-heavy websites.

Session Specific Attacks

Through the use of sessions your identity is maintained as you use a website, and just as in real life identity theft is a concern. By taking over your session an attacker would essentially become you on a website, with access to all of the actions, information and privileges that entails.

The main thing that an attacker needs to steal a session is the session ID. There are three ways an attacker normally goings about doing this, all of which can be protected against but are, by default, completely open.

• Guess the ID: most session handlers generate ids that make this impractical.
• Steal the ID: by using malware, sniffing the network, or exploiting javascript exploits attackers can get the value from the cookie itself.
• Set the ID: rather than steal or guess the ID an attacker may try and set it to a value they choose.

Starting the Session

The default session setup is not at all secure by itself, so we’re going to create a wrapper to add the security we need. To make this code more portable we’re going to build it as a static function of a php class called SessionManager.

To begin our sessionStart function is going to set the name cookie options for the session. Like all cookies we’re going to need to make some decisions about what is going to need access to the session ID. Since these options depend on the application itself lets add arguments we can change based on our specific needs.

For security we can hardcode the “HttpOnly” argument, as session ids are often the juiciest target for cross site scripting attacks.

class SessionManager
{
   static function sessionStart($name, $limit = 0, $path = '/', $domain = null, $secure = null)
   {
      // Set the cookie name before we start.
      session_name($name . '_Session');

      // Set the domain to default to the current domain.
      $domain = isset($domain) ? $domain : isset($_SERVER['SERVER_NAME']);

      // Set the default secure value to whether the site is being accessed with SSL
      $https = isset($secure) ? $secure : isset($_SERVER['HTTPS']);

      // Set the cookie settings and start the session
      session_set_cookie_params($limit, $path, $domain, $secure, true);
      session_start();
   }
}

Using the new class is as easy as including it and running one line but additional options can make it more restrictive.

SessionManage::sessionStart('InstallationName');
SessionManage::sessionStart('Blog_myBlog', 0, '/myBlog/', 'www.site.com');
SessionManage::sessionStart('Accounts_Bank', 0, '/', 'accounts.bank.com', true);

Lock the Session to a Host

Now that our wrapper class is in place and functional we can start building in additional security by restricting the session to the same IP address and User Agent (or browser) as when the session was first opened. This way if the session ID is stolen or guessed the attacker still has to get ahold of the user agent (admittedly not too difficult if they got the session ID) and somehow find a way to get the same IP address.

These attacks only help if the user is not on the same network. The user agent check only adds minor security, since many attacks that compromise the cookie are going to do the same to the user agent. If an attacker is on the same network as the target there is a good chance they already have the same external IP address, as it is pretty common for a network to use private internal addresses while presenting only a single IP address to the internet. This is why it is important to evaluate the need for SSL.

We’re going to add these new checks to our class in the function preventHijacking. This function will return false on new sessions or when a session is loaded by a host with a different IP address or browser. preventHijacking will true if the session is valid and false otherwise. This means it will return false not just on malicious attempts but completely new sessions as well.

static protected function preventHijacking()
{
	if(!isset($_SESSION['IPaddress']) || !isset($_SESSION['userAgent']))
		return false;

	if ($_SESSION['IPaddress'] != $_SERVER['REMOTE_ADDR'])
		return false;

	if( $_SESSION['userAgent'] != $_SERVER['HTTP_USER_AGENT'])
		return false;

	return true;
}

Now that we have a way to identify hijacking attempts we need to set up a way to respond to them. For us this means two things- clearing out the old session data and inserting the IP address and user agent into the new session.

static function sessionStart($name, $limit = 0, $path = '/', $domain = null, $secure = null)
{
	...
	session_start();

	if(!self::preventHijacking())
	{
		$_SESSION = array();
		$_SESSION['IPaddress'] = $_SERVER['REMOTE_ADDR'];
		$_SESSION['userAgent'] = $_SERVER['HTTP_USER_AGENT'];
	}
}

Session Fixation

So far we have effectively eliminated the possibility of brute force guessing. We’ve also made it so any attempts at capturing the session ID would require the attacker to be on the same network as the user in order to take advantage of that ID, while also discussing enforcing SSL to make capturing the session more difficult through traditional means. However, what if the attacker could set the session ID themselves?

By getting the user to follow a link with a session ID in it the attacker can trick the user into starting a session with the ID of the attacker’s choosing. Rather than guess or steal an ID the attacker will have it right from the start. Many web environments, including PHP, allow session ids to be set through the URL, primarily to get around systems which do not support cookies. Just like with regular cookies the value sent by the client is the value used for the ID, so in this case the value in the URL becomes the session ID.

The solution to this is to change the session ID. How often you do this is tends to be a matter of great debate, but at the bare minimum the ID should be changed when new sessions are created and when the user changes privileges (logs in or out).

A First Attempt At Regenerating the ID

Regenerating the ID is fairly simply in php. Deceptively simple one might say. The function “session_regenerate_id” lets us tell the system to use a new ID. It can also optionally delete the old session.

// Leaves old session intact
session_regenerate_id();

// Deletes old session
session_regenerate_id(true);

If you don’t delete the old session then it is still vulnerable to hijacking and whatever access it had can be granted to an attacker. If you’re changing the session ID often without deleting the old ones you could be creating more holes by leaving a trail of old, but valid, sessions.

Regenerating the ID in the World of Ajax

If an application creates a lot of quick connections to the server some interesting things can happen. PHP, and many other languages, restricts access to the session data to one running script at a time, so if multiple requests come in that try to access the session data the second request (and any other) gets queued up. When the first request changes the ID and deletes the old session the second request still has the old session ID which no longer exists. This results in a third, new session being opened and generally means your user gets logged out.

This bug is ridiculously hard to diagnose as the timing of not just the requests but the ID regeneration has to be just right. In sites that don’t make requests to the server using javascript this type of bug may never be encountered at all, as the time between page loads is more than long enough for the browser to have updated its session info. For sites that make use of ajax techniques, however, this issue will have a chance of occurring whenever the session ID is changed.

In our final update to the SessionManager class we’re going to write a fix for this problem. Rather than delete the session immediately when we change the ID, we’re going to mark the old session as obsolete and mark it to expire in ten seconds. This way any queued up requests will still have access to the expired session but we don’t have to leave it open forever.

To accomplish this we’re going to add the regenerateSession function. This function adds the obsolete flag and expiration to the session, regenerates the ID to create the new session and saves them both. It then reopens the new session and removes the obsolete flag. Unlike our other internal functions we are leaving this one open for use outside the class so that it can be tied into login scripts.

static function regenerateSession()
{
	// If this session is obsolete it means there already is a new id
	if(isset($_SESSION['OBSOLETE']) || $_SESSION['OBSOLETE'] == true)
		return;

	// Set current session to expire in 10 seconds
	$_SESSION['OBSOLETE'] = true;
	$_SESSION['EXPIRES'] = time() + 10;

	// Create new session without destroying the old one
	session_regenerate_id(false);

	// Grab current session ID and close both sessions to allow other scripts to use them
	$newSession = session_id();
	session_write_close();

	// Set session ID to the new one, and start it back up again
	session_id($newSession);
	session_start();

	// Now we unset the obsolete and expiration values for the session we want to keep
	unset($_SESSION['OBSOLETE']);
	unset($_SESSION['EXPIRES']);
}

We need to add another function to check for the obsolete flag and to see if the session has expired.

static protected function validateSession()
{
	if( isset($_SESSION['OBSOLETE']) && !isset($_SESSION['EXPIRES']) )
		return false;

	if(isset($_SESSION['EXPIRES']) && $_SESSION['EXPIRES'] < time())
		return false;

	return true;
}

Finally, in the last change to our SessionManager, we need to update our SessionStart function. It needs to call the regenerateSession function on new requests and periodically after that, as well as destroy the session if it is invalid. Here is the complete SessionStart function.

static function sessionStart($name, $limit = 0, $path = '/', $domain = null, $secure = null)
{
	// Set the cookie name
	session_name($name . '_Session');

	// Set SSL level
	$https = isset($secure) ? $secure : isset($_SERVER['HTTPS']);

	// Set session cookie options
	session_set_cookie_params($limit, $path, $domain, $https, true);
	session_start();

	// Make sure the session hasn't expired, and destroy it if it has
	if(self::validateSession())
	{
		// Check to see if the session is new or a hijacking attempt
		if(!self::preventHijacking())
		{
			// Reset session data and regenerate id
			$_SESSION = array();
			$_SESSION['IPaddress'] = $_SERVER['REMOTE_ADDR'];
			$_SESSION['userAgent'] = $_SERVER['HTTP_USER_AGENT'];
			self::regenerateSession();

		// Give a 5% chance of the session id changing on any request
		}elseif(rand(1, 100) <= 5){
			self::regenerateSession();
		}
	}else{
		$_SESSION = array();
		session_destroy();
		session_start();
	}
}

Summery

At times it amazes me how complex something as simple as an ID- what is essentially just a string of random characters- can turn out to be. While you can certainly use this class for all of your own projects here is what you need to remember when building your own session manager.

Session IDs are attacked by guessing, capturing or setting the id. You can protect against this in your own applications by …

• Securing the cookie to make stealing the ID harder
• Limiting the session to a specific host to make attacks more difficult
• Changing the ID when escalating privileges and throughout the session life.

Here is the complete Session.class.php file for your reference.

I am sure we have all been in the situation where we’ve learned a new piece of software and only a couple of weeks later we’ve forgotten all but the basic commands. This happened to me recently when moving back to SVN after working with Git. Thankfully I have a handful of “cheat sheets” that I call upon at these times.

Here are a list of cheat sheets I find useful:

Server Side Development

• PHP
• Ruby on Rails
• Django
• MySQL
• Regular Expressions
• Apache
• Mod Rewrite

Version Control

• SVN (Subversion)
• Git

Front End Development

• Microformats
• jQuery
• HTML Character Entities

Command Line

• Unix/Linix Command Line
• Windows Command Line

Blogging Tools

• Expression Engine

GMail

• GMail Shortcuts

There’s a comprehensive list available on cheat-sheets.org and Dave Child deserves a lot of credit for his own selection, many of which are linked above.

If you know of any more please link them up in the comments.

Whilst getting my head around how to create the plugin I started to delve into some of the core WordPress files and came across an unfamiliar yet syntactically sweet PHP control structure. It’s a simple if statement used in a file that combines PHP and HTML.

Old version:

<?php if(<your evaluation here>) { ?>
// Output
<?php } else { ?>
// Output
<?php }; ?>

New version: Much easier to read

<?php if(<your evaluation here>): ?>
// Output
<?php else: ?>
// Output
<?php endif; ?>

It also works on “for” and “while” loops as well as “elseif”.

I have never been a fan of combining HTML and PHP, preferring the separation of code and HTML offered by template engines like Smarty, but I could be persuaded. To me this is syntactically much clearer and in my opinion wouldn’t be too difficult for non “coders” working on your project to grasp.

Here are two further examples from WordPress:

<?php if (have_posts()) : while (have_posts()) : the_post(); ?>

<?php if (have_posts()) : while (have_posts()) : the_post(); ?>
// Output
<?php endwhile; else: ?>
// Output
<?php endif; ?>

There are always new things to learn and learning from other people’s code is a great place to start.

Silverlight is a powerful tool for creating Internet applications that go considerably beyond the capabilities of standard HTML and CSS. It supports a wide range of visual effects and has more than 30 user interface controls built-in, including not only buttons, list boxes and sliders but also a data grid and a calendar. It can display PNG and JPEG image files, and play back WMV, WMA and MP3 media with support for 720p HDTV display modes. Silverlight 1.0 was released in April 2007. The current version is Silverlight 2.0 (originally referred to as Silverlight 1.1) which is fully compatible with the original while offering many enhancements.

Inside a Silverlight application
You define the application that you want Silverlight to present using XAML (eXtensible Application Markup Language). This is based on the XML specification and was designed by Microsoft for initialising structured values and objects. The following XAML document declares a Canvas object containing a TextBlock, which is a lightweight element for displaying text:

Download complete code example

The visual elements that make up a Silverlight application need to be placed within a container object, and this provides a reference in which they can be positioned. In our example we are using a Canvas object measuring 300 by 100 pixels as the container and we have set its Background property so that it displays in a light blue color. Into this we have placed a single TextBlock object which will display the traditional ‘Hello World!’ text string in a Verdana font 30 pixels in size and 10 pixels below and to the right of the top-left corner of the Canvas object. Note the dot syntax that we have employed to reference properties of the Canvas object.

Actually displaying a Silverlight application within an HTML page need involve little more than a standard Object tag. At its simplest, the following renders our example within a browser:

Download complete code example

Here we have defined a space 300 pixels wide and 100 pixels wide in which to place the Silverlight plug-in, as defined by its MIME type. We have also defined a data attribute for the plug-in. In practice this is usually ignored but it can boost performance with some browsers (and note that the trailing comma is necessary as the attribute takes two parameters, the second having a ‘null’ value in this case). Finally, in the event that the client does not have Silverlight 2.0 installed, the anchor element displays a ‘Get Silverlight’ image from the Microsoft Web site which is linked to the page from which the user can download and install the plug-in.

The Silverlight plug-in takes a number of parameters but in this context the most important is ‘source’ which tells the plug-in where to find the application. In this case we are directing it to the file ‘silverlightapp.xml’. If this was to contain the XAML of our earlier example in simple text form, and both these files were uploaded to a directory on your Web server, then opening the HTML page would result in our ‘Hello World!’ application appearing to the top-left of your browser.

The XAML that defines the Silverlight application need not reside in a separate file. It can instead be defined within the page that instantiates the plug-in using a special script block. For example, we could insert the following immediately before the ‘pluginHost’ div block in our HTML page above, which also shows off some of the special effects supported by Silverlight:

Download complete code example

We reference this XAML block by changing the ‘source’ parameter for the Silverlight1 object as follows:

Download complete code example

The hash character indicates that what follows references a script block on the current page. The other principle difference between this and our earlier XAML example is that we have placed a Rectangle object on the Canvas. This is a Shape element, as is the Line, Ellipse, Polygon and Polyline, and as such supports a wider range of display options. The RadiusX and RadiusY attributes round the corners of the Rectangle, while the Fill property allows us to specify a Brush object. In this case we have used the LinearGradientBrush to shade the Rectangle in a graduated blend of yellow and light blue.

Most of the other parameters supported by the Silverlight plug-in can be ignored at this stage. However ‘minRuntimeVersion’ can be useful if you want to ensure, for example, that version 2.0 is installed rather than version 1.0. This can be accompanied by ‘autoUpgrade’ which means that an attempt should be made to upgrade automatically in the event of too early a version being found. There is also the ‘OnLoad’ parameter which can specify a JavaScript function that should be run once the plug-in is loaded (more on that later).

If you want to know more about the options available when instantiating Silverlight, then the article ‘Instantiating a Silverlight Plug-in’ from Microsoft’s MSDN Library is a good place to start.

Using PHP with Silverlight
For the PHP developer, the important point is that the source for the Silverlight object can be anything that returns XAML, and that includes a PHP script. This opens up many possibilities. For example, the following PHP page uses Silverlight to display data extracted from a MySQL database:

Download complete code example

Assuming this is part of the page ‘customers.php’ on our PHP server, then calling it with the following URL would cause Silverlight to display the name, city and postcode of the 134th customer in the database:

http://myserver.com/customers.php?ID=134

Having extracted the ID value from the query string, the code opens a connection to the database and then runs a query which gets the data for the customer specified and places it in the object $result. The function mysqli_fetch_array() extracts the data from $result into the array $row, from where it can be read and inserted into the XAML using the echo command.
This is far from production code, with little in the way of error checking, but it does serve to demonstrate how PHP can be used to generate a Silverlight application. For the sake of simplicity our example embeds the XAML within the page that instantiates the Silverlight control, but you could equally specify a PHP page as the source for the Silverlight control itself, as in the following snippet:

Download complete code example

All that is required here is that the page clients.php return valid XAML code that can be rendered by Silverlight.

Adding user interaction with JavaScript
The Silverlight plug-in exposes a JavaScript API that allows any XAML element can be manipulated by JavaScript, in much the same way that you would program against the HTML Document Object Model (DOM) exposed by the page. Furthermore, Silverlight boasts a wide range of programmable events which opens up many possibilities for user interaction.

For example, in the following we have added an ‘x:Name’ attribute to the TextBlock element. This allows JavaScript to access and manipulate the element using the findName function. We have also attached an event handler stating that the JavaScript function changeText should be executed if the user depresses the left mouse button while the pointer is over the Canvas element:

Download complete code example

We can now define the changeText function by adding the following to the page that instantiates the Silverlight object:

Download complete code example

This script locates the element we want to manipulate using the findName function, and then sets its Text attribute to change from ‘Hello World!’ to ‘Goodbye!’ when the Canvas is clicked. One important point to note here is that the JavaScript is interpreted by the browser and not by the Silverlight plug-in. The x:Name attribute provides a handle that allows the findName function to reach into Silverlight for objects declared within the XAML code.

You can use these techniques to respond to a wide range of events. The API allows you to respond to simple movements of the mouse, or when the mouse pointer enters or leaves an object. You can respond to the depression of the left mouse button, and when it is released. Most objects respond to key up and key down events as well, and there are facilities for determining the key combination. The TextBox control supports a TextChanged event, while the PasswordBox control supports a PasswordChanged event and the Button control supports a Click event

One of Silverlight’s great strengths is this ability to manipulate anything you declare in your XAML code through a coherent object model. Check out the Silverlight Developer Center in the MSDN Library for a comprehensive reference to the whole API.

Interacting with a PHP Web Service
Most of the techniques discussed so far work with both versions of Silverlight. However Silverlight 2.0 opens up new possibilities for client-side processing as it includes a version of the .NET Framework and the Common Language Runtime (CLR) which allows it to run client-side code written in C#, Visual Basic and many other languages. The code for such programs is compressed into a single ZIP file together with the XAML definition and a manifest (also written in XML). The result is given the file extension XAP and referenced through the plug-in’s source parameter in the same way as we referenced our XAML file in the example above. When the page containing the plug-in is opened by the client, the XAP file is downloaded and unpacked, and then the code is compiled and executed.

This opens up further opportunities for the PHP programmer as such applications can make calls to Web services, and those Web services can be defined in PHP. For such an application to work the service has to be SOAP 1.1 compliant, and you will need to define a clientaccesspolicy.xml file if the service comes from a different domain to the application. This is to prevent cross-site forgery (see the article Making a Service Available Across Domain Boundaries for more on this).

It is also worth noting that Silverlight 2.0 also includes the Dynamic Language Runtime (DLR) which supports IronPython, IronRuby and Managed JScript. These languages are being developed at Microsoft’s open source project hosting site Codeplex. For further details see Silverlight Dynamic Languages SDK.

Choosing the Right Tools
While not a requirement, Microsoft has released a number of tools that would be useful to the PHP developer looking to work with Silverlight. Microsoft Visual Web Developer 2008 Express Edition is a useful Web page designer with full support for CSS, JavaScript and AJAX. It can also be used with Silverlight Tools for Visual Studio 2008 to automate production of much of the infrastructure behind a Silverlight application. Both can be downloaded from the Microsoft Web site free of charge.

Microsoft Expression Blend 2 is a professional graphic design tool that outputs XAML, allowing designers to create attractive user interfaces and to automatically generate the code required by Silverlight for its display. Alternatively increased support from the community means there are a growing number of third party XAML editors out there as well.

Sitting alongside Blend 2 is Microsoft Expression Web 2. Aimed at the professional Web designer, this latest release introducing many features that have been designed specifically for the PHP developer. There are menu options for inserting common PHP snippets, including pre-defined form, URL and session variables, server side includes and other structures. Furthermore, Expression Web 2 will render the page in Design View as though all the code, including server side includes, were in a single file, allowing you to see your code in action without leaving the editor.

Expression Web 2 understands PHP which means it will colour code language constructs intelligently, and there is full support for auto-completion so that you can see what functions and parameters are available to you as you write the code. Expression Web 2 also includes the PHP 5.2.5 runtime which you can use locally as a development server.

So Silverlight has a great deal to offer the PHP developer – something that Microsoft is clearly recognising with its support for PHP in Expression Web 2. Trial versions of Microsoft’s Expression range are available for download.

[Main image by Pathfinder Linden]

This was the situation we found ourselves in back in March just after we launched Diarised. We had people not only visiting us from all over the world but blogging about us in many different languages. We thought it would be a nice idea to get Diarised working in a few.

The process of getting your website ready for multiple languages is known as internationalisation. Internationalisation goes beyond getting the website working in other languages and covers aspects such as dates, times and currency. In this two part article we’re going to look at how you go about preparing a website for internationalisation. Then we’ll look at solutions to some of the real-world problems that can arise, such as dynamic data and plurals.

Associative Arrays

As a first stab at internationalisation we might try using associative arrays. We could store our translated text using the English text as the key, like so:

  //set up our language arrays

  $english["welcome to example.com"] = "welcome to example.com";
  $english["have a nice day"] = "have a nice day";

  $spanish["welcome to example.com"] = "Bienvenidos a example.com";
  $spanish["have a nice day"] = "Ten un día bueno";
  ...

  /*
  *  We'll set the locale based on a variable in the query string
  */

  switch($_GET["lang"]){
    case "es":		            //es turns the page into Spanish
      $messages = $spanish;
      break;

    default:			    //everything else defaults back to English
      $messages = $english;
      break;
  }
  ...

  echo $messages["welcome to example.com"]

Adding new languages should then be a case of adding more arrays and updating the switch statement. Perfect! Well not quite. There are a few issues with this approach:

1. Dynamic data. What if you need to insert someone’s username into a sentence? Breaking the sentence down into lots of little phrases will only make your translator’s life difficult and will probably lead to inaccurate translations.
2. You’re assuming your translator will be able to understand PHP array syntax and avoid breaking everything. What happens when they decide to stick something in quotation marks? The last thing you want to do after receiving a translation is to start debugging syntax errors.
3. This approach won’t fail gracefully. What happens if you accidentally type: echo $messages["wlcome to example.com"] By missing off the “e” your translation will break and leave blank text.

Clearly this method has issues. What we really want is a way to allow non-techies to translate our text for us and a way for us to simply “plug” the translation back into the website.

Introducing Gettext

After ruling out associative arrays to do Diarised translation’s we decided to use gettext. gettext is the GNU internationalization library and it provides an excellent way of separating code from content. If you’re hosting on Linux there’s a good chance it will already be installed on your server.

So, how does it work?

The official Gettext website gives a highly detailed and fairly confusing overview but the gist is:

1. You pass every piece of text you need translated through a function called gettext
2. Once everything has been marked up you run the xgettext command to create a PO (Portable Object) file. This is a plain text file containing the source text and a place for the translated text
3. You send this to your translator to open with a PO editor
4. Once your translator has filled out the translations they send the PO file back to you
5. You compile the PO file into a MO (Machine Object) file that gettext can read
6. You set the locale of your site to a language (usually through the query string) and sit back and admire your website in a totally different language

Step 1 is just a case of the following:

  <p>welcome to example.com</p>

becomes

  <p><? echo gettext("welcome to example.com"); ?></p>

Marking up your code to use gettext is probably the most irritating step but fortunately you only have to do this once. It will then work for as many languages as you like. The next stage is to get this information into our translation file.

How to create a PO file

The first step is to set up the directory structure:

1. In your webroot folder create a folder called locale
2. Inside that create a folder for each language you plan on supporting and use the language code as the folder name, e.g. for Spanish use es_ES or if you wanted say a localised Argentine version you could have es_AR
3. Inside each of those folders create a new one called LC_MESSAGES. This is where we will keep our translation files

To create the PO file you’ll need to use the command line but don’t worry we’re here to hold your hand. Fire up a terminal window, connect to your webserver and be brave.
The command we need is called xgettext, this will scan a script looking for calls to gettext then grab the text you’re passing and put it into a PO file. For example:

  # xgettext -o messages.po *.php

This will search every PHP page in the current working directory and stick the results in messages.po. Once this is done open the file with a plain text editor and make the following change:

  "Content-Type: text/plain; charset=CHARSETn"

becomes

  "Content-Type: text/plain; charset=utf-8n"

Now save it and send it to your translator

Although a PO file is a plain text file its contents aren’t particularly friendly. Luckily there are a few pieces of software that make editing PO files a bit easier (especially for your translator). For Windows there’s poedit, and for the Mac there’s LocFactory Editor. Both are free and will make your translators lives much easier.

When your translator sends the PO file back stick it into the appropriate LC_MESSAGES folder created earlier and open a terminal window so we can compile it

In your command window go to the LC_MESSAGES folder with messages.po and issue the following:

  # msgfmt messages.po

Assuming there were no errors this will churn out a file called messages.mo. This is the compiled file gettext will actually read, any changes to your PO file will require you to redo this step to make the changes live. Now all we need to do is tell gettext which language we want our text in.

Binding a locale

This step can be done via a few lines of PHP near the start of your script:

  $locale = $_GET["locale"];

  putenv("LC_ALL=$locale");
  setlocale(LC_ALL, $locale);

  bindtextdomain("messages", "locale/");	//binds the messages domain to the locale folder
  bind_textdomain_codeset("messages","UTF-8"); 	//ensures text returned is utf-8, quite often this is iso-8859-1 by default
  textdomain("messages");	//sets the domain name, this means gettext will be looking for a file called messages.mo

$locale will need to be set to the locale that you want the website appear in. To begin with it’s simplest to set this via the query string as shown above. One of the advantages of gettext is that if it can’t find a folder for the locale you pick it will just go back to English, meaning when someone sticks locale=kl expecting a Klingon version they’ll just get English.

That’s it for part one. At this point you should be able to at least make a start on preparing your websites for internationalisation. In part two we’re going to look at some of the real world issues you’re likely to run into and tell you what we did to solve them on Diarised.