Archive for January, 2007

Custom PhpDocumentor Templates

January 30th, 2007

PhpDocumentor is an essential tool all serious PHP developers should know about.
By parsing the phpdoc blocks within the source of your files phpDocumentor can generate API documentation for your entire project/application.

I recently had the need to build a custom output template for the HTML converter, and decided to distribute it using a PEAR installable package so other PHP developers at the University could generate documentation for their code.

The process is fairly straightforward – I copied the frames template and created my own named ‘UNL.’ This template yields .php pages in the UNL Templates so that the API documentation matches the rest of the www.unl.edu website.

Tricks with creating an installable PEAR package were to mark all the files .tpl, .inc, etc as ‘php’ and to use ‘/’ as the baseinstalldir. This will make sure the template files get installed into the correct location.

Other UNL PHP developers can run:

pear install pear.unl.edu/UNL_PhpDocumentor_UNLHTMLTemplate-alpha

And then set phpDocumentor loose on your files like so:

phpdoc -po UNL_DWT -o HTML:UNL:UNL -d UNL_DWT -t /Library/WebServer/pear.unl.edu/docs/UNL_DWT/

which will generate API documentation within the UNL templates and it will look like this.

How to ‘Own Your Own Website’

January 29th, 2007

A friend recently asked me about how to own your own website… this is something I’ve had to answer so many times I decided to finally write it down.

There are two things to having ‘your own’ website:
1. Register a domain name.
2. Find a hosting provider.

(most companies allow you to do both at once)

To get a .com .net .us whatever address, you need to ‘register’ the
domain name of your choice with a company called a Domain Name
Registrar. There are a few select companies which have access to
modify information on the Internet and add entries into the system
known as ‘DNS’ – the domain name system. Here’s a couple popular ones
to just register a name with: http://www.godaddy.com/,
http://www.register.com/
Domain name registrars usually go by yearly rates, and will vary
anywhere from $35/year to $8/year.

Now, that name only gets you a small part of a personal website – that
gets you an entry in the Internet’s root domain name servers which
translates your domain name ‘fishstickmartyrs.com’ to an IP (Internet
Protocol) address. This is important so that when someone types in
your foobar.com address it gets translated to an address of 1’s and
0’s so your computer can connect to the server where your website is.
An IP address is unique to every computer connected to the Internet
and is the actual address which data gets routed to through the wires.
Think of the IP address as the Internet’s equivalent of a mailing
address. My mailing address is 1234 Briarboot Rd. Lincoln, NE 68588 and
that’s what you need to send information to me —- on the Internet
it’s a string of digits… normally people see it as a grouping of
four digits. My IP address at home is 24.27.144.78, and mine at work
is 129.93.25.136.
What a lot of people don’t know is, that’s truly all you need – a
computer connected to the Internet with an IP address! If you entered
in http://24.27.144.78/ , or http://129.93.25.136/ , you would see my
personal website and my work website respectively. So, in all
actuality, you don’t need a .com or a .net address at all. You could
just say, visit my website at http://###.###.###.###/ … which
actually sounds kind of absurd, because those numbers are hard to
remember. That’s why the DNS system is necessary.. to give humans
something a little easier to remember to connect to the various
machines on the Internet they want information from.

Keep in mind owning a domain name gives you a lot of potential
addresses. For example, I own saltybeagle.com. This means I own
*.saltybeagle.com… so I can arbitrarily set up any name I want on
it. shockers.saltybeagle.com, tyson.saltybeagle.com,
mike.saltybeagle.com etc etc.

Ok, now you know all about DNS and why it’s important.

