PHP Classes

Random Access File: Store data fixed record length data in files

Recommend this page to a friend!
     
  Info   Example   View files Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not enough user ratingsTotal: 208 All time: 8,392 This week: 455Up
Version License PHP version Categories
random-access-file 1.2BSD License5.5PHP 5, Databases, Files and Folders
Description 

Author

This class can store data fixed record length data in files.

It can open files for reading or writing and store records of data of fixed length in them, like those used by database file managers.

The class can also perform other operations such as copy one set of records to another position in the same file, swap or truncate records.

It can handle random access files with fixed-length or variable-length header at the beginning of the file (a variable-length header is a header whose real size is specified in some fixed part of the header itself and therefore must be retrieved when the file is opened).

The class implements array and iterator interfaces, so its objects can be accessed as if they were arrays.

Innovation Award
PHP Programming Innovation award nominee
May 2016
Number 14
Database systems use files that have records of fixed length because it is easy to predict the position of a given record in the file and jump to that position to read or write the record data.

This class can manipulate files with fixed length records in pure PHP code. It performs several types of operations with data records that can be used a simple PHP based file database system.

Manuel Lemos
Picture of Christian Vigh
  Performance   Level  
Name: Christian Vigh <contact>
Classes: 32 packages by
Country: France France
Age: 58
All time rank: 13410 in France France
Week rank: 28 Up2 in France France Up
Innovation award
Innovation award
Nominee: 20x

Winner: 3x

Example

<?php
   
require ( "RandomAccessFile.phpclass" ) ;

   
$random_file = "random.dat" ;

   
// Initialize a file containing the numbers 0 through 100, written with 3 digits
    // and terminated by a newline (each record will occupy 4 bytes)
    // This file will be used as our example case for testing random file access.
   
$fp = fopen ( $random_file, "w" ) ;

    for (
$i = 1 ; $i < 100 ; $i ++ )
       
fwrite ( $fp, sprintf ( "%03d", $i ) . "\n" ) ;

   
fwrite ( $fp, "100" ) ; // Note that the last record will be incomplete (no terminating newline)
   
fclose ( $fp ) ;

   
// Instantiate a random access file and open it in read/write mode.
    // "4" is the record size, "1024" the number of records to be cached, and "\n" the filler character to be
    // used when inserting empty records
   
$rf = new RandomAccessFile ( $random_file, 4, 0, 1024, "\n" ) ;
   
$rf -> Open ( ) ;

   
// Show the number of records that this file holds (should be 100)
   
echo ( "Count = " . count ( $rf ) . "\n" ) ;

   
// Swap 10 records (3d parameter) from record #0 with record #10
    // The file should now have the following values (one per line) :
    // Records 0 to 9 : 011..020
    // Records 10 to 19 : 001..010
    // Records 20 to 99 : 021..099
   
$rf -> Swap ( 0, 10, 10 ) ;

   
// Now copy 20 records from record #0 to record #100 (which is past the end of file)
    // The new contents should have 20 more records, with values in the range 011..020 and 001..010
   
$rf -> Copy ( 0, 100, 20 ) ;

   
// Note that you can use the for() and foreach() constructs to loop through each record
   
foreach ( $rf as $entry )
        echo (
"[" . trim ( $entry ) . "]\n") ;

   
// There is also a small (and dumb) cache that store a few statistics
   
echo ( "Hits : {$rf -> CacheHits}, misses = {$rf -> CacheMisses}\n" ) ;


Details

INTRODUCTION

The RandomAccessFile class is used to manage random access files, ie files having fixed-length records.

You can insert new records, copy one set of records to another destination in the same file, swap or truncate records.

The class also allows you to access file data as if it were an array or an iterator.

See the file example.php for a short example on how to use this class.

HISTORY

VERSION 1.1

  • Added support for fixed-size and variable-size headers at the beginning of a random access file.

VERSION 1.0

  • Initial version

NOTES FOR USERS OF VERSION 1.0

The version 1.0 was not able to process headers in random access files.

In version 1.1, a parameter, $header\_size, has been added as the third parameter of the class constructor. If you have code that already uses this class, then you should modify it to specify an additional value of 0 or false at the third position in the constructor (between the $record\_size and the $cache\_size parameters), if you are also specifying the optional $cache\_size and $filler parameters that appear after $record\_size.

REFERENCE

METHODS

CONSTRUCTOR

$rf	=  new  RandomAccessFile ( $filename, $record_size, $header_size = false, $cache_size = false, $filler = "\0" ) ;

