Class TM::MyCSV by Thiemo Mättig
Version 2009-09-02

See also data(), each().

The field delimiter for separating values in the CSV file. Default is "," (default CSV style). If not, the class tries to use ";" (European/German CSV style), "\t" (tabulator separated values), "\0", "|", "&" (URI encoded/parameter style), ":" (Unix /etc/passwd style) and " " (log file style). Normaly you don't have to touch this variable. Simply choose your delimiter when creating your initial CSV file.

First have to be "id".

See also add_field(), insert().

Reads a table into a new MyCSV object. The file name may be entered with or without the .csv file extension. If the file does not exist it will be created when calling write(). Set length to the maximum number of bytes per row you expect (as you did in fgetcsv()). Default is 10000 bytes per line. Setting this to 1000 may speed up the method if you'r sure there is no longer line.

For example, create a file called table.csv with the following content and call the script below.

id,value
3,Example
4,Another value
7,Blue

<?php
require_once("MyCSV.class.php");
$table = new MyCSV("table");
while ($row = $table->each()) {
    echo $row['id'] . " is " . $row['value'] . "<br>";
}
?>

Returns false on failure, e.g. if the field already exists.

See also insert(), drop_field().

This is an alias for num_rows().

Returns false if the row does not exist.

This is an alias for seek(row_number, SEEK_SET).

Deletes a table row specified by the id. Deletes all rows if no id is given.

Returns false on failure, e.g. if field does not exists. Rewinds the internal array pointer to the first element on success.

Remove all columns and all fields too.

Example:

<?php
require_once("MyCSV.class.php");
$table = new MyCSV("people");
$table->insert(array('name' => "Adam", 'age'  => 23));
$table->insert(array('name' => "Bill", 'age'  => 19));
echo "<pre>";
$table->dump();
?>

See also export().

See MyCSV() for an example.

Returns the last data row.

See also reset(), last().

See also write(), dump().

This is an alias for each().

This depends on how's the table sorted and isn't identical to min() in all cases.

See also last(), prev(), reset().

See also row_exists().

See also min(), max(), first(), last(), prev(), next(), rand().

The tables are merged using a foreign key of the left table and the primary key of the right table. This adds temporary columns to the left table (temporary means, they aren't stored using write()). A slightly complex example:

echo "<pre>";
$rightTable = new MyCSV();
$rightTable->insert(array('id' => 7, 'color' => "red"));
$rightTable->insert(array('id' => 8, 'color' => "yellow"));
$rightTable->dump();
echo "\n";
$leftTable = new MyCSV();
$leftTable->insert(array('thing' => "Table", 'color_id' => 7));
$leftTable->insert(array('thing' => "Chair", 'color_id' => 8));
$leftTable->insert(array('thing' => "Lamp", 'color_id' => 7));
$leftTable->dump();
echo "\n";
$leftTable->join($rightTable, "color_id");
while ($row = $leftTable->each()) {
    echo $row['thing'] . " is " . $row['color'] . "\n";
}

This is identical to sort("id DESC") but a bit faster.

This is identical to sort("id") but a bit faster.

This depends on how's the table sorted and isn't identical to max() in all cases.

See also first(), next(), end().

Use limit(2) to fetch the first two rows only when calling each() (or fetch_assoc()). Use limit(2, $id) to fetch the next two rows, where $id is calculated using first() for the first page and using next($id, 2), next($id, 4) and so on for all other pages. Example:

$table = new MyCSV("table");
for ($i = 10; $i < 21; $i++) {
  $table->insert(array('text' => "Text $i"));
}
// Order the table first because limit() depends on this.
$table->sort("text DESC");
// Limit to 5 rows starting from a specific id.
$rows = 5;
$id = isset($_REQUEST['id']) ? $_REQUEST['id'] : $table->first();
$table->limit($rows, $id);
while ($row = $table->each()) {
  echo "ID $row[id]: $row[text]<br>";
}
// Calculate and display the link targets for paging.
$first = $table->first();
$prev  = $table->prev($id, $rows);
$next  = $table->next($id, $rows);
$last  = $table->prev($table->last(), ($table->count() - 1) % $rows);
if (strcmp($first, $id)) echo "<a href=\"$PHP_SELF?id=$first\">First</a> ";
if ($prev)               echo "<a href=\"$PHP_SELF?id=$prev\">Prev</a> ";
if ($next)               echo "<a href=\"$PHP_SELF?id=$next\">Next</a> ";
if (strcmp($last, $id))  echo "<a href=\"$PHP_SELF?id=$last\">Last</a>";

See also seek().

This is often the same as insert_id() which returns the last inserted ID. But unlike that, max() doesn't depend on a previous call of insert().

Typically, this is 1.

Use offset to get another ID near to the row specified by id. Default is 1 (one forward). Returns false if there is no row at this position.

See also prev(), last().

See also count().

Use offset to get another ID near to the row specified by id. Default is 1 (one backward). Returns false if there is no row at this position.

See also next(), first().

See also ids().

Returns the first data row.

See also end(), each(), first().

See also id_exists().

If whence is left out, seek jumps to a specific ID (default).

whence may be SEEK_SET to set an absolute position counted from the start of the table, SEEK_CUR for a relative position or SEEK_END for an absolute position counted from the end of the table. The behaviour of these options is identical to fseek(). Keep in mind that id represents an offset instead of a row ID in these cases. Example:

$table = new MyCSV("table");
$table->insert(array('id' => 3)); // 1st row
$table->insert(array('id' => 7)); // 2nd row
$table->seek(1, SEEK_SET); // Jump to 2nd row
$row = $table->fetch_assoc();
echo $row['id']; // Output: 7
$table->seek(7); // Jump to 2nd row

See also limit().

Sorting order flags:

• ASC or SORT_ASC - Sort in ascending order (default).
• DESC or SORT_DESC - Sort in descending order.

• SORT_REGULAR - Compare items normally (default).
• SORT_NUMERIC - Compare items numerically.
• SORT_STRING - Compare items as strings.
• SORT_LOCALE_STRING - Compare items as strings, based on the current locale. Don't forget to use setlocale() before.
• SORT_NAT - Compare items using a "natural order" algorithm.
• SORT_TIME - Compare items as date and time values. This uses strtotime() to convert the strings from the CSV file (everything in a CSV file is a string) into timestamps and compares the timestamps.

setlocale(LC_ALL, "de_DE@euro", "de_DE", "deu_deu");
$table->sort("a, b DESC");
$table->sort("a b DESC"); // Same as above
$table->sort("a", "b", SORT_DESC); // Same as above
$table->sort("a SORT_LOCALE_STRING SORT_NULL b SORT_NULL");
$table->sort("a SORT_NAT, b SORT_NAT, c");

The path returned can be used in MyCSV() without any change. Directories are not removed from the string, if present.

Examples:

$table->update(array(...), 3);
$table->update(array('id' => 3, ...));
$table->update(array('id' => 7, ...), 3); // Moves ID 3 to ID 7

write() closes the file when done.

The files created are binary-safe and compatible with any external spread sheet software (e.g. Excel) with a few exceptions:

• NUL bytes (#0) are replaced with a backslash followed by a DEL character (#127). That's because older PHP versions aren't able to process CSV files containing NUL bytes.
• Double quotes at the beginning and end of a value are replaced with a backslash followed by a left double quote (#147). That's because newer (!) PHP versions strip such quotes.
• Backslashes in front of a NUL, DEL, double quote, left double quote, other backslash or end of string are replaced with two backslashes.