Håvard Eide

PHP5.1 introduced a new file object, the SplFileObject, an object that can be used with any streams and implements RecursiveIterator & SeekableIterator for easy access to the stream iteself.

The documentation at php.net has the full API for the class, but to see how it behaves we will look at how this class can help us out with our day to day code.

File Content

To illustrate the simplest example on how the SplFileObject can help you coding more efficient: lets look at a example ( taken from php.net ) that most of you have done when reading the content of a file:

1
2
3
4
5
6

$handle = @fopen("splfile.php", "r");
while (!feof($handle)) {
    $buffer = fgets($handle, 4096);
    echo $buffer;
}
fclose($handle);

This will read the file and output the content, if we take a look at SplFileObject and how we can use that to solve the same task we see a much better piece of code:

1
2
3
4

$file = new SplFileObject( "one.php" );
foreach( $file as $line ) {
    echo $line;
}

Those two pieces of code will output the exact same: one and one line from the source file will be fetched and then printed out. The first code ( as you have been doing all the time ) have no less than 4 different function calls to do the same operation that you can do with the new SplFileObject. the magic with SplFileObject is done with the fact that it implements ArrayIterator, this will treat the input file as a array where each array element is a single line of content. So: we can use any Iterator function on the SplFileObject to achieve the exact same output:

1
2
3
4
5
6
7
8
9

$file = new SplFileObject( "two.php" );
foreach( $file as $line ) {
       echo $line;
}
$file->rewind();
while( $file->valid() ) {
    echo $file->current();
    $file->next();
}

Seek

You can seek in the file with the seek() function:

1
2
3
4

$file = new SplFileObject( "three.php" );
$file->seek( 3 );
//This line will be printed
echo $file->current();

This will open the file, seek to the third line and output //This line will be printed

File information

You can retrieve information regarding the file opened by the object:

1
2

$file = new SplFileObject( "four.php" );
print_r( $file->fstat() );

This will return a array of information:

Array(
    [dev] => 234881039
    [ino] => 11851231
    [mode] => 33188
    [nlink] => 1
    [uid] => 501
    [gid] => 501
    [rdev] => -1
    [size] => 80
    [atime] => 1131225352
    [mtime] => 1131225350
    [ctime] => 1131225350
    [blksize] => -1
    [blocks] => -1
)

Functions

There are a lot of functions available for the SplFileObject, run the following code and you will get a list:

1
2

$file = new SplFileObject( "five.php" );
print_r(get_class_methods($file) );

Array
(
    [0] => __construct
    [1] => getFilename
    [2] => rewind
    [3] => eof
    [4] => valid
    [5] => fgets
    [6] => fgetcsv
    [7] => flock
    [8] => fflush
    [9] => ftell
    [10] => fseek
    [11] => fgetc
    [12] => fpassthru
    [13] => fgetss
    [14] => fscanf
    [15] => fwrite
    [16] => fstat
    [17] => ftruncate
    [18] => current
    [19] => key
    [20] => next
    [21] => setFlags
    [22] => getFlags
    [23] => setMaxLineLen
    [24] => getMaxLineLen
    [25] => hasChildren
    [26] => getChildren
    [27] => seek
    [28] => getCurrentLine
    [29] => __toString
    [30] => getPath
    [31] => getPathname
    [32] => getPerms
    [33] => getInode
    [34] => getSize
    [35] => getOwner
    [36] => getGroup
    [37] => getATime
    [38] => getMTime
    [39] => getCTime
    [40] => getType
    [41] => isWritable
    [42] => isReadable
    [43] => isExecutable
    [44] => isFile
    [45] => isDir
    [46] => isLink
    [47] => getFileInfo
    [48] => getPathInfo
    [49] => openFile
    [50] => setFileClass
    [51] => setInfoClass
)

As you can see: the SplFileObject maps to some of the functions you are used to use and adds some new ones, it is a very good class to use when manipulating files and is also helpful when you want to pass a file from one function to another.