Setting up PhD on Windows

Documentation for PHP

Ever have an issue with PHP documentation and file a bug, only to have it sit for a long time? Or find a typo or other error in the documentation and have someone tell you “send me a patch”. PHP has, in my opinion, some of the best API documentation around. But the documentation is written, edited, and updated completely by volunteers so it’s only as good as the people who help write it. And there are never, ever enough people who want to document an open source project.

Ever contemplate contributing back to PHP? Have you ever thought about submitting a change for the documentation, but couldn’t figure out where to start? Documentation is an easy way to give something back to the PHP community. Yes I said easy – I’m not lying. There just isn’t good documentation on how PHP documentation works. (PHP doesn’t have enough volunteers to keep up with API documentation, much less people to spare to document the documentation system)

PHP documentation is written in a slightly modified Docbook 5 format. The files are all available in PHP CVS. Just to confuse the world, PHP documentation is often referred to as phpdoc – which is not phpdoc or phpdocumentor. Those are scripts for generating documentation from comments in php scripts. The phpdoc at php.net is for documenting the PHP runtime, API, and extensions.

If you open one of the xml files in php cvs you’ll see it doesn’t look very much like the documentation on the PHP website. The information in those files is “rendered” with a system written in PHP. I think it’s rather cool that PHP documentation is created with PHP. The documentation is written in XML because the data can be output into various formats, from straight html to chm. The renderer that PHP uses is called PhD (that’s PHP-based DocBook Renderer, someone was trying to be clever) The renderer does not support every DocBook 5 tag yet and PHP has added additional tags to the DTD . All the extensions live in their own XML namespace “phd:” which resolves to http://www.php.net/ns/phd.

So, you’ve decided you want to help out – where do you start? Before you can edit a file or document an extension you need to be able to build the manual to check your changes. So you need a working install of PhD. In order to accomplish this goal you’ll need three things installed and configured, which is what this article is intended to help with.

1. PHP installed somewhere on your system. If you’re using Windows you MUST use PHP 5.3 (for getopt support) or have 5.2.x + PEAR + PHP_Compat installed.
2. The phpdoc xml files from cvs
3. PhD

If you already know your way around an operating system there’s a “five minute install” version you can jump to, otherwise keep reading for the “long view”.

I’ll be showing you how to do this on windows, since most people using linux, mac or a unix variant know what they’re doing, but most of the steps are similar for any operating system.

Installing PHP

If you’re not on windows, chances are you have PHP installed somewhere, and your getopt support works fine – move along.

If you ARE on windows you will need PHP 5.3 to run PhD, or a PEAR install with PEAR’s PHP_Compat package available. But that would take too long, and I’m lazy (besides, it’s fun to play with development PHP versions)

It is VERY easy to install multiple versions of PHP on the same machine, so I’ll introduce you to my famous “three file install” (That’s right, you only need three files to run PHP on windows)

First of all, pick a spot for your new 5.3 install. I’m boring, I’m putting mine into c:\build\phd\php. Make a directory for it wherever you decide to put it. Next you need PHP 5.3 Notice this is NOT a released version and may have quirks. Since we’ll be using the CLI version of PHP, you can get the NTS variety. NTS stands for non-thread safe. You also have a choice of which compiler version to use – VC6 or VC9. What’s the difference? VC9 is faster, better, more interesting – but you’ll need to run a little msi installer for a runtime .dll the first time you install PHP. The VC6 version is slower but no installer required.

QA builds of PHP 5.3 can be found at windows.php.net Download either the VC6 non thread safe version or the VC9 non thread safe version of the PHP 5.3 beta1 . If you’re very brave (or insane, or any combination thereof) you can try a snapshot version of 5.3 available from the same site.

Open up the zip file and grab three things – php.exe, php5.dll, and php-ini.recommended and put it in the location you’ve chosen (c:\build\phd\php for me). Rename php-ini.recommended to php.ini If you’re using the VC9 build for the first time, you’ll need to install the Microsoft 2008 C++ runtime as well.

One last thing – PHP 5.3 is VERY noisy if you don’t set a default timezone! Open up that php.ini file (even notepad will work for this) and find the line that says


