Introduction

File_Fortune provides an OOP interface for reading nix fortune cookie files. File_Fortune_Writer provides methods for writing fortune files.*

Description

The fortune program is a small but important part of *nix culture, and this package aims to provide support for its "fortune cookie" databases to PHP programmers.

For efficiency, all versions of fortune rely on a binary header consisting mainly of offsets into the fortune file proper. Modern versions of fortune keep this header in a separate file, and this is the style adopted by this package; the older style of munging the header and data into one large "compiled" file is not currently supported, and may never be.

Using File_Fortune makes it trivial to write a simplified version of the fortune program:

<?php
    // Trivial 'fortune' program
    $fortuneFilename = $_SERVER['argv'][1];
    $fortuneFile     = new File_Fortune($fortuneFilename);
    $fortune         = $fortuneFile->getRandom();
    echo $fortune;
?>

(A more robust example of this may be found in the File/Fortune/examples/phpFortune script provided with this package.)

The original fortune program provides additional features, such as parallel databases of offensive fortunes, selection of long or short fortunes, dealing with multiple fortune files, etc. These features are not currently available with this package, but may be included in future releases.

Additionally, File_Fortune includes the package File_Fortune_Writer, which makes it trivial to maintain fortune databases. It provides methods for writing new files, as well as for adding, updating, and deleting fortunes from files.

Usage Example 1: Retrieve a random fortune

<?php
    require_once 'File/Fortune.php';
    try {
        $ffile   = new File_Fortune('/path/to/fortune/file');
        $fortune = $ffile->getRandom();
        echo $fortune;
    } catch (File_Fortune_Exception $e) {
        echo "An error occurred: " . $e->getMessage;
    }
?>

Usage Example 1a: Retrieve a random fortune from a list of files

<?php
    require_once 'File/Fortune.php';
    try {
        $fortune   = File_Fortune::getRandomFromSet(
            '/path/to/fortune/file',
            '/path/to/fortune/file2',
            '/path/to/fortune/file3',
        );
        echo $fortune;
    } catch (File_Fortune_Exception $e) {
        echo "An error occurred: " . $e->getMessage;
    }
?>

Usage Example 2: Retrieve a specific fortune

<?php
    require_once 'File/Fortune.php';
    try {
        $ffile   = new File_Fortune('/path/to/fortune/file');
        $fortune = $ffile->getOne(3);
        echo $fortune;
    } catch (File_Fortune_Exception $e) {
        echo "An error occurred: " . $e->getMessage;
    }
?>

Usage Example 3: Write a fortune file from an array of fortunes

<?php
    require_once 'File/Fortune/Writer.php';
    $fortunes = array(
        'A thousand mile journey begins with a single step.',
        'cd /pub ; more beer',
        'We apologize for the inconvenience'
    );
    $ffile   = new File_Fortune_Writer();
    $ffile->filename = '/path/to/fortune/file';
    try {
        $ffile->write($fortunes);
    } catch (File_Fortune_Exception $e) {
        echo "An error occurred: " . $e->getMessage;
    }
?>

Usage Example 4: Add a fortune to an existing file

<?php
    require_once 'File/Fortune/Writer.php';
    try {
        $ffile   = new File_Fortune_Writer('/path/to/fortune/file');
        $ffile->add("There's no place like 127.0.0.1");
    } catch (File_Fortune_Exception $e) {
        echo "An error occurred: " . $e->getMessage;
    }
?>

Usage Example 5: Update a fortune in an existing file

<?php
    require_once 'File/Fortune/Writer.php';
    try {
        $ffile   = new File_Fortune_Writer('/path/to/fortune/file');
        $ffile->update(2, 'mv /can/spam /dev/null');
    } catch (File_Fortune_Exception $e) {
        echo "An error occurred: " . $e->getMessage;
    }
?>

Usage Example 6: Delete a fortune from a file

<?php
    require_once 'File/Fortune/Writer.php';
    try {
        $ffile   = new File_Fortune_Writer('/path/to/fortune/file');
        $ffile->delete(3);
    } catch (File_Fortune_Exception $e) {
        echo "An error occurred: " . $e->getMessage;
    }
?>