README

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

fostam / file

Maintainers

Details