File: README

z-base32 encoding/decoding
==========================

The purpose of 32-bit encoding generally is to put 8-bit data into
streams that do not respect case. One typical example is e-mail
addresses.

Difference between base32 and z-base32
======================================

z-base32 is more compact than standard base32, as it does not use pad
characters. (These are in fact unnecessary for well-written
algorithms.) z-base32 also favours characters that are visually
distinct: z-base32 encodings can safely be transcribed over the
telephone, for example. 5 bytes of 8-bit data will produce
8 bytes of z-base32-encoded data.

Contents of this package
========================

There are two subdirectories in this package. One is for PHP version
5.2. It uses the zbase32 class wrapper to encapsulate the data needed for the
encoding and decoding functions. The class has no instance data and
no constructor: it does not make sense to create objects of type zbase32. 

The second is for PHP version 5.3. This uses namespaces rather than a
class wrapper. This is more desirable, because an encoder/decoder is
not a natural software object and does not lend itself to subclassing.
Instead, the encoding/decoding functions are invoked using their
qualified name, e.g. zbase32\encode($data).

Each subdirectory contains a test program to ensure correct operation of the
functions.

If you choose to use the namespace version, you can ignore subdirectory 5.2;
if you prefer not to get entangled with namespaces, ignore subdirectory 5.3.

Using the functions
===================

They are trivially easy to use.

<?php
// encoding using the 5.2 (class) version

require 'zbase32.php';

$str = 'Some data';
$encoded_string = zbase32::encode($str); // get encoded data
echo $encoded_string; // echoes 'kpzs43jyctozeae'

// decoding using the 5.3 (namespace) version

$str = 'jiose3jypfznytmqc7sgn5ur';
$decoded_string = zbase32\decode($str);
echo $decoded_string; // echoes 'Made in England'
?>

Author's rant
=============

Before the advent of namespaces, classes were the principal method of
packaging functionality in PHP, and keeping global objects out of the
global namespace. Excessive use of classes can lead, however, to
a loss of understanding of what classes are for: provision of
encapsulated, extensible functionality.

If it makes no sense to derive a subclass from an object, it makes
sense to ask: "why make this functionality into an object in the first
place?"

The principal absurdity here is the "singleton" class. While the singleton
pattern is valid and useful, there is something inappropriate about using
classes to create an object that is global, unique and un-reusable. Isn't that
what global data and functions are really for?