The second part is Hosting, or a hosting provider. When you type in
the domain name, your computer checks with a server to get the IP
address of the machine holding the information. That machine can be
one that you own, or more commonly a machine you lease space on. I
host my own website, which means my computer at home is my server. So
when you type in http://saltybeagle.com/ my computer at home is
sending you the information (most people don’t do this unless they’re
uber geeks).
The other option is leasing space on a server someone else owns. A
hosting provider is a company which offers you space on a server
connected to the Internet. Most offer various plans with different
levels of service. Things to be conscious of are bandwidth, space,
monthy rate, email options, and shell access or ftp access (if you
plan on doing anything fancy). Bandwidth in the hosting arena refers
to how much data your website can serve out in a month, and space
means how much data you can store on their server. The monthly rate is
how much it will cost you to have them host your website — when you
look at a hosting provider, note if domain name registration (our #1)
is included in that monthly rate or separate. Hosting can cost you
anywhere from $8/month to the skies the limit. Email is important if
you want to send email as todd@fishstickmartyrs.com. Shell access is
important for users who want to do more than just serve out flat
files, and do advanced things — something you may not need at all.

Basic plans will cover most beginning users — and all hosting
providers offer ways to increase your plan.

I personally have no experience with hosting providers, but I know of
people who use and are happy with http://www.dreamhost.com/

Now, there are various places out there who will give you a free ride
because they gain from advertising or they want your content. This is
the case of blogspot for example. They provide you space and your own
subdomain entry advancedsasquatch.blogspot.com, and they are a hosting
provider for you free of charge. Kinda nifty in a way… you get free
hosting, and don’t have to pay for anything. But — you don’t have the
vanity of your own domain name, nor all the other features other
hosting providers might offer.

Others offer free space for just certain content — take pictures for
example: http://flickr.com/ and http://picasaweb.google.com/ will
host your pictures for you for free…
Yahoo/gmail want your email content and they’ll host your email for
free etc etc.

Keep this in mind when you consider hosting and bandwidth. You can
save if you buy a small hosting plan and utilize the services of
another source like flickr to serve out your pictures, which is
typically the large percentage of bandwidth — or keep using yahoo,
or gmail for email.

If you plan it right, you can certainly get by with only buying a
Domain Name! But, you have to plan out your services, and become a
server administrator yourself or leave your information in the hands
of another hosting provider — each has its benefits and drawbacks.

Simple Guidelines for Proposing a PEAR Package

January 24th, 2007

Recently I went through the proposal process for a PEAR package (Services_W3C_HTMLValidator) and figured I would write down some thoughts.

Simple Guidelines for Proposing a PEAR Package ( and getting it approved ):

1. Lose your ego (if you have one). Your code might be good, but there are plenty of people out there who will find flaws with it. The sooner you realize others can help you, the sooner you can move on to accepting help and improving your code.

2. Choose an appropriate package name. And be sure you understand why the underscores are in package names. Examine what packages are out there, and note their category and naming scheme — the package name should quickly convey the purpose of your package. Also make sure you look to see if your package is already in the repository.

3. Follow the coding standards. PEAR developers will nitpick you to death – it’s best to just correct this ahead of time. The biggest ones are: Use 4 spaces, not tabs! Take a look at PHP_CodeSniffer and run your code through this before you submit any code.

4. Document your code. If you expect anyone else to use your code, you MUST document it. Provide internal documentation using PHPDoc syntax – AND externally using general terms anyone can understand.

5. Provide useful examples. You must have examples which work and are easy to understand – and you MUST have examples which cover the basic functionality your package provides.

Anytown USA

January 21st, 2007

I awake to see the empty canvas laid out by mother nature — rolling hills of white bumps like Christmas cookies dusted with powdered sugar. 4 inches of snow had fallen through the night.

Like clockwork, every male neighbor opens their garage door at 9:00 AM on this Sunday morning. Each dressed in snow garb, with stocking caps, boots, snowsuits. . . some just in sweatpants; each priming their snowblowers to carve the landscape away.

The sound of small engines echoes down the street as streams of snow fill the air. Each one helping his neighbor, cheerfully wishing good morning as they clear the pavement.

Ahh…. Anytown USA. It’s good to be here.

Ubuntu LIRC

January 7th, 2007

UPDATE:

Ubuntu now has a helpful wiki page, and with Gutsy, installation is much easier. See https://help.ubuntu.com/community/Install_Lirc_Gutsy

So what’s the hardest thing I’ve ever done in Ubuntu? Compile a custom driver for a LIRC remote. I bought a Streamzap PC remote at Fry’s in Dallas a couple weeks ago and finally sat down to get it running in Linux. Sheesh… never before has one simple task given me so much trouble. In gentoo I could have rebuilt everything for mythtv in the time it took me to just get one simple module built for Ubuntu. Every tutorial on the net wants to teach you how to make installable .deb files to replace the distributed packages – this is completely unnecessary in my opinion.

Here’s how I got it to work, in case you’re in my shoes:

sudo apt-get install linux-source build-essential automake libtool
cd /usr/src/
sudo bunzip2 linux*
sudo tar -xvf linux*.tar
sudo ln -s /usr/src/linux-source-2.6.17 /usr/src/linux
sudo cp /boot/config-`uname -r` /usr/src/linux/.config
cd /usr/src/linux
sudo make
cd ~/
cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login
cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc
cd ~/lirc
./autogen.sh
./setup.sh
sudo make
sudo make install

After that you should be able to plug in the usb module, run dmesg and see that it found the correct device, then sudo /etc/init.d/lirc restart, and use irw to see the correct codes.

Some notes: I just run make on /usr/src/linux to get the correct version info built into header files. If you don’t complete this step the LIRC module will be built and fail because of a version magic kernel string mis-match.
I had to use the CVS version of LIRC because the USB module syntax has changed with kernels > 2.6.13, specifically affecting the streamzap driver. Like I said, there are plenty of other guides out there which teach you how to build the entire kernel/modules and make a .deb package to install – all of these are a huge waste of time to just build one necessary module.