Home » File Formats » File_Fortune » Manual

Class Summary File_Fortune

Class Summary File_Fortune – File_Fortune

File_Fortune

File_Fortune: Interface to fortune cookie databases

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.

Class Trees for File_Fortune

• File_Fortune
• File_Fortune_Exception

Introduction

Introduction – File_Fortune aims to provide a simple OOP and array-like interface to fortune files. To this end, it implements the SPL interfaces Iterator, Countable, and ArrayAccess. With it, you may easily create and maintain fortune databases, as well as fulfill their primary use case: getting a random fortune.

Authors

• Greg Ward is the original author of the Perl "Fortune.pm", on which work this heavily derives.
• Matthew Weier O'Phinney is the author of this implementation.

Examples

Examples – Common use cases.

Getting a random fortune

<?php
require_once 'File/Fortune.php';

// Grab from a single fortune file:
$fortunes = new File_Fortune('/path/to/fortune/file');
echo $fortunes->getRandom();

// Grab from a directory of fortune files:
$fortunes = new File_Fortune('/path/to/fortune/files/');
echo $fortunes->getRandom();
?>

Get all fortunes

<?php
require_once 'File/Fortune.php';

$fortunes = new File_Fortune('/path/to/fortune/file');
$cached = $fortunes->getAll();

// or all fortunes in all files:
$fortunes->setDirectory('/path/to/fortunes/');
$cached = $fortunes->getAll();
?>

Counting fortunes

<?php
require_once 'File/Fortune.php';

$fortunes = new File_Fortune('/path/to/fortune/file');
$count = count($fortunes);

// or all fortunes in all files:
$fortunes->setDirectory('/path/to/fortunes/');
$count = count($fortunes);
?>

Looping through fortunes

<?php
require_once 'File/Fortune.php';

$fortunes = new File_Fortune('/path/to/fortune/file');
foreach ($fortunes as $fortune) {
    echo $fortune;
}
?>

Note: this will raise exceptions if a directory or multiple files have been set.

Manipulating fortunes

<?php
require_once 'File/Fortune.php';

$fortunes = new File_Fortune('/path/to/fortune/file');

// Delete a fortune:
unset($fortunes[2]); // deletes fortune denoted at index 2

// Update a fortune:
$fortune[2] = "I never liked this fortune"; // update fortune at index 2
?>

Note: this will raise exceptions if a directory or multiple files have been set.

Adding fortunes

<?php
require_once 'File/Fortune.php';

$fortunes = new File_Fortune('/path/to/fortune/file');
$fortunes->add('Shiny, new fortune!');
?>

Note: this will raise exceptions if a directory or multiple files have been set.

Creating a new fortune file

<?php
require_once 'File/Fortune.php';

$newFortunes = array(
    'Fortune 1',
    'Fortune 2',
    'Fortune 3'
);

$fortunes = new File_Fortune('/path/to/fortune/file');
$fortunes->create($newFortunes);
?>

Note: this will raise exceptions if a directory or multiple files have been set.

File_Fortune::__construct

File_Fortune::__construct() – Constructor

Synopsis

File_Fortune File_Fortune::__construct ( string|array $file = null , string $headerFile = null )

Description

Optionally pass a filename or directory name to set the fortune file or directory, and, if passing a fortune file name, optionally pass the name of the header file.

Parameter

string|array $file

Fortune file name, or name of a directory containing fortune files.

If passing an array, array of fortune files names.

string $headerFile

Optional location of binary header file to associate with file passed to $file; see setHeader() for more information.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::add

File_Fortune::add() – Add a new fortune

Synopsis

File_Fortune File_Fortune::add ( string $fortune )

Description

This package is not documented yet.

Parameter

string $fortune

Fortune string to add to fortune file. Fortune will be appended to fortune file.

If multiple files or a directory have been set, you cannot manipulate the fortune list, and this method will raise an exception.

Throws

throws File_Fortune_Exception

Note

This function can not be called statically.

File_Fortune::create

File_Fortune::create() – Create a new fortune file from an array of fortunes

Synopsis

void File_Fortune::create ( $fortunes , string $file = null )

Description

This package is not documented yet.

Parameter

$fortunes

Array of fortunes to use to seed the new fortune file.

string $file

Optional file name to use when creating new fortune file. If not provided, attempts to use the file set via setFile()

Throws

throws File_Fortune_Exception

Note

This function can not be called statically.

File_Fortune::delete

File_Fortune::delete() – Delete an existing fortune

Synopsis

void File_Fortune::delete ( int $index )

Description

delete() may be used to delete a fortune at a given index. However, the easier usage is to simply use unset with array notation:

