Source for file File.php

<?php
/* vim: set expandtab tabstop=4 shiftwidth=4: */
// +----------------------------------------------------------------------+
// | Copyright (c) 2002-2003 Brent Cook                                        |
// +----------------------------------------------------------------------+
// | This library is free software; you can redistribute it and/or        |
// | modify it under the terms of the GNU Lesser General Public           |
// | License as published by the Free Software Foundation; either         |
// | version 2.1 of the License, or (at your option) any later version.   |
// |                                                                      |
// | This library is distributed in the hope that it will be useful,      |
// | but WITHOUT ANY WARRANTY; without even the implied warranty of       |
// | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU    |
// | Lesser General Public License for more details.                      |
// |                                                                      |
// | You should have received a copy of the GNU Lesser General Public     |
// | License along with this library; if not, write to the Free Software  |
// | Foundation, Inc., 59 Temple Place, Suite 330,Boston,MA 02111-1307 USA|
// +----------------------------------------------------------------------+
//
// $Id: File.php,v 1.12 2003/01/27 04:31:42 busterb Exp $
 
require_once 'DBA.php';
 
// {{{ constants
/**
 * Location in the index file for a block location
 */
define('DBA_SIMPLE_LOC',0);
 
/**
 * Location in the index file for a block size
 */
define('DBA_SIMPLE_SIZE',1);
 
/**
 * Location in the index file for a block value size
 */
define('DBA_SIMPLE_VSIZE',2);
 
/**
 * Location in the index file for a block key
 */
define('DBA_SIMPLE_KEY',3);
// }}}
 
/**
 * DBA_Driver_File provides a simple, file-based implementation of a
 * DBM-style database. It uses two files, and index and a data file to
 * manage key/value pairs. These two files use the suffixes '.dat' and
 * '.idx'. When a database is opened, only the index file is read. The
 * index file contains pointers to locations within the data file, which
 * are used to retrieve values.
 *
 * The class uses a concept of blocks for data storage. When the first value
 * is inserted, a new block is created by appending to the data file. If that
 * value is deleted, it remains in the data file, but is marked as empty in
 * the index file. A list of available blocks is kept, so when a new value
 * is inserted, its size is compared to the list of available blocks. If one
 * is of sufficient size, it is reused and marked as used in the index file.
 * Blocks can be of any length.
 *
 * In updating the index, lines are simply appended to the file after each
 * operation. So, the index file might have the same block listed multiple time
 * , just in different states. When the database is closed, it rewrites the
 * index file, removing and duplicate entries for a single block. The index
 * reader only uses the last entry for a block from the index file, so if close
 * is not called for some reason, the index file is still in a valid state.
 *
 * The optimize function merely removes duplicated index entries by rewriting
 * the file, the same as close.
 * The sync function calls fflush on the data and index files.
 *
 * @author  Brent Cook
 * @version 1.0
 * @access  public
 * @package DBA
 */
class DBA_Driver_File extends DBA
{
    // {{{ instance variables
    /**
     * Name of the database
     * @access private
     */
    var $_dbName;
 
    /**
     * Handle to data file
     * @access private
     */
    var $_datFP;
 
    /**
     * Handle to index file
     * @access private
     */
    var $_idxFP;
 
    /**
     * Indicates the current ability for read/write operations
     * @access private
     */
    var $_writable;
 
    /**
     * Indicates the current ability for read operations
     * @access private
     */
    var $_readable;
 
    /**
     * Determines if the driver should use an index file
     * @access private
     */
    var $_indexed;
    // }}}
 
    // {{{ DBA_Driver_File($indexed = true)
    /* Constructor
     *
     * @access public
     * @param   string  $driver dba driver to use
     */
    function DBA_Driver_File($indexed = true)
    {
        // call the base constructor
        $this->DBA();
        $this->_indexed = true;
    }
    // }}}
 
