PHP, Web and Mobile development

FlatFileDB : a PHP Library for Flat File DB

FlatFileDB is a PHP library that implements a Flat File database API, with cache, expecially designed to be used for a CMS application project.

Its available on github at and is a component of the new FRAD php framework.


I’ve read many posts about the 2014 becoming the year were people will start abandoning WordPress and other tools that uses SQL database towards flat file CMS.

There are already a lot of flat file CMS available around, like Pico, Kirby or Get Simple, but almost all of them fails at implementing a flat file API.

Some of them have a custom internal storage, while someother have developed some little crappy internal library.

My goal is to have a simple, fast, lightweight and portable library accessible also from Perl and Shell.

Many flat file CMS, indeed, does not implement locking of the data and also they use PHP’s serialize() making the data not portable or proprietary.


Instead of reinventing the wheel i decided to test a few PHP Flat File solution already present. After a few testing i comed out that using the PHP “DBA” extensions with the QDBM driver is the best choice. For more information about QDBM you can look at

QDBM provide locking and it can be accessed from Perl and Shell.

Bash/Shell access its possibile installing the debian package qdbm-util and using the dpmgr command line tool.

Or, you can develop a command line tool in PHP, Python, Perl, or in whatever language you wants that supports QDBM.

Example of accessing the DB from Bash:

# dpmgr list cms.qdbm
agx 1402755350
euro "\u20ac"
html "&<!\u00f9\u00a7> \t\r\nciao!"
array {"io":"miao"}
null null
false false
object {"uno":1,"due":2}

You can notice that all the values are stored as JSON.

From Bash you can use JQ to decode and use it. JQ homepage is at


Those are the main features of the PHP library:

  • uses fast PHP DBA module that is already compiled within PHP
  • locking at table level
  • cache: the library has a little caching system on top of it
  • portable, usable from shell scripts also
  • can store almost anything: strings, array, objectes, everything that JSON accepts;

Some Examples

For more usage and examples please goes to

Opening the DB:

$cms = FlatFile::open('db/cms.qdbm');

Write a Post:

/* Create an Object */
$post = new stdClass;
$post->title='my title';
$post->body='<p>my content</p>';
$post->last_modified_time = time();
$post->tags = array('featured','gallery');

if (!$post) die('Save failed');

Get a Post:

$post = $cms->get($post_id);
if (!$post) die('Post not found');

Check if Key exists:

if ($cms->is_valid('manteinance_mode')) die('Website is under manteinance');

Delete a key:


Get all data: