Manual

Common file and directory routines

Introduction

Introduction – Introduction to the File class

Description

File provides an easy interface to PHP's builtin file and directory functions, plus some functions to deal with paths.

Example

Using File

<?php
require_once 'File.php';

$file = "/home/tal/example.txt";

//Echo the whole file
echo File::readAll($file);

//Now use a different approach
$fp = new File();

//Write a single line to the file, using a Macintosh EOL character and
//truncating the file before writing to it
$fp->writeLine($file, "This is a single line", FILE_MODE_WRITE, "\r");

//strip leading and trailing separators from the file path
echo $fp->stripLeadingSeparators($file);
echo $fp->stripTrailingSeparators($file);

?>

Constants

Constants – Predefined Constants

FILE_DEFAULT_READSIZE

The default number of bytes to read from a file.

Used in

FILE_MODE_READ

Read-only mode for opened files

Used in

FILE_MODE_WRITE

Using this mode, opened files will be truncated first and then new data will be written to them.

Used in

FILE_MODE_APPEND

Using this mode, new data will be appended to the end of opened files.

Used in

FILE_LOCK_SHARED

Shared (read) locking mode

Used in

FILE_LOCK_EXCLUSIVE

Exclusive (write) locking mode

Used in

File::buildpath()

File::buildpath() – build a path from given parts array

Synopsis

require_once 'File.php';

mixed File::buildpath ( array $parts , string $separatir = DIRECTORY_SEPARATOR )

Description

Parameter

Return value

Throws

Deprecated

deprecated

Note

This function can be called statically.

See

Example

Using File::write()

<?php
require_once 'File.php';

// deprecated Use File_Util::buildPath() instead.
?>

File::close()

File::close() – closes an open file pointer

Synopsis

require_once 'File.php';

mixed File::close ( string $filename , string $mode )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::close()

<?php
require_once 'File.php';

$e = File::close('test.txt', FILE_MODE_WRITE);

if (PEAR::isError($e)) {
    echo 'Could not close file : ' . $e->getMessage();
} else {
    echo "Successfully closed file test.txt\n";
}
?>

File::getTempDir()

File::getTempDir() – retrieves the system's temporary directory

Synopsis

require_once 'File.php';

string File::gettempdir ( )

Description

Parameter

Return value

Throws

Deprecated

deprecated

Note

This function can be called statically.

See

Example

Using File::getTempDir()

<?php
require_once 'File.php';

// deprecated Use File_Util::tmpDir() instead
?>

File::getTempFile()

File::getTempFile() – returns a path to a temporary file

Synopsis

require_once 'File.php';

string File::getTempFile ( string $dirname = null )

Description

Parameter

Return value

Throws

Deprecated

deprecated

Note

This function can be called statically.

See

Example

Using File::getTempFile()

<?php
require_once 'File.php';

// deprecated Use File_Util::tmpFile() instead
?>

File::isAbsolute()

File::isAbsolute() – checks wether the given path is an absolute path

Synopsis

require_once 'File.php';

bool File::isAbsolute ( string $path )

Description

This method checks whether the supplied path is an absolute path (eg. "/foo/bar" or "C:\foo\bar").

Parameter

string $path - the path the will be checked.

Return value

This method returns TRUE if the path is absolute, FALSE otherwise.

Note

This function can be called statically.

Example

Using File::isAbsolute()

<?php
require_once 'File.php';