    // {{{ open($dbName='', $mode='r', $persistent = false)
    /**
     * Opens a database.
     *
     * @access  public
     * @param   string  $dbName The name of a database
     * @param   string  $mode The mode in which to open a database.
     *                    'r' opens read-only.
     *                    'w' opens read-write.
     *                    'n' creates a new database and opens read-write.
     *                    'c' creates a new database if the database does not
     *                       exist and opens read-write.
     * @param   boolean $persistent Determines whether to open the database
     *                   peristently. Not supported here.
     * @return  object  PEAR_Error on failure
     */
    function open($dbName='', $mode='r', $persistent = false)
    {
        if ($persistent) {
            return $this->raiseError(DBA_ERROR_UNSUP_PERSISTENCE);
        }
 
        if ($dbName == '') {
            return $this->raiseError(DBA_ERROR_NO_DBNAME);
        } else {
            $this->_dbName = $dbName;
            $dat_name = $dbName.'.dat';
            $idx_name = $dbName.'.idx';
        }
 
        switch ($mode) {
            case 'r':
                    // open for reading
                    $file_mode = 'rb';
                    $this->_writable = false;
                    $this->_readable = true;
                    break;
            case 'n':
                    // create a new database
                    $file_mode = 'w+b';
                    $this->_writable = true;
                    $this->_readable = true;
                    break;
            case 'c':
                    // should we create a new database?
                    if (!DBA_Driver_File::db_exists($dbName)) {
                        $file_mode = 'w+b';
                        $this->_writable = true;
                        $this->_readable = true;
                        break;
                    } // otherwise, we just open for writing
            case 'w':
                    $file_mode = 'r+b';
                    $this->_writable = true;
                    $this->_readable = true;
                    break;
            default:
                return $this->raiseError(DBA_ERROR_INVALID_MODE, NULL, NULL,
                    'filemode: '.$mode);
        }
 
        // open the index file
        $this->_idxFP = @fopen($idx_name, $file_mode);
        if ($this->_idxFP === false) {
            $this->_writable = false;
            $this->_readable = false;
            return $this->raiseError(DBA_ERROR_CANNOT_OPEN, NULL, NULL,
                'could not open idx file '.$idx_name);
        }
 
        // open the data file
        $this->_datFP = @fopen($dat_name, $file_mode);
        if ($this->_datFP === false) {
            fclose ($this->_idxFP);
            $this->_writable = false;
            $this->_readable = false;
            return $this->raiseError(DBA_ERROR_CANNOT_OPEN, NULL, NULL,
                'could not open data file '.$dat_name);
        }
 
        // get a shared lock if read-only, otherwise get an exclusive lock
        if ($file_mode == 'r') {
            flock ($this -> _idxFP, LOCK_SH);
            flock ($this -> _datFP, LOCK_SH);
        } else {
            flock ($this -> _idxFP, LOCK_EX);
            flock ($this -> _datFP, LOCK_EX);
        }
 
        // we are writing to a new file, so we do not need to read anything
        if ($file_mode != 'w+') {
            // parse the index file
            $this->_readIdx();
        }
    }
    // }}}
 
    // {{{ close()
    /**
     * Closes an open database.
     *
     * @access  public
     * @return  object  PEAR_Error on failure
     */
    function close()
    {
        if ($this->isOpen())
        {
            if ($this->isWritable())
            {
                $this->_writeIdx();
            }
            $this->_readable = false;
            $this->_writable = false;
            fclose($this->_idxFP);
            fclose($this->_datFP);
        } else {
            return $this->raiseError(DBA_ERROR_NOT_OPEN);
        }
    }
    // }}}
 
    // {{{ reopen($mode)
    /**
     * Reopens an already open database in read-only or write mode.
     * If the database is already in the requested mode, then this function
     * does nothing.
     *
     * @access  public
     * @param   string  $mode 'r' for read-only, 'w' for read/write
     * @return  object  PEAR_Error on failure
     */
    function reopen($mode)
    {
        if ($this->isOpen()) {
            if (($mode == 'r') && $this->isWritable()) {
                // Reopening as read-only
                $this->close();
                return $this->open($this->_dbName, 'r');
            } else {
                if (($mode == 'w') && (!$this -> _writable))
                {
                    // Reopening as read-write
                    $this->close();
                    return $this->open($this->_dbName, 'w');
                }
            }
        } else {
            return $this->raiseError(DBA_ERROR_NOT_OPEN);
        }
    }
    // }}}
 
    // {{{ _DBA_Driver_File()
    /**
     * PEAR emulated destructor calls close on PHP shutdown
     * @access private
     */
    function _DBA_Driver_File()
    {
        $this->close();
    }
    // }}}
 
    // {{{ getName()
    /**
     * Returns the name of the opened database. Assumes database is open
     * @returns string the name of the opened database
     */
    function getName()
    {
        return $this->_dbName;
    }
    // }}}
 
    // {{{ isOpen()
    /**
     * Returns the current open status for the database
     *
     * @access  public
     * @return  boolean true if the database is open, false if it is closed
     */
    function isOpen()
    {
        return($this->_readable || $this->_writable);
    }
    // }}}
 
