NOT implemented - Neatinfo

perchmysteriousData Management

Nov 30, 2012 (4 years and 9 months ago)

218 views

PHP Flatfile package

A light but powerful flat file database package.

Documentation:
http://lukeplant.me.uk/resources/flatfile/docs/li_flatfile.html


PHP 5 and later comes with the SQLite extensions already enabled. If available, SQLite
will usually be a massively superior alternative to a flat file database. PLEASE PLEASE,
do yourselves and your data a favour and
use SQLite

instead!

Seriously,
use SQLite
. You shouldn't have got this far down the page. Why are you still
here? Please go away, unless you really, really
cannot

use SQLite.

Still
here? Well, you have been warned.

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.

This package is comprised of 2 smallis
h PHP files, fully documented. It is very easy to use, and
with the
example based tutorial

in the documentation you should be up and running in a couple
of minutes.

The package is built to be very flexible and extensible, while providing the majority of built
-
in
functionality that would be commonly used. For example, WHERE clause functionality is
provided by a family of WhereClause classes. This means first that the s
electWhere(),
updateSetWhere() and deleteWhere() functions are all equally powerful without having any
duplicate code, and secondly that you can provide your own WhereClause objects (that
implement the WhereClause interface), if the builtin functionality i
s not enough. Also, while
there are 3 builtin comparison methods (used in a number of places), they can in each instance
be replaced with user defined functions in case you need to do things like case insensitve
sorting/comparing.

It is also built to avoid

arbitrary limitations (while maintaining simple syntax for the common
cases). For example, you can have arbitarily complex WHERE clause expressions (by
combining WhereClause objects using things like AndWhereClause), and can specifiy ORDER
BY with any num
ber of fields.

The format of the database files is tab delimited text files, and no database schemas, indexes for
optimisation or any other files are used. (Note that the format means you cannot store tabs or
newline characters directly in a table
--

you w
ill have to escape these yourself before storing
them).

The package is run against a set of tests which are now fairly comprehensive, so you can have
confidence in the quality.

NOT implemented

The package provides no support for relational features like jo
ins. It provides only the most
simplistic attempts to handle concurrency (simple file locks using PHPs flock, only when
writing), which obviously still leaves plenty of room for race conditions or dead locks. Flatfile
makes no attempt to be fast by using i
ndexing or other methods, or to ensure data integrity, or
that data has been written securely to disk etc. These features are omitted by design, since
otherwise you will simply end up with an ad hoc, informally
-
specified, bug
-
ridden, slow
implementation of

half of an RDMS :
-
) If you need those featues, you need something like
PostgreSQL, or for less demanding situations SQLite may suffice.

LICENSE

MIT
(which means in short that it is open
source and free of charge for any use, and without
ANY warranty).

Flatfile Tutorial

Introduction

Example usage of flatfile class

The Flatfile package is a small but very poweful set of classes for database like access to text "flat files". It
provides equi
valents 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.

Example usage of the flatfile class

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

1.

define
(
'POST_ID'
,
0
);

2.

define
(
'POST_TITLE'
,
1
);

3.

define
(
'POST_DATE'
,
2
);

4.

define
(
'POST_BY'
,
3
);

5.

define
(
'POST_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.

1.

require_once
(
'flatfile.php'
);

2.

$db
=
new
Flatfile
();

3.

$db
-
>
datadir
=
'data/'
;

SELECT

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

1.

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

The result will be an array of arrays: $allrows[r][c] will contain the data for row r, column c, w
here r and c
are integers (zero based indexes).

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

1.

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

The result is a single array of the values in the specified row.

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

and
SimpleWhereClause
:

1.

$rows
=
$db
-
>
selectWhere
(
'posts.txt'
,

2.

new
SimpleWhereClause
(
POST_BY
,
'='
,
'joe'
));

The output is an array of arrays, as for
selectAll()
.

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

1.

$compClause
=
new
AndWhereClause
();

2.

$compClause
-
>
add
(
new
SimpleWhereClause
(
POST_BY
,
'='
,
'joe'
,
STRING_COMPARISON
));

3.

$compClause
-
>
add
(
new
SimpleWhereClause
(
POST_DATE
,
'>'
,
mktime
(
0
,
0
,
0
,
1
,
2
,
2005
),

4.

INTEGER_COMPARISON
));

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

1.

$compClause
=
new
AndWhereClause
(

2.

new
SimpleWhereClause
(
POST_BY
,
'='
,
'joe'
,
STRING_COMPARISON
),

3.

new
SimpleWhereClause
(
POST_DATE
,
'>'
,

4.

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:

1.

$rows
=
$db
-
>
selectWhere
(
'posts.txt'
,
$compClause
,
5
,

2.

new
OrderBy
(
POST_DATE
,
DESCENDING
,
INTEGER_COMP
ARISON
));

(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.

Th
e '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 latt
er will do an auto
-
increment on a specified field,
and will return the newly generated ID.

1.

$newpost
[
POST_ID
]
=
'0'
;
// dummy

2.

$newpost
[
POST_TITLE
]
=
'A great post'
;

3.

$newpost
[
POST_DATE
]
=
time
();

4.

$newpost
[
POST_BY
]
=
'Me'
;

5.

$newpost
[
POST_TEXT
]
=
'I have discovered a truly wonderful cure to cancer

6.

which this line of code is too small to contain'
;

7.

$newId
=
$db
-
>
insertWithAutoId
(
'posts.txt'
,
POST_ID
,
$newpost
);

UPDATE

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

1.

$db
-
>
updateSetWhere
(
'posts.txt'
,
array
(
POST_BY
=>
'jane'
),

2.

new
SimpleWhereClause
(
POST_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:

1.

$db
-
>
deleteWhere
(
'posts.txt'
,
new
AndWhereClause
(

2.

new
SimpleWhereClause
(
POST_BY
,
'='
,
'jane'
,
STR
ING_COMPARISON
),

3.

new
SimpleWhereClause
(
POST_DATE
,
'<'
,
mktime
(
0
,
0
,
0
,
3
,
4
,
2004
),

4.

INTEGER_COMPARISON
)));

Custom comparisons

OrderBy

an
d
SimpleWhereClause

use the constants STRING_COMPARISON, NUMERIC_COMPARISON and
INTEGER_COMPARISON to qualify ordering and comparison operations. However, these
constants are in fact
just the names of functions that do the comparison of two variables. You can therefore use your own
function or a builtin PHP function wherever one of these constants can be used. This means, for example,
that you can use
strcasecmp()

to do case insensitive string comparisons:

This will match all posts by joe or JOE or jOe:

1.

$db
-
>
selectWhere
(
'posts.txt'
,

2.

new
SimpleWhereClause
(
POST_BY
,
'='
,
'joe'
,
'strcasecmp'
));

You can of course create your own function, providing it works equivalently to
strmp()