;date.timezone =


Remove the semi-colon (that’s a comment) and set it to … something. You can find a list of timezones at php.net/timezone (man I love the docs… and soon you can help make them even cooler) My new line looks like this

date.timezone = America/Detroit


Want to test your new PHP install? Open a command window (you can type cmd.exe into the run dialog from the start menu). Then cd to the location of your new PHP and type php -v. You should get information about your new php install.

A little note, you’ll be doing a lot of command line work for PhD so you’ll need to be properly acquainted with cmd.exe.

If you’re on XP the Open Command Window Here PowerToy will make your life SOO much easier. Simply install it, and then right click on any directory. The context menu will have an “Open Command Window Here” choice.

If you’re on Vista – just hold the shift key while right clicking on a directory and the “Open Command Window Here” choice will appear. But on Vista dragging and dropping files into cmd.exe to get the full path is broken – you can get a magic “Copy as Path” choice if you hold shift when right clicking on a file. So on XP you can drag a file into a command window and get a magic path – on Vista you have to shift and right click until your fingers bleed.

Installing PhD

There are two basic ways to install PhD. One way uses the PEAR installer, but I haven’t had good luck with it and local PEAR installs (and I am NOT wanting a global install on this machine – and yes Helgi I should file a bug … not enough time in my day).

If you have a working PEAR installer on your system …

pear channel-discover doc.php.net
pear install doc.php.net/phd-beta


You only need to do the channel-discover call once, after that your PEAR installer will know where to find PhD. Future versions of the PEAR installer will probably have the channel already available for you, but for now you need to “discover” it first.

If you’re lazy, or PEAR is flaky on your system, or you’re just a contrary person it is easy to install PhD by hand. First you need the source, the current “release” is found at http://doc.php.net/phd/PhD-0.4.5.tgz. Unpack it into any location you please. I keep all my current work in c:build, so I’ll be putting it at c:\build\phd for this article. If you don’t have a program capable of dealing with .tgz files on windows, 7-zip is a great open-source choice (even works on 64 bit correctly).

You will need to do one more step after extracting the files. The PEAR installer would have changed information in some files for you, since it didn’t, you need change one file by hand.

First of all, open phd.bat. Do NOT open it in notepad.exe – why? Because the line endings are wrong (again, I need to file a bug…) Instead open it with wordpad.exe or your favorite editor (Komodo/KomodoEdit works great – yes I am pimping my favorite editor) You can’t just right click on on the file either, you’ll need to open wordpad (or your editor) and open the file from there. (Notice if you open the file in wordpad, you need to change the file type filter to have the .bat show up).

This is what you should see in the file

@echo off
REM $Id: phd.bat,v 1.1.4.1.2.1 2008/12/02 21:27:59 kalle Exp $

@"@php_bin@" "@bin_dir@\build.php" %*


You need to change two things – the @php_bin@ should be the path to your newly placed 5.3 php.exe, mine is at C:\build\phd\php\php.exe – notice if you have spaces in your path, be sure to keep the quotation marks in the file intact. The other thing you need to replace is @bin_dir@ – which should be the path to where you have placed the phd files – in my case c:\build\phd

My finished version is

@echo off
REM $Id: phd.bat,v 1.1.4.1.2.1 2008/12/02 21:27:59 kalle Exp $

@"C:\build\phd\php\php.exe" "c:\build\phd\build.php" %*


There – was that so hard?

phpdoc source

Now it is finally time to get the php documentation sources. If you’re not on windows, or are addicted to the command line and already have CVS set up somewhere, the relevant commands to get a phpdoc checkout are


cvs -d:pserver:cvsread@cvs.php.net/repository login
cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc

The password is “phpfi”

But if you prefer something a little easier to work with…

The single easiest way to do any kind of cvs on Windows without losing your mind is tortoisecvs. Seriously, if you do not have it, get it. It even does tricky stuff like translating your line endings to the nix version so nix people don’t jump down your throat after a commit. You can use command line or other versions of cvs clients, but I’m going to explain how to do the checkout with tortoisecvs. Also make sure you have a CURRENT version of tortoisecvs – there were some nasty pserver login bugs with earlier versions. And make sure you restart after installing or upgrading – theoretically you don’t have to but this IS windows after all. If you’re installing tortoisecvs and the cvsnt installer portion confuses you, remember you ONLY need the client stuff, not the server or anything else