    // {{{ isReadable()
    /**
     * Returns the current read status for the database
     *
     * @access  public
     * @return  boolean true if the database is readable, false if it is not
     */
    function isReadable()
    {
        return $this->_readable;
    }
    // }}}
 
    // {{{ isWritable()
    /**
     * Returns the current write status for the database
     *
     * @access  public
     * @return  boolean true if the database is writable, false if it is not
     */
     function isWritable()
     {
         return $this->_writable;
     }
    // }}}
 
    // {{{ remove($key)
    /**
     * Removes the value at location $key
     *
     * @access  public
     * @param   string  $key key to remove
     * @return  object  PEAR_Error on failure
     */
    function remove($key)
    {
        if ($this->isWritable()) {
            if (isset($this->_usedBlocks[$key])) {
                $this->_freeUsedBlock($key);
            } else {
                return $this->raiseError(DBA_ERROR_NOT_FOUND, NULL, NULL, 'key: '.$key);
            }
        } else {
            return $this->raiseError(DBA_ERROR_NOT_WRITEABLE);
        }
    }
    // }}}
 
    // {{{ &fetch($key)
    /**
     * Returns the value that is stored at $key.
     *
     * @access  public
     * @param   string $key key to examine
     * @return  mixed  the requested value on success, false on failure
     */
    function &fetch($key)
    {
        if ($this->isReadable()) {
            if (!isset($this->_usedBlocks[$key])) {
                return $this->raiseError(DBA_ERROR_NOT_FOUND, NULL, NULL, 'key: '.$key);
            } else {
                fseek($this->_datFP, $this->_usedBlocks[$key][DBA_SIMPLE_LOC]);
                return fread($this->_datFP,$this->_usedBlocks[$key][DBA_SIMPLE_VSIZE]);
            }
        } else {
            return $this->raiseError(DBA_ERROR_NOT_READABLE);
        }
    }
    // }}}
 
    // {{{ firstkey()
    /**
     * Returns the first key in the database
     *
     * @access  public
     * @return  mixed  string on success, false on failure
     */
    function firstkey()
    {
        if ($this->isReadable() && ($this->size() > 0)) {
            reset($this->_usedBlocks);
            return key($this->_usedBlocks);
        } else {
            return false;
        }
    }
    // }}}
 
    // {{{ nextkey()
    /**
     * Returns the next key in the database, false if there is a problem
     *
     * @access  public
     * @return  mixed  string on success, false on failure
     */
    function nextkey()
    {
        if ($this->isReadable() && ($this->size() > 0)
            && next($this->_usedBlocks)) {
            return key($this->_usedBlocks);
        } else {
            return false;
        }
    }
    // }}}
 
 
    // {{{ getkeys()
    /**
     * Returns all keys in the database
     *
     * @access  public
     * @return  mixed  array
     */
    function getkeys()
    {
        if ($this->isReadable() && ($this->size() > 0)) {
            return array_keys($this->_usedBlocks);
        } else {
            return array();
        }
    }
    // }}}
 
    // {{{ size()
    /**
     * Calculates the size of the database in number of keys
     *
     * @access  public
     * @return  int    number of keys in the database
     */
    function size()
    {
        if (is_array($this->_usedBlocks)) {
            return sizeof($this->_usedBlocks);
        } else {
            return 0;
        }
    }
    // }}}
 
    // {{{ insert($key, $value)
    /**
     * Inserts a new value at $key. Will not overwrite if the key/value pair
     * already exist
     *
     * @access  public
     * @param   string  $key key to insert
     * @param   string  $value value to store
     * @return  object  PEAR_Error on failure
     */
    function insert($key, $value)
    {
        if ($this->exists($key)) {
            return $this->raiseError(DBA_ERROR_ALREADY_EXISTS, NULL, NULL,
                'key: '.$key);
        } else {
            return $this->replace($key, $value);
        }
    }
    // }}}
 
