[dev] Wandering Books progress report

[Luciano Ramalho]

If you are wondering what are Wandering Books, please read the updated 
description at the SoC site:
http://code.google.com/soc/horde/appinfo.html?csaid=D26A255891C1C455

PROGRESS REPORT

The first weeks were spent getting up to speed in modern PHP OO 
programming, getting started with Horde and experimenting with the 
application domain (book metadata). Here is what I've done, in summary 
(details follow):

- Learned to use PHPUnit2
- Written high-level documentation for developers
- Implemented a class to represent books
- Implemented methods for handling ISBNs and barcodes
- Implemented scripts to retrieve book metadata from Amazon.com
- Implemented an initial database for Wandering Books
- Configured a complete Horde development environment

DETAILS

Learned to use PHPUnit2
I've started to use PHPUnit2 to test the code, but also to provide a 
programmer-readable low-level documentation of how the methods handle 
different inputs. Chuck has pointed me to the Horde test infrastructure, 
and I will look into that as well.

Written high-level documentation for developers
I believe it's useful to have overview documents explaning what a piece 
of code does, so I've written a little about the Book and ISBN code 
mentioned below, and will continue to do so as I write more code.
Overview: http://cvs.horde.org/incubator/groo/experiments/Book-Notes.txt

Implemented a class to represent books
The Book class constructor accepts a PHP array of book metadata, and a 
Book::fromXML factory returns a book instance from an XML 
representation. I've studied and adopted some of the Dublin Core 
concepts and terms, and particularly the DC Library Application Profile 
was useful, but in the end I did not follow the full DC recommendations 
for representing book metadata as XML to avoid unnecessary complexity. 
You can read more about this decision in the overview text linked above. 
The Book class currently has a few methods with a db_prefix which will 
be refactored once I start using RDO.
Code: http://cvs.horde.org/incubator/groo/experiments/Book.php
Tests: http://cvs.horde.org/incubator/groo/experiments/BookTest.php

Implemented methods for handling ISBNs and barcodes
The ISBN.php module contains static methods for validating and 
converting among ISBN, ISBN-13 and EAN which are numbers used to 
identify books. This is useful becaue the fastest way to catalog a 
personal library is to use a barcode scannner to get the EAN from the 
back covers. However, book databases such as Amazon.com and the Library 
of Congress do not show the EAN, but only the ISBN, so a conversion must 
be made. ISBN-13 is a new format being adopted by the book trade in 2007.
Code: http://cvs.horde.org/incubator/groo/experiments/ISBN.php
Tests: http://cvs.horde.org/incubator/groo/experiments/ISBNTest.php

Implemented scripts to retrieve book metadata from Amazon.com
The Fetch module contains utilities which should be useful for all 
metadata drivers and the command-line interface for invocation from 
cron. The Amazon module contains the actual functions which retrieve 
book XML metadata from Amazon and transorm it in a way suitable for 
creating a Book instance. The Book class is used to do the actual 
INSERTs in the database.
Code: http://cvs.horde.org/incubator/groo/experiments/Fetch.php
http://cvs.horde.org/incubator/groo/experiments/Amazon.php

Implemented an initial database for Wandering Books
It currenly has 5 tables: 3 to represent books and authors, 1 for the 
metadata request queue, and 1 for members. This last one needs to be 
reviewed, but the idea is to use it to relate Wandering Books users to 
Horde users. I need to understand Horde better to see if I really need 
this, but what I call a member is someone who may not yet be a user, but 
a person who has been invited to participate, yet has not created an 
account.
Code: http://cvs.horde.org/incubator/groo/experiments/groo.sql

Configured a complete Horde development environment
As I am new to the platform, I had to start from scratch. Initially I 
tried to use the PHP 5.1.2 packages from the Ubuntu 6.06 distro, but PDO 
was not installed, there was no package available with it and pecl 
refused to work at all (not just for installing PDO). After struggling 
for a couple of days, now I have compiled and set up everything I need 
for Horde development.

NEXT STEPS

- integrate work done so far into Horde
- learn how to use the Horde api and some Horde apps (especially Nag) 
for some functionality
- become confortable enough in Horde to be able to come up with a plan 
and schedule...

Special thanks to Chuck for the support and guidance he has provided so far.

Cheers,

Luciano

-- 
THE ROAD TO WISDOM?
Well, it's plain
and simple to express.
Err and err and err again,
but less and less and less.
— Piet Hein.