if (File::isAbsolute("/usr/local") {
 echo "Path is absolute";
} else {
 echo "Path isn't absolute";
}
?>

This short example will output the string 'Path is absolute'.

File::read()

File::read() – read bytes from a file

Synopsis

require_once 'File.php';

mixed File::read ( string $filename , int $size = FILE_DEFAULT_READSIZE , mixed $lock = false )

Description

File::read() reads a specific amount of bytes from a specified file and returns them to the user.

Parameter

string $filename - the file to read from
int $size - the number of bytes to read from the file (defaults to FILE_DEFAULT_READSIZE)
mixed $lock - lock type to use, FALSE if none

Return value

mixed - this function returns the requested bytes from the file if there were no errors, FALSE if it reached EOF or a PEAR_Error object if an error has occured during reading from file.

Throws

Possible PEAR_Error values
Error Code	Error Value	Meaning	Solution
NULL	"File does not exist: `$filename`"	The file `$filename` does not exist.	Check if the path that is passed to the function is correct.
NULL	"Failed to open file: `$filename`"	There are few possible things that might cause that error, usually it's caused by wrong permissions or bad sectors on the harddisk.	Check the permissions of the file (ls -l {file} on UNIX systems) and change them so the file is readable by PHP, check if the harddisk is working properly and has no bad sectors.

Note

This function can be called statically.

See

Example

Using File::read()

<?php
require_once 'File.php';

//output 40 bytes of file foo.bar
echo File::read("/path/to/foo.bar", 40);
?>

File::readAll()

File::readAll() – reads a complete file

Synopsis

require_once 'File.php';

mixed File::readAll ( string $filename , mixed $lock = false )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::readAll()

<?php
require_once 'File.php';


?>

File::readChar()

File::readChar() – reads a single character from a file

Synopsis

require_once 'File.php';

mixed File::readCharChar ( string $filename , mixed $lock = false )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::readChar()

<?php
require_once 'File.php';

$e = File::readChar('test.txt');

if (PEAR::isError($e)) {
    echo 'Could not read char from file : ' . $e->getMessage();
} else {
    echo $e;
}
?>

File::readLine()

File::readLine() – reads a single line from a file

Synopsis

require_once 'File.php';

mixed File::readLine ( string $filename , mixed $lock = false )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::readLine()

<?php
require_once 'File.php';

$e = File::readLine('test.txt');

if (PEAR::isError($e)) {
    echo 'Could not read from file : ' . $e->getMessage();
} else {
    echo $e;
}
?>

File::rewind()

File::rewind() – rewinds a file pointer

Synopsis

require_once 'File.php';

mixed File::rewind ( string $filename , string $mode )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::rewind()

<?php
require_once 'File.php';

$e = File::rewind('test.txt', FILE_MODE_READ);
 
if (PEAR::isError($e)) {
    echo 'Could not rewind the file : ' . $e->getMessage();
} else {
    echo "File test.txt successfully rewound\n";
}
?>

File::skipRoot()

File::skipRoot() – strips the root directory from a given path

Synopsis

require_once 'File.php';

string File::skipRoot ( string $path )

Description

This method strips the root directory from $path.

Parameter

string $path - the path to be processed.

Return value

If the path is absolute, this method returns the processed path, otherwise, it returns the path untouched.

Note

This function can be called statically.

See

File::isAbsolute()

Example

Using File::skipRoot()

<?php
require_once 'File.php';

echo File::skipRoot("/home/foo/bar");
?>

This example prints out home/foo/bar.

File::stripLeadingSeparators()

File::stripLeadingSeparators() – strip leading separators from a path

Synopsis

require_once 'File.php';

string File::stripLeadingSeparators ( string $path , string $separator = DIRECTORY_SEPARATOR )

Description

This method removes the leading directory separator (like "/" on *nix) from a path name.

Parameter

string $path - the path name where the leading separator should be removed from.
string $separator - optional string that defines the separator. This parameter defaults to the value of the constant DIRECTORY_SEPARATOR that is pre-defined by PHP.

Return value

This methods returns the given path name without a leading directory separator.

Note

This function can be called statically.

Example

Using File::stripLeadingSeparators()

<?php
require_once "File.php";

echo File::stripLeadingSeparators("/home/foo/lala/");
?>

This example will print home/foo/lala/.

File::stripTrailingSeparators()

File::stripTrailingSeparators() – strips trailing separators from a path

Synopsis

require_once 'File.php';

string File:stripTrailingSeparators ( string $path , string $separator = DIRECTORY_SEPARATOR )

Description

This method removes the trailing directory separator (like "/" on *nix) from a path name.

Parameter

string $path - the path name where the trailing separator should be removed from.
string $separator - optional string that defines the separator. This parameter defaults to the value of the constant DIRECTORY_SEPARATOR that is pre-defined by PHP.

Return value

This methods returns the given path name without a trailing directory separator.

Note

This function can be called statically.

Example

Using File:stripTrailingSeparators()

<?php
require_once "File.php";

echo File::stripTrailingSeparators("/home/foo/lala/");
?>

This example will print /home/foo/lala.

File::unlock()

File::unlock() – unlocks a locked file pointer

Synopsis

require_once 'File.php';

mixed File::unlock ( string $filename , string $mode )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::unlock()

<?php
require_once 'File.php';

$e = File::unlock('test.txt');
 
if (PEAR::isError($e)) {
    echo 'Could not unlock the file : ' . $e->getMessage();
} else {
    echo "Successfully unlocked the file test.txt\n";
} 
?>

File::write()

File::write() – writes bytes to a file

Synopsis

require_once 'File.php';

mixed File::write ( string $filename , string $char , string $mode = FILE_MODE_APPEND , mixed $lock = false )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::write()

<?php
require_once 'File.php';

$e = File::write('test.txt', 'this is a test line', FILE_MODE_WRITE);

if (PEAR::isError($e)) {
    echo 'Could not write to file : ' . $e->getMessage();
} else {
    echo "Successfully wrote to file test.txt\n";
}
?>

File::writeChar()

File::writeChar() – writes a single character to a file

Synopsis

require_once 'File.php';

mixed File::writeChar ( string $filename , string $char , string $mode = FILE_MODE_APPEND , mixed $lock = false )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::writeChar()

<?php
require_once 'File.php';

$e = File::write('test.txt', 'a');

if (PEAR::isError($e)) {
    echo 'Could not write to file : ' . $e->getMessage();
} else {
    echo "Successfully wrote to file test.txt\n";
}
?>

File::writeLine()

File::writeLine() – writes a single line to a file

Synopsis

require_once 'File.php';

mixed File::writeLine ( string $filename , string $line , string $mode = FILE_MODE_APPEND , string $crlf = "\n" , mixed $lock = false )

Description

Writes a single line, appending a linefeed by default.

Parameter

$filename - Name of file to write to
$line - Line of data to be written to file
$mode - Write mode, can be either FILE_MODE_WRITE or FILE_MODE_APPEND. Defaults to appending.
$crlf - Carriage return / line feed your system is using. Defaults to LF (\n), but can be set to anything. On Unix, \n is used, on Windows \r\n and Mac OS uses \r.
$lock - If the file shall be locked

Return value

PEAR_Error when an error occured, number of bytes written when all went well (crlf included).

Example

Using File::writeLine()

<?php
require_once 'File.php';

$e = File::writeLine('test.txt', str_repeat("0123456789", 1000));

if (PEAR::isError($e)) {
    echo 'Could not write to file : ' . $e->getMessage();
} else {
    echo "Successfully wrote to file test.txt\n";
}
?>