    // {{{ replace($key, $value)
    /**
     * Inserts a new value at key. If the key/value pair
     * already exist, overwrites the value
     *
     * @access  public
     * @param   $key    string the key to insert
     * @param   $val    string the value to store
     * @return  object  PEAR_Error on failure
     */
    function replace($key, $value)
    {
        // is the database in a usable state?
        if ($this->isWritable()) {
            // get how much space we need
            $vsize = strlen($value);
 
            if (!isset($this->_usedBlocks[$key])) {
                // the value is new
                $this->_writeNewBlock($key, $value, $vsize);
 
            } else {
                // the value is not new
                $size = $this->_usedBlocks[$key][DBA_SIMPLE_SIZE];
 
                // is the value smaller or equal in size to its block size
                if ($size >= $vsize) {
                    // move to the block's location in the data file
                    $loc = $this->_usedBlocks[$key][DBA_SIMPLE_LOC];
                    fseek($this->_datFP, $loc);
 
                    // write to the data file
                    fwrite($this->_datFP, str_pad($value, $size), $size);
 
                    // update internal indecies
                    $this->_usedBlocks[$key][DBA_SIMPLE_VSIZE] = $vsize;
                    $this->_writeIdxEntry($loc, $size, $vsize, $key);
 
                // the value is larger than its allocated space
                } else {
                    // free this value's allocated block
                    $this->_freeUsedBlock($key);
 
                    $this->_writeNewBlock($key, $value, $vsize);
                }
            }
        } else {
            return $this->raiseError(DBA_ERROR_NOT_WRITEABLE);
        }
    }
    // }}}
    
    // {{{ _writeNewBlock($key, $value, $vsize)
    /**
     * Allocates a new block of at least $vsize and writes $key=>$val
     * to the database
     *
     * @access  private
     * @param   string $key 
     * @param   string $value 
     * @param   int    $vsize 
     */
    function _writeNewBlock($key, $value, $vsize)
    {
        // is there is a sufficiently sized block free ?
        $loc = $this->_getFreeBlock($vsize);
        if ($loc !== false) {
            // update free block list
            $size = $this->_freeBlocks[$loc];
            unset($this->_freeBlocks[$loc]);
 
            // move to the block's location in the data file
            fseek($this->_datFP, $loc, SEEK_SET);
 
            // write to the data file
            fwrite($this->_datFP, str_pad($value,$size), $size);
 
            $this->_usedBlocks[$key] = array($loc, $size, $vsize);
            $this->_writeIdxEntry($loc, $size, $vsize, $key);
 
        // there is not a sufficiently sized block free
        } else {
            // move to the end of the data file
            fseek($this ->_datFP, 0, SEEK_END);
            $loc = ftell($this->_datFP);
 
            // write to the data file
            $size = $vsize + ceil($vsize / 20); // make size 5% larger
 
            // add a useless "\n" to new values. This makes the data file
            // readable in any text editor. Useful when things go wrong :P
            fwrite($this->_datFP, str_pad($value, $size)."\n", $size+1);
 
            // update internal block lists
            $this->_usedBlocks[$key] = array($loc, $size, $vsize);
            $this->_writeIdxEntry($loc, $size, $vsize, $key);
        }
    }
    // }}}
 
    // {{{ _getFreeBlock($reqsize)
    /**
     * Returns a block location from the free list
     *
     * @access  private
     * @param   int     $reqsize Requested size
     * @returns mixed  location of free block, false if there are no free blocks
     */
    function _getFreeBlock($reqsize)
    {
        // check if we have any blocks to choose from
        if (is_array($this->_freeBlocks)) {
            // iterate through the blocks in blockIndex to find
            // a free block
            foreach ($this->_freeBlocks as $loc=>$size) {
                if ($size >= $reqsize) {
                    return $loc;
                }
            }
        }
        // no blocks available
        return false;
    }
    // }}}
 
    // {{{ _freeUsedBlock($key)
    /**
     * Places a used block on the free list, updates indicies accordingly
     *
     * @access  private
     * @param   string $key 
     * @returns mixed
     */
    function _freeUsedBlock($key)
    {
        $loc = $this->_usedBlocks[$key][DBA_SIMPLE_LOC];
        $size = $this->_usedBlocks[$key][DBA_SIMPLE_SIZE];
        unset($this->_usedBlocks[$key]);
 
        $this->_freeBlocks[$loc] = $size;
        $this->_writeIdxEntry($loc, $size);
    }
    // }}}
 
    // {{{ create($dbName)
    /**
     * Creates a new database file if one does not exist. If it already exists,
     * updates the last-updated timestamp on the database
     *
     * @access  public
     * @param   string  $dbName the database to create
     * @return  object  PEAR_Error on failure
     */
    function create($dbName)
    {
        if (!(@touch($dbName.'.dat') && @touch($dbName.'.idx'))) {
           return $this->raiseError('Could not create database: '.$dbName);
        }
    }
    // }}}
 
    // {{{ db_exists($dbName)
    /**
     * Indicates whether a database with given name exists
     *
     * @access  public
     * @param   string   $dbName the database name to check for existence
     * @return  boolean true if the database exists, false if it doesn't
     */
    function db_exists($dbName)
    {
        return(file_exists($dbName.'.dat') && file_exists($dbName.'.idx'));
    }
    // }}}
 