Pick a spot to dump the phpdoc files. Again, I’m so terribly original so I’m going to be using c:\build\phd\phpdoc . Go to the directory ABOVE where you want phpdoc located (for me this is c:buildphd) and right click. See the pretty tortoisecvs stuff that appears? Choose “Cvs Checkout” and get a pretty dialog. First of all copy this line


:pserver:cvsread@cvs.php.net/repository


And paste it into the top line there where it says CVSROOT (see how the other stuff magically fills in?)

Next where tortoisecvs says “module” put phpdoc

Tortoisecvs will automatically put the checkout in a folder called “phpdoc” – if you want a different name, hit the options tab, hit the “Enter your own folder name” option and put the name you want in the dialog. Now for the fun – click OK!

Now – tortoisecvs might pop up a login window, or it might not – if it DOES the password is “phpfi”


Watch the pretty checkout scroll by – warning – this is is big and will take a bit of time. Finally you’ll see the “Success, CVS operation completed” message.

Look in the newly created phpdoc directory and you should have a TON of files in there


One more step – we need to build a special file called .manual.xml using PHP. Here you’re going to get a quick lesson in file paths. You need to use your PHP 5.3 php.exe to run the configure.php file in your new phpdoc directory. Below is what I typed, the location of your php.exe might be different. If you’re on XP you can simply drag and drop php.exe onto a command window to get the full path. Vista you need to shift, right click, choose “Copy as Path”, right click in your command window, choose paste.

Pain… In… Rear…. (or just type out the full path if you’re bored)


"c:\build\phd\php\php.exe" configure.php --with-php="c:\build\phd\php\php.exe"


Notice that you’ll need to tell configure.php what php executable to use for it’s magic, and it is generally a good idea to quote paths on windows because you never know when a space might pop up.

You should see a little message that says “all good, done” – congratulations! You have a .manual.xml file.
Take your phd.bat file and copy it into your phpdoc checkout (really, will make your life easier)

Using PhD

Now you have all the necessary ingredients to build the docs – the cvs checkout, PhD, a PHP CLI install with getopt support. Time to finally build some documentation.

Open a command window and cd to where you have that phpdoc checkout located. If you followed my advice earlier you can just right click on your the directory and tell windows to “open command window here”. Running the following code


phd -h


to get some extremely ugly help output (it’s longer than 80 characters, I know, I know, another bug to file)

You can read the explanations to get exactly the command you need. But I’ll save you some time and energy. If you’re just looking to build one version of the docs so you can track your changes, the command you’re looking for is


phd -d .manual.xml -f xhtml -t chunkedhtml


This will create a directory called “html” with a plain (as in no css) rendering of the PHP docs.

I’d like to create an html version with php.net style css – but again, something to add to a bug report (preferably with a patch)

Five Minute Install

Here’s the short version wrapup of installing PhD – if you’ve read the long version this is just review

1. Get a working PHP install.
   • On windows, install PHP 5.3, or PEAR with PHP_Compat package
   • On other systems, any PHP above 5.2 will work
2. Install PhD
   • Using Pear
     
pear channel-discover doc.php.net
pear install doc.php.net/phd-beta

   • By hand

     Download PhD-0.4.5.tgz and decompress it somewhere

     Change @php_bin@ location in phd.bat on windows or the shebang at the top of the build.php file to the absolute path to your PHP CLI binary. If on windows changed the @bin_dir@ in phd.bat to your phd directory

   • Get phpdoc sources
     
cvs -d:pserver:cvsread@cvs.php.net/repository login
cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc

     Password is phpfi
   • Run configure.php in your phpdoc checkout
     
php configure.php

     Windows users will need to add —with-php=”full/path/to/php.exe”
   • Run PhD

     From inside your phpdoc checkout run

     
phd -d .manual.xml -f xhtml -t chunkedhtml


Done!

Onward to Fame

