James Titcumb

There is a really easy way to document PHP (from a technical perspective anyway), and it’s known as phpDocumentor (or phpdoc for short).

Most good PHP IDEs (Eclipse PDT, PhpED, and probably Zend Studio, but I have not tried that) will support the language, which is actually pretty easy to remember and use anyway. phpdoc is just comments that are formatted in a special way. Phpdoc notation is like a normal comment, but is preceeded by /** instead of the regular /*. There are several special keywords that one can use as well to assist in documentation.

The other great thing about phpdoc is that the IDE (Eclipse PDT and PhpED do this) picks up on the variable types specified before a function, which makes code tooltips much more efficient.

Have a look at some sample phpdoc’ed code (not checked for syntax!):

<?
	/**
	 * File description goes here
	 */
 
	/**
	 * Class description goes here
	 *
	 * @name ClassName
	 * @version 1
	 * @package PackageName
	 */
	class ClassName
	{
		/**
		 * This variable holds some information
		 */
		private $SomeMember = 5;
 
		/**
		 * This function does something
		 *
		 * @param String $some_arg1 A string to be echoed out, prepended by Hello:
		 * @param OtherClass $some_arg2 The object containing a number that will form part of the division function.
		 * @return Number The value after the division.
		 */
		public function DoSoemthing($some_arg1, $some_arg2)
		{
			echo "Hello: {$some_arg1}";
			return $some_arg2->SomeNumber / $this->SomeMember;
		}
	}
?>

As you can see, just formatting the comments a bit better makes things clearer. The step after is to generate the documentation, which is an automatic process and more can be found on the phpDocumentor website.

Every few months I re-investigate what bitwise is and how it works as I’m always forgetting what it does and how it works, and how useful it actually is. I’ve not yet used bitwise in PHP, so I thought I’d investigate and write a flag system in PHP that uses bit vectors.

First, let me give you an overview of how the flags work underneath. A flag in my example is the number 1, shifted n steps left. I have a list of flags that represent different weather situations, that could happen simultaneously:

define("WEATHER_CLOUDY", (1 << 0));
define("WEATHER_FOGGY", (1 << 1));
define("WEATHER_RAINING", (1 << 2));
define("WEATHER_SNOWING", (1 << 3));

These values, displayed as binary are 1, 2, 4, 8 respectively. The important part however, is not the decimal values, but the binary values, which are 0001, 0010, 0100, 1000 (with leading zeros for ease of understanding).

Read the rest of this entry »

So here is my creation on Spore; Asgrimus Maximus. He looks a bit like a deer, with a spiked codpiece, but it’s not meant to be a codpiece, more of a belly button. Nevertheless, as you might notice, I’ve been dragged into the Spore phenomenon. It’s quite an enjoyable game so far, I’ve just got into the Tribal stage, and haven’t played much with it, but its seeming very much like an RTS now instead of before, where it was just “find as much DNA as possible”. Eventually I’ll manage to get into again, but life is busy!!

Say you have a table of information, and another table that has more information, there’s a clever way of getting data from, one, the other, or both. It’s nothing new really at all, more of a reference thing for me… Say you have two tables:

common_table:

uncommon_table:

Joining these is a standard operation, and if we wanted all records, that may or may not have a postcode, we’d:

SELECT * FROM common_table c LEFT JOIN uncommon_table u ON u.customer_id = c.id

And that would give us:

Note carefully the fact that the uncommon_table values in the second row are NULL. We can use this to distinguish which records have entries in the uncommon_table, and which don’t. Then we can form queries based on this, for example if you wanted a report of each user with their postcode, ignoring those without postcodes:

SELECT * FROM common_table c LEFT JOIN uncommon_table u ON u.customer_id = c.id WHERE u.id IS NOT NULL

And converseley, find those people who haven’t got a postcode entry:

SELECT * FROM common_table c LEFT JOIN uncommon_table u ON u.customer_id = c.id WHERE u.id IS NULL

Knowing this can be handy, and sometimes quite powerful.

I posted the other day that I couldn’t get Bugzilla working due to missing Perl modules*. Well last night I badgered 1and1.co.uk to install the modules, but I got a vauge no. I carefully read various pages, and got it installed… here’s how:

Read these instructions** first. If the CPAN shell complains about not having permissions to modify /root/.cpan, read this. Instead of putting the whole Apache httpd.conf <Directory> section (you probably dont have access to an httpd.conf…), you can put the AddHandler/Options/DirectoryIndex lines in a .htaccess file in the Bugzilla directory. Just to note that I couldn’t add the AllowOverride option in for some reason - it threw a 500 error…

Another thing that confused me was this:

perl -pi -e 's@use strict\;@use strict\; use lib \"/home/foo/perl/lib\"\;@' *cgi *pl Bug.pm processmail syncshadowdb

Perhaps the document is out of date, but none of those files existed. I changed Bugzilla.pm (note: you must use the FULL path to your local Perl installation, not just ~/myperl/lib!!!), and hey presto, it works! I now have a nice neat and tidy Bugzilla installation.

* It turns out that Bugzilla 3.2 (in release candidate stage) has a script to do all this for you - doh!

** Updated documentation link to the correct version - doh!