    // {{{ db_drop($dbName)
    /**
     * Removes a database from existence
     *
     * @access  public
     * @param   string  $dbName the database name to drop
     * @return  object  PEAR_Error on failure
     */
    function db_drop($dbName)
    {
        if (DBA_Driver_File::db_exists($dbName)) {
            if (!unlink($dbName.'.dat') || !unlink($dbName.'.idx')) {
                return $this->raiseError(DBA_ERROR_CANNOT_DROP, NULL, NULL,
                    'dbname: '.$dbName);
            }
        } else {
            return $this->raiseError(DBA_ERROR_NOSUCHDB, NULL, NULL,
                'dbname: '.$dbName);
        }
    }
    // }}}
 
    // {{{ drop($dbName)
    /**
     * Removes the last open database from existence
     *
     * @access  public
     * @return  object  PEAR_Error on failure
     */
    function drop()
    {
        $this->close();
        return $this->db_drop($this->_dbName);
    }
    // }}}
 
    // {{{ exists($key)
    /**
     * Check whether key exists
     *
     * @access  public
     * @param   string   $key 
     * @return  boolean true if the key exists, false if it doesn't
     */
    function exists($key)
    {
        return($this->isOpen() && isset($this->_usedBlocks[$key]));
    }
    // }}}
 
    // {{{ sync()
    /**
     * Synchronizes an open database to disk
     * @access  public
     */
    function sync()
    {
        if ($this->isWritable()) {
            fflush($this->_datFP);
            fflush($this->_idxFP);
        }
    }
    // }}}
 
    // {{{ optimize()
    /**
     * Optimizes an open database
     * @access  public
     */
    function optimize()
    {
        if ($this->isWritable()) {
            $this->_writeIdx();
        }
    }
    // }}}
 
    // {{{ _readIdx()
    /**
     * Reads the entries in an index file
     * Assumes that $this->_idxFP is valid and readable
     * @access private
     */
    function _readIdx()
    {
        // clear out old data if a previous database was opened
        $this->_usedBlocks = array();
        $this->_freeBlocks = array();
        $usedBlocks = array(); // temporary used index
        $key = '';            // reset key
 
        while (fscanf($this->_idxFP, '%u|%u|%u|%s', $loc, $size, $vsize, $key))
        {
            // is this an free block?
            if ($key == '') {
                // check if this block had been previously marked as used
                if (isset($usedBlocks[$loc])) {
                    unset($this->_usedBlocks[$usedBlocks[$loc]]);
                    unset($usedBlocks[$loc]);
                }
 
                $this->_freeBlocks[$loc] = $size;
            } else {
                // check if this block had been previously marked as free
                if (isset($this->_freeBlocks[$loc])) {
                    unset($this->_freeBlocks[$loc]);
                }
 
                $this->_usedBlocks[$key] = array($loc, $size, $vsize);
                $usedBlocks[$loc] = $key;
            }
            $key = ''; // reset key for the next iteration
        }
    }
    // }}}
 
    // {{{ _writeIdx()
    /**
     * Rewrites the index file, removing free entries
     * Assumes that $this->_idxFP is valid and writable
     *
     * @access private
     */
    function _writeIdx()
    {
        // move the file pointer to the beginning; ftruncate does not do this
        fseek($this->_idxFP, 0);
 
        // clear the index
        ftruncate($this->_idxFP, 0);
 
        // write the free blocks
        if (isset($this->_freeBlocks)) {
            foreach ($this->_freeBlocks as $loc=>$size) {
                $this->_writeIdxEntry($loc,$size);
            }
        }
 
        // write the used blocks
        if (isset($this->_usedBlocks)) {
            foreach ($this->_usedBlocks as $key=>$block) {
                $this->_writeIdxEntry($block[DBA_SIMPLE_LOC],
                                      $block[DBA_SIMPLE_SIZE],
                                      $block[DBA_SIMPLE_VSIZE], $key);
            }
        }
        fflush($this->_idxFP);
    }
    // }}}
 
    // {{{ _writeIdxEntry($loc, $size, $vsize=NULL, $key=NULL)
    /**
     * Writes a used block entry to an index file
     *
     * @access private
     */
    function _writeIdxEntry($loc, $size, $vsize=NULL, $key=NULL)
    {
        if (is_null($vsize)) {
            // write a free block entry
            fputs($this->_idxFP, "$loc|$size\n");
        } else {
            // write a used block entry
            fputs($this->_idxFP, "$loc|$size|$vsize|$key\n");
        }
    }
    // }}}
}
?>