<?php
unset($fortunes[$index]);

If multiple files or a directory have been set, you cannot manipulate the fortune list, and this method will raise an exception.

Parameter

integer $index

Throws

throws File_Fortune_Exception

Note

This function can not be called statically.

File_Fortune::getAll

File_Fortune::getAll() – Retrieve all fortunes from the current file

Synopsis

array File_Fortune::getAll ( )

Description

getAll() can be used to pull the entire fortune database into an array. Typically this is a bad idea as fortune files are often very large. If you wish to do some processing with each fortune, use the File_Fortune object as an iterator:

<?php
foreach ($fortunes as $fortune) {
    // do something with the fortune
}
?>

Note: you can use getAll() when a directory or multiple files have been set; in such a context, it will return all fortunes in all files.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::getDirectory

File_Fortune::getDirectory() – Retrieve current directory of fortune files

Synopsis

string File_Fortune::getDirectory ( )

Description

getDirectory() returns the currently registered fortune file directory, if any.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::getFile

File_Fortune::getFile() – Retrieve current fortune file name

Synopsis

string File_Fortune::getFile ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::getFiles

File_Fortune::getFiles() – Retrieve list of currently set fortune files

Synopsis

array File_Fortune::getFiles ( )

Description

Retrieves a list of all currently set fortune files, as set either explicitly by setFiles() or implicitly by setDirectory().

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::getHeaderFile

File_Fortune::getHeaderFile() – Retrieve current header file name

Synopsis

string File_Fortune::getHeaderFile ( )

Description

Header files are explained in the setHeaderFile() documentation. This method returns the current header file name, if any.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::getRandom

File_Fortune::getRandom() – Retrieve random fortune

Synopsis

string File_Fortune::getRandom ( )

Description

getRandom() pulls a random fortune. If a fortune file has been explicitly specified, the fortune will be pulled from that file; if a directory has been specified, a random fortune file will first be selected.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::save

File_Fortune::save() – Save changes

Synopsis

void File_Fortune::save ( )

Description

In most cases, it will not be necessary to save changes; __destruct() will save changes when the object goes out of scope. However, if you wish to manually ensure that changes are set, you may call save().

If multiple files or a directory have been set, you cannot manipulate the fortune list, and this method will raise an exception.

Throws

throws File_Fortune_Exception

Note

This function can not be called statically.

File_Fortune::setDirectory

File_Fortune::setDirectory() – Set directory from which to randomly select a fortune file

Synopsis

File_Fortune File_Fortune::setDirectory ( string $directory )

Description

This package is not documented yet.

Parameter

string $directory

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::setFile

File_Fortune::setFile() – Set fortune file

Synopsis

File_Fortune File_Fortune::setFile ( string $file , string $headerFile = null )

Description

setFile() may be used to explicitly set a fortune file to use or create.

Parameter

string $file

string $headerFile

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::setFiles

File_Fortune::setFiles() – Set multiple fortune files

Synopsis

File_Fortune File_Fortune::setFiles ( )

Description

setFiles() may be used to define a list of files from which to pull fortunes. You may pass either a string single argument, an array single argument, or multiple string arguments. As examples:

<?php
// single file:
$fortunes->setFiles('/path/to/fortunefile');

// array of files:
$fortunes->setFiles(array('/path/to/fortunefile', '/another/fortunefile', '/more/fortunes'));

// multiple individual files:
$fortunes->setFiles('/path/to/fortunefile', '/another/fortunefile', '/more/fortunes');
?>

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::setHeaderFile

File_Fortune::setHeaderFile() – Set header file name

Synopsis

File_Fortune File_Fortune::setHeaderFile ( string $headerFile )

Description

Fortune files consist of an ASCII file containing fortunes separated by a delimiter, and a binary header file that contains meta information such as the delimter used, number of fortunes, minimum and maximum length of fortunes contained in the file, and the offsets where each fortune exist in the file.

In most cases, this file is simply the name of the fortune file plus the extension 'dat', and File_Fortune will automatically detect this. If this is not the case, however, you may explicitly set the header file name using this method.

Parameter

string $headerFile

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::update

File_Fortune::update() – Update an existing fortune

Synopsis

void File_Fortune::update ( int $index , string $fortune )

Description

update() may be used to update fortunes. However, the recommended practice is to use array access:

<?php
$fortunes[2] = 'Updated fortunes are fun!';

If multiple files or a directory have been set, you cannot manipulate the fortune list, and this method will raise an exception.

Parameter

integer $index

string $fortune

Throws

throws File_Fortune_Exception

Note

This function can not be called statically.