Flatfile Tutorial

Introduction

The Flatfile package is a small but very poweful set of classes for database like access to text "flat files". It provides equivalents to many of the common SQL commands.

Below is an extended example of how to use Flatfile and the related classes. The example is a table that holds 'posts' (such as a message on a message board), each with an ID, the title, the date, the author and the text of the post.

Setup

First we will set up some constants for the columns (not required, but encouraged!).

define('POSTS_ID',    0);
define('POSTS_TITLE', 1);
define('POSTS_DATE',  2);
define('POSTS_BY',    3);
define('POSTS_TEXT',  4);

Now we need to create the database object and set it up. $datadir is set to the directory where all the tables are stored.

require_once('flatfile.php');
$db = new Flatfile();
$db->datadir = 'data/';

SELECT

To get all rows from a table, use selectAll():

$allrows = $db->selectAll('posts.txt');

To get a single row that is identified by a unique field, use selectUnique()

$aSingleRow = $db->selectUnique('posts.txt', POSTS_ID, '1234');

To do a simple WHERE clause, e.g. get all posts from user 'joe', use selectWhere() and SimpleWhereClause:

$rows = $db->selectWhere('posts.txt', 
                              new SimpleWhereClause(POSTS_BY, '=', 'joe'));

To build a complex criteria that will select rows from user 'joe' made after the first of February 2005 (assuming the date column stores UNIX timestamps):

$compClause = new AndWhereClause();
$compClause->add(new SimpleWhereClause(POSTS_BY, '=', 'joe', STRING_COMPARISON));
$compClause->add(new SimpleWhereClause(POSTS_DATE, '>',  mktime(0, 0, 0, 1, 2, 2005), 
                                       INTEGER_COMPARISON));

You can also build the composite where clause in the constructor:

$compClause = new AndWhereClause(
  new SimpleWhereClause(POSTS_BY, '=', 'joe', STRING_COMPARISON),
  new SimpleWhereClause(POSTS_DATE, '>',  
                        mktime(0, 0, 0, 1, 2, 2005), INTEGER_COMPARISON));

To use the clause, and only return the first 5 posts, sorted in date order descending, do this:

$rows = $db->selectWhere('posts.txt', $compClause, 5, 
                          new OrderBy(POSTS_DATE, DESCENDING, INTEGER_COMPARISON));

(This introduces the $limit and $orderBy parameters of selectWhere)

You can of course use any WhereClause object as part of a CompositeWhereClause and so can have a combination of AND and OR operators.

The 'WhereClause' method can be used with deleteWhere() and updateSetWhere(). Other WhereClause classes are available and if they are not sufficient you can create your own very easily.

You can order on multiple fields by supplying an array of OrderBy objects instead of a single one.

INSERT

To insert a row, use insert() or insertWithAutoId(). The latter will do an auto-increment on a specified field, and will return the newly generated ID.

$newpost[POSTS_ID] = '0'; // dummy
$newpost[POSTS_TITLE] = 'A great post';
$newpost[POSTS_DATE] = time();
$newpost[POSTS_BY]   = 'Me';
$newpost[POSTS_TEXT]  = 'I have discovered a truly wonderful cure to cancer 
                       which this line of code is too small to contain';
$newId = $db->insertWithAutoId('posts.txt', POSTS_ID, $newpost);

UPDATE

To set a number of fields in a table, you can use updateSetWhere(). Suppose user joe has a sex change operation:

$db->updateSetWhere('posts.txt', array(POSTS_BY => 'jane'),
                    new SimpleWhereClause(POSTS_BY, '=', 'joe');

The second parameter can contain any number of fields (not just one as above), or even the complete row.

DELETE

deleteWhere() works in a similar fashion to updateSetWhere() and selectWhere(). 'joe', or should I say 'jane', later decides that she wants to disown all posts she made while still a man:

$db->updateSetWhere('posts.txt', new AndWhereClause(
        new SimpleWhereClause(POSTS_BY, '=', 'jane', STRING_COMPARISON),
        new SimpleWhereClause(POSTS_DATE, '<', mktime(0,0,0,3,4,2004), 
                              INTEGER_COMPARISON));