Docs For Class File_Fortune

[line 62]
File_Fortune_Writer: Write and modify fortune files

Write and modify fortune files in PHP. Inherits from File_Fortune for read and header functions, and adds functions for writing fortune files.

DESCRIPTION

This package provides the ability to write fortune files. It can:

write entire files, given an array of fortunes
add a fortune to an existing file
update an existing fortune in an existing file
delete an existing fortune from an existing file

Whenever files are written, a binary header file is also written. This header file, which by default is named after the fortune file with an extra '.dat' extension, contains information on the number of fortunes in the fortune file and the offset of each fortune within the file. Files written with File_Fortune_Writer will be compatible with all newer versions of fortune and fortune-mod.

Older style fortune files that munged the header and data into a single file are not currently supported, and may never be.

The class inherits its constructor from File_Fortune.

Tutorial: Introduction
Version: Release: 0.9.0

add [line 301]

true add(
string
$fortune)

Add a new fortune

Adds a new fortune to the file. In doing so, it simply appends the file with a new fortune, and then rewrites the header file with new information (new number of strings, new version, possibly new min/max, new offset).

On error, an exception is thrown.

Throws: File_Fortune_Writer_Exception_FileLock if unable to obtain file lock
Throws: File_Fortune_Writer_Exception_FileOpen if unable to open file
Throws: File_Fortune_Exception_BadHeaderFile if unable to open header file, unable to read header file, unable to get header information, or if header information appears corrupted
Throws: File_Fortune_Writer_Exception_FilePos if unable to obtain one or more file offsets while writing file
Throws: File_Fortune_Exception_NoFilename if no filename passed and no filename in object
Throws: File_Fortune_Exception_BadFile if missing file or unable to read from file
Access: public

Parameters:

string $fortune —

[ Top ]

delete [line 407]

true delete(

$num)

Remove a fortune

Removes a fortune from the file, as specified by $num.

Note: Like updating, deleting is an expensive operation. All offsets following the deleted fortune need to be recalculated -- which means that all fortunes need to be loaded in memory first, then re-written to the file. It's probably best to stick to adding fortunes or reading fortunes in most instances.

On error, an exception is thrown.

Throws: File_Fortune_Exception_InvalidCount if an invalid fortune number is passed
Throws: File_Fortune_Exception_NotOpen if the fortune file hasn't yet been opened
Throws: File_Fortune_Exception_HeaderNotRead if header file hasn't been read
Throws: File_Fortune_Exception_NotOpen if fortune file is not open
Throws: File_Fortune_Exception_InvalidID if ID is out of range
Throws: File_Fortune_Writer_Exception_FileLock if unable to obtain file lock
Throws: File_Fortune_Writer_Exception_FilePos if unable to obtain one or more file offsets while writing file
Throws: File_Fortune_Writer_Exception_FileOpen if unable to open file
Throws: File_Fortune_Exception_Offset if unable to seek to fortune offset
Access: public

Parameters:

$num —

[ Top ]

update [line 251]

bool update(
int
$num, string
$fortune)

Update a single fortune in a file

Updates a single fortune in a file, as denoted by $num, with $fortune. If $num is greater than the number of fortunes currently in the file, the fortune is added as the last fortune in the file.

Note: Updating is an expensive operation. All offsets following the updated fortune need to be recalculated -- which means that all fortunes need to be loaded in memory first, then written to the file. It's probably best to stick to adding fortunes or reading fortunes in most instances.

On error, an exception is thrown.

Throws: File_Fortune_Exception_InvalidCount if an invalid fortune number is passed
Throws: File_Fortune_Exception_NotOpen if the fortune file hasn't yet been opened
Throws: File_Fortune_Exception_HeaderNotRead if header file hasn't been read
Throws: File_Fortune_Exception_NotOpen if fortune file is not open
Throws: File_Fortune_Exception_InvalidID if ID is out of range
Throws: File_Fortune_Writer_Exception_FileLock if unable to obtain file lock
Throws: File_Fortune_Writer_Exception_FilePos if unable to obtain one or more file offsets while writing file
Throws: File_Fortune_Writer_Exception_FileOpen if unable to open file
Throws: File_Fortune_Exception_Offset if unable to seek to fortune offset
Access: public

Parameters:

int	`$num`	—
string	`$fortune`	—

[ Top ]

write [line 86]

bool write(
array
$fortunes)

Write a fortune file

Writes a fortune file and the related header file.

The $fortunes array should be an ordinal array of fortune strings.

The file is written to $filename, and the header file to $headerFilename. If $headerFilename remains undefined, the filename $filename.dat is used.

On error, an exception is thrown.

Throws: File_Fortune_Writer_Exception_FileOpen if unable to open file
Throws: File_Fortune_Writer_Exception_FileLock if unable to obtain file lock
Throws: File_Fortune_Writer_Exception_FilePos if unable to obtain one or more file offsets while writing file
Access: public

Parameters:

array $fortunes — Array of fortunes

[ Top ]

_writeHeader [line 177]

true _writeHeader(
)

Write the header file for a fortune file

Writes a fortune header file to $headerFilename, using $version, $numstr, $maxLength, $minLength, $flags, $delim, and $offsets.

If an error occurs, an exception is thrown.

Throws: File_Fortune_Writer_Exception_FileLock if unable to obtain lock on header file
Throws: File_Fortune_Writer_Exception_FileOpen if unable to open header file
Access: protected

[ Top ]

Class: File_Fortune_Writer

Class Overview

Author(s):

Version:

Methods

Inherited Variables

Class: File_Fortune

Inherited Methods

Class: File_Fortune

Class Details

Method Detail

add [line 301]

Parameters:

delete [line 407]

Parameters:

update [line 251]

Parameters:

write [line 86]

Parameters:

_writeHeader [line 177]