fostam/file

File is a simple convenience wrapper for PHP functions like fopen(), fgets(). It offers object oriented usage of file functions, and handles errors with exceptions instead of return results and PHP warnings/errors.

Install

The easiest way to install File is by using composer:

$> composer require fostam/file

Usage

Example: print the contents of a file, line by line

<?php

use Fostam\File\File;

$reader = new File($filename, File::MODE_READ);

while ($line = $reader->readLine()) {
    print $line;
}

$reader->close();

Example: write into a file

$writer = new File($filename, File::MODE_WRITE_CREATE_OR_TRUNCATE);
$writer->write('test');
$writer->close();

Example: resumt reading a file from a known position

$reader = new File($filename, File::MODE_READ);

// (read $pos from previous run)

while ($line = $reader->readLine(null, $pos)) {
    // (process $line)
    // (save $pos to resume if interrupted)
}

$reader->close();

Errors

All errors are caught and passed on by throwing an Exception. All thrown Exceptions derive from the Fostam\File\Exception\FileException class.

Reference

Methods

Method	Return value	Description	Equivalent
__construct(string $filename, string $mode)	void	Constructor	-
open()	void	Open the file	fopen()
close(bool $silent = false)	void	Close the file	fclose()
setPos(int $pos)	void	Set the file pointer to position $pos	fseek()
getPos()	int	Get the current file position	ftell()
readLine(?int $maxBytes = null, int $pos = null)	?string	Get the line (up to $maxBytes bytes) at the current position, or $pos	fgets()
readBytes(int $length, int $pos = null)	?string	Get $length bytes from the current position, or $pos	fread()
write(string $data, int $maxBytes = null, int $pos = null)	int	Write (up to $maxBytes bytes from) $data to the current position, or $pos	fputs()
truncate(int $size = 0)	void	Truncate the file to $size bytes	ftruncate()
flush()	void	Write all data to disk	fflush()
lockShared(bool $nonBlocking = false)	void	Lock the file in shared mode	flock()
lockExclusive(bool $nonBlocking = false)	void	Lock the file in exclusive mode	flock()
unlock(bool $nonBlocking = false)	void	Unlock the file	flock()
stat()	void	Get file information	fstat()
isAtEOF()	bool	Returns true if the file pointer is at the end of the file	feof()
getFileHandle(): resource	void	Get the file handle (e.g. to be used with other file functions)	fopen() (return value)

Open File Modes

See the fopen() documentation for a description of modes.

Constant	Mode	Description
MODE_READ	r	Read-only
MODE_READWRITE	r+	Read/Write
MODE_WRITE_CREATE_OR_TRUNCATE	w	Write-only; create file, truncate if existing
MODE_READWRITE_CREATE_OR_TRUNCATE	w+	Read/Write; create file, truncate if existing
MODE_WRITE_APPEND_CREATE	a	Write-only; append; create file if not existing
MODE_READWRITE_APPEND_CREATE	a+	Read/Write; append; create file if not existing
MODE_WRITE_CREATE_NEW	x	Write-only; create file, fail if existing
MODE_READWRITE_CREATE_NEW	x+	Read/Write; create file, fail if existing
MODE_WRITE_CREATE	c	Write-only; create file, don't truncate if existing
MODE_READWRITE_CREATE	c+	Read/Write; create file, don't truncate if existing

Exceptions

• FileException
• OpenFileErrorFileException
• CloseFileErrorFileException
• GetPositionErrorFileException
• SetPositionErrorFileException
• ReadErrorFileException
• WriteErrorFileException
• TruncateErrorFileException
• FlushErrorFileException
• ValueErrorFileException
• LockWouldBlockFileException