Now you can build the PHP documentation any time you want. So what comes next? Probably editing the existing xml and creating patches. But that’s a post for another day. You can find more information about phpdoc and phd from the Documentation Wiki and the phpdoc volunteers hang out on efnet on #php.doc

Happy Documenting!

Seven (Weird) Things (

It’s like a giant game of tag around here! So Derick has so graciously tagged me – I suppose I need to do this before everyone has already been tagged!

Warning – I ramble…

1. I grew up in a Mennonite family and have some Amish relatives from my grandmother’s families. Yes we drove a car, but there are still a lot of Amish and Old Order Mennonites who live in this area. I can remember my mother wearing a covering on her head at church when I was small (looked like a knit doily) but fewer and fewer did as I grew older and the church became more “modern”.
2. I love music. From the hymns I sang in church as a child (Dad sang bass, Mom alto, Me soprano and my brother Tenor) to the camp songs around the fire every summer, music has always been a part of my life. I played flute in middle and high school, took piano lessons, sang in the Choir in high school, and also did Color Guard in marching band. Those experiences are some of my best memories, including the Trip to Toronto my Senior Year to watch my first “real” stage show (Beauty and the Beast) and the trip to Walt Disney World. It was amazing marching down main street flipping a flag and listening to MY band play just before the fireworks show.
3. I once broke my toe shoes in the middle of a performance and kept on dancing anyway. I love to dance. I took ballet lessons for 20 years – was a dance major in college my freshman year but had a baby instead of staying on that path professionally. I continued to take lessons when I could. I still dance whenever I get the chance.
4. I was an English (Creative Writing) major for the rest of college with a minor in Sociology but never finished my degree, I had two kids to support after my divorce so school was off my list of things I could do.
5. I am a manga and anime addict. I got started in college, when Sailor Moon played on Toonami every afternoon in 1998 – when my then 1 year old son was taking his nap. It also was my gateway to the internet and PHP – free “dial-in” from the college meant I could be online all the time, and every fan had their own website. My dad was playing around with linux, running a server off his cable connection (back before port blocking and bad latency) and gave me some space to play. I wanted a forum and he installed PHP for me – the rest as they say is history. But I still have my anime and manga collections and write Fanfiction about my favorite shows.
6. I have never taken a single computer class. I learned PHP because my forum software wouldn’t work and no one would help. I learned html and css to help with my site. I learned to admin a linux box so I could run my fun toys. I learned C because Andrei pissed me off. Seriously.
7. I still play with dolls. I collect American Girl dolls and love to design period clothes for them. I love to sew. I made my own wedding dresses (both of them) – the second one I designed as well. By extension I also knit and crochet and embroider and do cross stitch. The saddest thing I ever made was a piece when my grandfather died – it was a border of red carnations with a bible verse. They buried it with him.

Now for seven people to pass off to: this is really hard for me because so many people have been tagged that I know, but I’ve been told it’s legal to tag someone until they write a tag post

1. Andrei Zmievski – the man who started my descent into C madness
2. Chris Shiflett – My boss, who does far too much and needs a vacation and introduced me to the only beer I’ve actually been able to drink
3. Wez Furlong – Who when I complained no one was looking at my windows patches opened up his laptop and gave me karma
4. Sara Golemon – Who held my hand when I was learning C and PHP internals, answered every stupid question, and is a hell of a lot of fun to drink with.
5. Luke Welling – who teaches me the most interesting Australian phrases, and can turn any bad thing at the office into a laugh worthy lukeism.
6. Bob Madjak – PHP-GTK buddy and the closest PHP dev I’ve ever met (as in physically) who sat in my basement during the phpthrowdown and slept
7. Joe Stagner – who got me software when I needed it and always answered my “look what I did” with “Cool” instead of “Why are you doing that on Windows”

And now for the 7 things rules:

• Link your original tagger(s), and list these rules on your blog.
• Share seven facts about yourself in the post – some random, some weird.
• Tag seven people at the end of your post by leaving their names and the links to their blogs.
• Let them know they’ve been tagged by leaving a comment on their blogs and/or Twitter.

Acorn Squash Cream Soup

I made this for Christmas dinner and even my picky brother-in-law liked it

Ingredients:
* 1 small onion, chopped
* 1 stick of celery, chopped
* 4 tablespoons butter
* 2 tablespoons flour
* 1 teaspoon chicken bouillon granules (or 1/2 boullion cube)
* 1 teaspoon dill weed
* 1/2 teaspoon curry powder
* 1 1/2 cups chicken broth
* 1 1/2 cups whipping cream
* 3 cups mashed cooked acorn squash

Garnish:
* salt and pepper
* bacon, cooked and crumbled
* croutons

Directions:

Saute the onions and celery in the butter. Stir in the flour and spices. Slowly add the broth and cream and heat until boiling. Mix in the squash and cook until thick. Process in blender in small batches (1 to 1 1/2 cups at a time) until smooth. Season with salt and pepper, garnish with croutons and crumbled bacon. Even kids won’t know they’re eating vegetables

A walk into my mind

Something people tend to forget (myself included) is that I originally started this site for my writing. So I guess I need to spend a bit more time letting out the words that fill my head on a daily basis. If you normally visit for technical content, this may be a bit confusing. But if you know me, you understand that the mind I have never lets me rest. So here’s some of what I would term 1/3 “prose poetry”, 1/3 diary, 1/3 rant – Imagine this running through your head all day every day.

Every morning when the alarm goes off and I roll out of bed and step on the dog… Why does he insist on sleeping there when every morning he yelps as my feet hit his warm fur… there’s a choice that has to be made, to get out of bed, to keep moving forward. The darkness of the room, of the world beyond the shades makes me long to crawl back into the green cotton with the Martha Stewart tag and escape back to my dreams where I can control the choices, the paths to take. In dreams I can stop myself from falling, I can fly away into the sky. I am free.

But every morning I follow the path at my feet and try to forget the points where other paths diverged. Because a life full of indecision is actually better than a life of regret. Yet you only get once chance, one life. I often wonder if there really is a destiny for each spark inside a woman’s body, a predetermined path. So that all the choices I’ve made are already picked from the moment of conception. And if so why should I waste my time on regret?

But I don’t believe in fate.

Often that regret lives, growing like the weeds that clutter the landscaping in my yard, choking the flowers and old mulch in a profusion of prickers and dandelion fluff. And I want to rip the regret away, suffocate it in the compost pile. I can’t find gloves that fit my tiny hands. Or the real desire to do the work. It’s work, and when I pull out the weeds another hundred have grown. Too much regret, too many weeds, too many choices I wish I’d never made, too many places I wish I’d let my feet wander. The impulsiveness of my nature makes me long for stability, normalcy, to be “just like everyone else”. I need an anchor or I drift along wildly. No matter how hard I chase that dream, when I follow that path I feel so alone. Because I’m not normal and I don’t belong.

That is the hardest thing to face every day. I’m alone in an empty room, alone in a crowded room, alone in bed even with a body beside me. Always feeling on the edge of life, watching people do the normal things. I feel like a voyeur, like the man behind the glass observing the strangeness of the people in the room beyond. I take notes, write about them later. A night in front of the TV doesn’t appeal to me. Why didn’t I think about this before? Why does it bother me? Am I really so different? I’m a hamster in the wheel running round and round. And yet, unlike the hamster I know I’m running foolishly. I can’t step off. How do you step off when so many other people rely on your choices. And they have no recourse if you decide to try to fly. They know what happens when you try to fly. Icarus should have listened after all.

Foolish. Perhaps that’s the word to sum up how I feel. Stupid. Should I not be content? They were my choices, my decisions, my chance to follow the smooth easy path or the one filled with ruts. But it has been better for those close to me. And now I’m in a golden cage where I should be happy, singing of how easy life is, how I am given good food, a nice place to sleep, and a pet on the head from my master when I sing pretty.

I don’t want to sing. Because it’s not enough. I’m greedy, selfish. I want more. I want to be the sun.

I read a book in which a man said he’d be the sun and shine upon those he loves. I don’t want to wait for the sun to shine upon me. What use is the sun if it turns itself off? Just… look at me, notice me, talk to me. And turn the damn TV off.

Too much to ask I know. After all, I spend all this time in front of the screen. Here I talk to people with words when voices can’t navigate the bits. Here people know what I feel … here I am the sun. So I won’t sit in front of the TV with you. If I can be shined upon, I will shine.

And the day is bright and another long walk down my road goes on… and I see a path I might just follow. And it might be hell… or heaven. I don’t know. Maybe I don’t care. At least I won’t be like the dog, chasing my tail. After all, when I catch it what do I do? He bites it and yelps. I’m not that masochistic.

Then again, maybe I am. I like to hurt because I feel alive.

For today I’ll just eye that path and wonder if I have the nerve to be impulsive again.

New Cairo Symbols in 1.8 and 1.6

I’ve been working on a new Cairo extension for PHP (5.2+ only, OOP and functional) that was started for the gsoc

Originally we were only going to support the lastest (1.6), but then the new 1.8 version was released and I started adding support to that as well. Then we noticed that dreadfully slow/out of date RHEL and derivitives still have 1.4 versions of Cairo floating around (yuck). So the extension will support 1.4+ However the cairo docs are incorrect in a couple of places regarding new symbols. After some header diffing here is a complete list for 1.8 and 1.6 (to make life easier for anyone else writing language wrappers)

New Symbols in 1.8


CAIRO_STATUS_FONT_TYPE_MISMATCH
CAIRO_STATUS_USER_FONT_IMMUTABLE
CAIRO_STATUS_USER_FONT_ERROR
CAIRO_STATUS_NEGATIVE_COUNT
CAIRO_STATUS_INVALID_CLUSTERS
CAIRO_STATUS_INVALID_SLANT
CAIRO_STATUS_INVALID_WEIGHT
cairo_glyph_allocate
cairo_glyph_free
CAIRO_HAS_IMAGE_SURFACE
CAIRO_HAS_USER_FONT
cairo_text_cluster_t;
cairo_text_cluster_allocate;
cairo_text_cluster_free;
cairo_text_cluster_flags_t
CAIRO_TEXT_CLUSTER_FLAG_BACKWARD
cairo_show_text_glyphs
CAIRO_FONT_TYPE_USER
cairo_scaled_font_text_to_glyphs
cairo_scaled_font_get_scale_matrix
cairo_toy_font_face_create
cairo_toy_font_face_get_family
cairo_toy_font_face_get_slant
cairo_toy_font_face_get_weight
cairo_user_font_face_create
cairo_user_font_face_set_init_func
cairo_user_font_face_set_render_glyph_func
cairo_user_font_face_set_text_to_glyphs_func
cairo_user_font_face_set_unicode_to_glyph_func
cairo_user_font_face_get_init_func
cairo_user_font_face_get_render_glyph_func
cairo_user_font_face_get_text_to_glyphs_func
cairo_user_font_face_get_unicode_to_glyph_func
cairo_user_scaled_font_init_func_t
cairo_user_scaled_font_render_glyph_func_t
cairo_user_scaled_font_text_to_glyphs_func_t
cairo_user_scaled_font_unicode_to_glyph_func_t
CAIRO_VERSION_STRINGIZE
cairo_surface_get_fallback_resolution
cairo_surface_has_show_text_glyphs

New symbols in 1.6
cairo_win32_printing_surface_create
cairo_win32_font_face_create_for_logfontw_hfont
cairo_quartz_font_face_create_for_cgfont
cairo_quartz_font_face_create_for_atsu_font_id
CAIRO_PS_LEVEL_2
CAIRO_PS_LEVEL_3
cairo_ps_level_t
cairo_ps_surface_restrict_to_level
cairo_ps_get_levels
cairo_ps_level_to_string
cairo_ps_surface_set_eps
cairo_ps_surface_get_eps
CAIRO_STATUS_TEMP_FILE_ERROR
CAIRO_STATUS_INVALID_STRIDE
cairo_path_extents
CAIRO_FONT_TYPE_QUARTZ
cairo_has_current_point
CAIRO_SURFACE_TYPE_WIN32_PRINTING
CAIRO_SURFACE_TYPE_QUARTZ_IMAGE
cairo_surface_copy_page
cairo_surface_show_page
cairo_format_stride_for_width