Instantiates a RandomAccessFile object, without opening the specified file.

The parameters are the following :

$filename (string) - Random file name.

$record_size (integer) - Size of a record.

$cache_size (integer) - When not null, indicates how many records from the random file should be cached into memory.

$filler (char) - Character to be used for filling when an incomplete record is written.

$header_size (integer) - Size of an optional fixed header at the start of the file. The default is false, which means no header. If your random access file contains a variable-length header, whose size is specified into some fixed-part of the header itself, then you can also specify a callback function that must have the following signature :

integer function  mycallback ( $fd ) ;

$fd being the file descriptor which will allow you to read the part of the header that contains the real header size, then return this size. Note that the callback will be called whenever the Open() method is called.

CLOSE

$rf -> Close ( ) ;

Closes an already opened random access file.

Nothing happens if the file is already closed. Note that the class destructor systemtically closes the file.

COPY

$rf -> Copy ( $from, $to, $count = 1 ) ;

Copies $count record starting from record from to record to. Record numbers always start from zero.

This method can handle situations where origin and destination overlap.

The method returns the number of records effectively copied. This value can be lower than the specified number of records if :

  • $from + $count - 1 goes past the end of file
  • A read or write error occurred during the copy (consider this as a paranoid check)

Note that :

  • The $to parameter can be specified past the end of file. In this case intermediate records will be created using the filler character.
  • Similarly, at some point during the copy, the current destination record can go past the end of file ; in this case, the new record(s) will be appended to the random file.

ISOPENED

$status		=  $rf -> IsOpened ( ) ;

Checks if the random access file is opened.

ISREADONLY

$status		=  $rf -> IsReadOnly ( ) ;

Checks if the random access file has been opened in read-only mode.

OPEN

$rf -> Open ( $read_only = false ) ;

Opens the random file that has been instantiated.

By default, a random file is opened in write mode. Specify true for the $read_only parameter to open it in read-only mode.

READ

$data	=  $rf -> Read ( $record ) ;

Reads the record whose index has been specified (record numbers start from zero).

Note that this is equivalent to :

$data 	=  $rf [ $record ] ;

Returns false if :

  • The specified record number is past the end of file
  • An unlikely IO error occurred

SWAP

$rf -> Swap ( $from, $to, $count = 1 ) ;

Swaps one or more record contents.

Although this method handles overlapping ranges, the result may seem counter-intuitive. This method should be used on non-overlapping ranges.

The method returns the actual number of records swapped.

TRUNCATE

$rf -> Truncate ( $start_record ) ;

Truncates the random access file up to $start_record - 1.

WRITE

$rf -> Write ( $record, $data ) ;

Writes data in the specified record. Parameters are the following :

$record (integer) - Record number. If the specified record number is past the end of file, then empty records will be added using the filler character.

$data (string) - Record data. If the data is greater than the file's record size, it will be truncated. If smaller, it will be padded using the filler character.

Note that this is equivalent to :

$rf [ $record ] 	=  $data ;

The last record of an existing file can be incomplete (such a situation is allowed for example when you use the RandomAccessFile class for fast access to existing text files).

If the specified record number is past the end of file, then the last incomplete record (if any) will be filled using the filler character and intermediate records initialized with the filler character will be inserted as needed.

PROPERTIES

CacheMisses, CacheHits

Number of cache misses and cache hits since the file was opened.

CacheSize

Number of cached records.

Filename

Underlying random access file name.

Filler

Filler character to be used when expanding incomplete records or inserting new ones.

Header

This property will contain header data, once the Open() method has been called.

HeaderSize

Contains the header size, as specified to the constructor, or returned by the GetHeaderSize() method when implemented by derived classes.

This property can also be set manually before calling the Open() method (but note that the results will be unpredictable if it is set after calling the method).

RecordSize

Random access file record size.


  Files folder image Files (10)  
File Role Description
Accessible without login Plain text file example-with-fixed-header.php Example Example script
Accessible without login Plain text file example-with-variable-header.php Example Example script
Accessible without login Plain text file example.php Example Example script
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file NOTICE Data Auxiliary data
Accessible without login Plain text file random-with-fixed-header.dat Data Auxiliary data
Accessible without login Plain text file random-with-variable-header.dat Data Auxiliary data
Accessible without login Plain text file random.dat Data Auxiliary data
Plain text file RandomAccessFile.phpclass Class Class source
Accessible without login Plain text file README.md Doc. Documentation

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Unique User Downloads Download Rankings  
 100%
Total:208
This week:0
All time:8,392
This week:455Up