Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ /** * Simple but powerful flatfile database * See http://lukeplant.me.uk/resources/flatfile/ for documentation and examples * * @tutorial flatfile.pkg * @package flatfile * @license http://www.opensource.org/licenses/mit-license.php */ require_once('flatfile_utils.php'); /** Used to indicate the default comparison should be done, which is STRING_COMPARISON in the absence of a schema, or whatever the schema specifies if one has been added */ define('DEFAULT_COMPARISON', ''); /** Used to indicate a comparison should be done as a string comparison */ define('STRING_COMPARISON', 'strcmp'); /** Used to indicate a comparison should be done as an integer comparison */ define('INTEGER_COMPARISON', 'intcmp'); /** Used to indicate a comparison should be done as a numeric (float) comparison */ define('NUMERIC_COMPARISON', 'numcmp'); /** Indicates ascending order */ define('ASCENDING', 1); /** Indicates descending order */ define('DESCENDING', -1); $comparison_type_for_col_type = array( INT_COL => INTEGER_COMPARISON, DATE_COL => INTEGER_COMPARISON, // assume Unix timestamps STRING_COL => STRING_COMPARISON, FLOAT_COL => NUMERIC_COMPARISON ); function get_comparison_type_for_col_type($coltype) { global $comparison_type_for_col_type; return $comparison_type_for_col_type[$coltype]; } /** * Provides simple but powerful flatfile database storage and retrieval * * Includes equivalents to SELECT * FROM table WHERE..., DELETE WHERE ... * UPDATE and more. All files are stored in the {@link Flatfile::$datadir $datadir} directory, * and table names are just filenames in that directory. Subdirectories * can be used just by specifying a table name that includes the directory name. * @package flatfile */ class Flatfile { /** @access private */ var $tables; /** @access private */ var $schemata; /** The directory to store files in. * @var string */ var $datadir; function Flatfile() { $this->schemata = array(); } /** * Get all rows from a table * @param string $tablename The table to get rows from * @return array The table as an array of rows, where each row is an array of columns */ function selectAll($tablename) { if (!isset($this->tables[$tablename])) $this->loadTable($tablename); return $this->tables[$tablename]; } /** * Selects rows from a table that match the specified criteria * * This simulates the following SQL query: *
* SELECT LIMIT $limit * FROM $tablename * WHERE $whereclause * ORDER BY $orderBy [ASC | DESC] [, $orderBy2 ...] ** * @param string $tablename The table (file) to get the data from * @param object $whereClause Either a {@link WhereClause WhereClause} object to do selection of rows, or NULL to select all * @param mixed $limit Specifies limits for the rows returned: * - use -1 or omitted to return all rows * - use an integer n to return the first n rows * - use a two item array ($startrow, $endrow) to return rows $startrow to $endrow - 1 (zero indexed) * - use a two item array ($startrow, -1) to return rows $startrow to the end (zero indexed) * @param mixed $orderBy Either an {@link OrderBy} object or an array of them, defining the sorting that should be applied (if an array, then the first object in the array is the first key to sort on etc). Use NULL for no sorting. * @return array The matching data, as an array of rows, where each row is an array of columns */ function selectWhere($tablename, $whereClause, $limit = -1, $orderBy = NULL) { if (!isset($this->tables[$tablename])) $this->loadTable($tablename); $table = $this->selectAll($tablename); // Get a copy $schema = $this->getSchema($tablename); if ($orderBy !== NULL) usort($table, $this->getOrderByFunction($orderBy, $schema)); $results = array(); $count = 0; if ($limit == -1) $limit = array(0, -1); else if (!is_array($limit)) $limit = array(0, $limit); foreach ($table as $row) { if ($whereClause === NULL || $whereClause->testRow($row, $schema)) { if ($count >= $limit[0]) $results[] = $row; ++$count; if (($count >= $limit[1]) && ($limit[1] != -1)) break; } } return $results; } /** * Select a row using a unique ID * @param string $tablename The table to get data from * @param string $idField The index of the field containing the ID * @param string $id The ID to search for * @return array The row of the table as an array */ function selectUnique($tablename, $idField, $id) { $result = $this->selectWhere($tablename, new SimpleWhereClause($idField, '=', $id)); if (count($result) > 0) return $result[0]; else return array(); } /* * To correctly write a file, and not overwrite the changes * another process is making, we need to: * - get a lock for writing * - read its contents from disc * - modify the contents in memory * - write the contents * - release lock * Because opening for writing truncates the file, we must get * the lock on a different file. getLock and releaseLock * are helper functions to allow us to do this with little fuss */ /** Get a lock for writing a file * @access private */ function getLock($tablename) { ignore_user_abort(true); $fp = fopen($this->datadir . $tablename . '.lock', 'w'); if (!flock($fp, LOCK_EX)) { // log error? } $this->loadTable($tablename); return $fp; } /** Release a lock * @access private */ function releaseLock($lockfp) { flock($lockfp, LOCK_UN); ignore_user_abort(false); } /** * Inserts a row with an automatically generated ID * * The autogenerated ID will be the highest ID in the column so far plus one. The * supplied row should include all fields required for the table, and the * ID field it contains will just be ignored * * @param string $tablename The table to insert data into * @param int $idField The index of the field which is the ID field * @param array $newRow The new row to add to the table * @return int The newly assigned ID */ function insertWithAutoId($tablename, $idField, $newRow) { $lockfp = $this->getLock($tablename); $rows = $this->selectWhere($tablename, null, 1, new OrderBy($idField, DESCENDING, INTEGER_COMPARISON)); if ($rows) { $newId = $rows[0][$idField] + 1; } else { $newId = 1; } $newRow[$idField] = $newId; $this->tables[$tablename][] = $newRow; $this->writeTable($tablename); $this->releaseLock($lockfp); return $newId; } /** * Inserts a row in a table * * @param string $tablename The table to insert data into * @param array $newRow The new row to add to the table */ function insert($tablename, $newRow) { $lockfp = $this->getLock($tablename); $this->tables[$tablename][] = $newRow; $this->writeTable($tablename); $this->releaseLock($lockfp); } /** * Updates an existing row using a unique ID * * @param string $tablename The table to update * @param int $idField The index of the field which is the ID field * @param array $updatedRow The updated row to add to the table */ function updateRowById($tablename, $idField, $updatedRow) { $this->updateSetWhere($tablename, $updatedRow, new SimpleWhereClause($idField, '=', $updatedRow[$idField])); } /** * Updates fields in a table for rows that match the provided criteria * * $newFields can be a complete row or it can be a sparsely populated * hashtable of values (where the keys are integers which are the column * indexes to update) * * @param string $tablename The table to update * @param array $newFields A hashtable (with integer keys) of fields to update * @param WhereClause $whereClause The criteria or NULL to update all rows */ function updateSetWhere($tablename, $newFields, $whereClause) { $schema = $this->getSchema($tablename); $lockfp = $this->getLock($tablename); for ($i = 0; $i < count($this->tables[$tablename]); ++$i) { if ($whereClause === NULL || $whereClause->testRow($this->tables[$tablename][$i], $schema) ) { foreach ($newFields as $k => $v) { $this->tables[$tablename][$i][$k] = $v; } } } $this->writeTable($tablename); $this->releaseLock($lockfp); $this->loadTable($tablename); } /** * Deletes all rows in a table that match specified criteria * * @param string $tablename The table to alter * @param object $whereClause . {@link WhereClause WhereClause} object that will select * rows to be deleted. All rows are deleted if $whereClause === NULL */ function deleteWhere($tablename, $whereClause) { $schema = $this->getSchema($tablename); $lockfp = $this->getLock($tablename); for ($i = count($this->tables[$tablename]) - 1; $i >= 0; --$i) { if ($whereClause === NULL || $whereClause->testRow($this->tables[$tablename][$i], $schema) ) { unset($this->tables[$tablename][$i]); } } $this->writeTable($tablename); $this->releaseLock($lockfp); $this->loadTable($tablename); // reset array indexes } /** * Delete all rows in a table * * @param string $tablename The table to alter */ function deleteAll($tablename) { $this->deleteWhere($tablename, NULL); } /**#@+ * @access private */ /** Gets a function that can be passed to usort to do the ORDER BY clause * @param mixed $orderBy Either an OrderBy object or an array of them * @return string function name */ function getOrderByFunction($orderBy, $rowSchema = null) { $orderer = new Orderer($orderBy, $rowSchema); return array(&$orderer, 'compare'); } function loadTable($tablename) { $filedata = @file($this->datadir . $tablename); $table = array(); if (is_array($filedata)) { foreach ($filedata as $line) { $line = rtrim($line, "\n"); $table[] = explode("\t", $line); } } $this->tables[$tablename] = $table; } function writeTable($tablename) { $output = ''; foreach ($this->tables[$tablename] as $row) { $keys = array_keys($row); rsort($keys, SORT_NUMERIC); $max = $keys[0]; for ($i = 0; $i <= $max; ++$i) { if ($i > 0) $output .= "\t"; $data = (!isset($row[$i]) ? '' : $row[$i]); $output .= str_replace(array("\t", "\r", "\n"), array(''), $data); } $output .= "\n"; } $fp = @fopen($this->datadir . $tablename, "w"); fwrite($fp, $output, strlen($output)); fclose($fp); } /**#@-*/ /** * Adds a schema definition to the DB for a specified regular expression * * Schemas are optional, and are only used for automatically determining * the comparison types that should be used when sorting and selecting. * * @param string $fileregex A regular expression used to match filenames * @param string $rowSchema An array specifying the column types for data * files that match the regex, using constants defined in flatfile_utils.php */ function addSchema($fileregex, $rowSchema) { array_push($this->schemata, array($fileregex, $rowSchema)); } /** Retrieves the schema for a given filename */ function getSchema($filename) { foreach ($this->schemata as $rowSchemaPair) { $fileregex = $rowSchemaPair[0]; if (preg_match($fileregex, $filename)) { return $rowSchemaPair[1]; } } return null; } } /////////////////////////// UTILITY FUNCTIONS //////////////////////////////////// /** * equivalent of strcmp for comparing integers, used internally for sorting and comparing */ function intcmp($a, $b) { return (int)$a - (int)$b; } /** * equivalent of strcmp for comparing floats, used internally for sorting and comparing */ function numcmp($a, $b) { return (float)$a - (float)$b; } /////////////////////////// WHERE CLAUSE CLASSES //////////////////////////////////// /** * Used to test rows in a database table, like the WHERE clause in an SQL statement. * * @abstract * @package flatfile */ class WhereClause { /** * Tests a table row object * @abstract * @param array $row The row to test * @param array $rowSchema An optional array specifying the schema of the table, using the INT_COL, STRING_COL etc constants * @return bool True if the $row passes the WhereClause * selection criteria, false otherwise */ function testRow($row, $rowSchema = null) { } } /** * Negates a where clause * @package flatfile */ class NotWhere extends WhereClause { /** @access private */ var $clause; /** * Contructs a new NotWhere object * * The constructed WhereClause will return the negation * of the WhereClause object passed in when testing rows. * @param WhereClause $whereclause The WhereClause object to negate */ function NotWhere($whereclause) { $this->clause = $whereclause; } function testRow($row, $rowSchema = null) { return !$this->clause->testRow($row, $rowSchema); } } /** * Implements a single WHERE clause that does simple comparisons of a field * with a value. * * @package flatfile */ class SimpleWhereClause extends WhereClause { /**#@+ * @access private */ var $field; var $operator; var $value; var $compare_type; /**#@-*/ /** * Creates a new {@link WhereClause WhereClause} object that does a comparison * of a field and a value. * * This will be the most commonly used type of WHERE clause. It can do comparisons * of the sort "$tablerow[$field] operator $value" * where 'operator' is one of: