README

About

This package contains php classes to access, change, copy, delete, move, rename files and directories.

Features

File
- Extending SplFileInfo
- change Privileges
- create file or directories
- copy files and directories
- move files and directories
- delete files and directories (recursive)
- iterate files an directories
FileReader
- read file content
- iterate lines
FileWriter
- write file content
- write lines to file
- remove file content (clear)
- truncat file content
Lock (file lock mechanism)

Compatibility

PHP5.3

Installation

install the latest version via composer

composer require naucon/file

Basic Usage

File

The File class provides methods to access and change file attributes as well as basic file operations like copy, delete, move, rename to a given absolute file or directory path. Since PHP 5.1.2 the Standard PHP Library (SPL) contains a class SplFileInfo that can access file attributes but do not change or perform any basic file operations. The File class inherit from the SplFileInfo class to ensure compatibility.

Create a instance of File class with a absolute file path string.

$examplePath = __DIR__ . '/example.txt';

use Naucon\File\File;
$fileObject = new File($examplePath);

Example:

echo 'File ' . $fileObject->getPathname() . ' do' . (($fileObject->exists()) ? '' : ' not') . ' exist.';
echo '<br/>';
echo 'File is' . (($fileObject->isReadable()) ? '' : ' not') . ' readable.';
echo '<br/>';
echo 'File is' . (($fileObject->isWritable()) ? '' : ' not') . ' writeable.';
echo '<br/>';
echo '<br/>';

echo 'File size: ' . $fileObject->getSize() . ' bytes';
echo '<br/>';
echo 'Access Time: ' . $fileObject->lastAccessed()->format('d.m.Y H:s');
echo '<br/>';
echo 'Change Time: ' . $fileObject->lastChanged()->format('d.m.Y H:s');
echo '<br/>';
echo 'Modification Time: ' . $fileObject->lastModified()->format('d.m.Y H:s');
echo '<br/>';
echo '<br/>';

echo 'File Owner: ' . $fileObject->getOwnerName() . ' (' . $fileObject->getOwner() . ')';
echo '<br/>';
echo 'File Group: ' . $fileObject->getGroupName() . ' (' . $fileObject->getGroup() . ')';
echo '<br/>';
echo 'File permission: ' . $fileObject->getPermission();
echo '<br/>';
echo '<br/>';

create directory

To create a directory, make a instance of File with a absolute path of the new directory and call the method mkdir() or mkdirs().

$newDirectoryPath = __DIR__ . '/tmp';

use Naucon\File\File;
$fileObject = new File($newDirectoryPath);
$fileObject->mkdir();

The method mkdirs() will not only create the given directory instead it create every directories of the path recursive.

$newDirectoryPath = __DIR__ . '/tmp/foo/bar';

use Naucon\File\File;
$fileObject = new File($newDirectoryPath);
$fileObject->mkdirs();

rename

To rename a file or directory, first create a instance of File with the absolute path of the file or directory. Afterward call the method rename() with the new file or directory name (file with extension).

$fileObject->rename('example_foo.txt');

copy

To copy a file or directory, first create a instance of File with the absolute path of the source file or directory. Afterward call the method copy() with a absolute path of the target directory.

$sourcePath = __DIR__ . '/example.txt';
$targetPath = __DIR__ . '/tmp/target/';

use Naucon\File\File;
$fileObject = new File($sourcePath);
$fileObject->copy($targetPath);

move

To move a file or directory, first create a instance of File with the absolute path of the source file or directory. Afterward call the method move() with a absolute path of the target directory.

$sourcePath = __DIR__ . '/example.txt';
$targetPath = __DIR__ . '/tmp/target/move/';

use Naucon\File\File;
$fileObject = new File($sourcePath);
$fileObject->move($targetPath);

delete

To delete a file or directory, first create a instance of File with the absolute path of the file or directory. Afterward call the method delete() or deleteAll().

$sourcePath = __DIR__ . '/tmp/example.txt';

use Naucon\File\File;
$fileObject = new File($sourcePath);
$fileObject->delete();

The method delete() will delete the file or directory. It can only remove empty directories. To delete a directory recursive with its files and sub directories call deleteAll().

$sourcePath = __DIR__ . '/tmp/';

use Naucon\File\File;
$fileObject = new File($sourcePath);
$fileObject->deleteAll();

iterate

The File class provides the methods listAll() and listFiles() to access the files an directories of a given directory. The methods return a instance of FilesystemIterator class (SPL). The instance can be iterated with the foreach() command to retrieve the files and directories.

$path = __DIR__ . '/ExampleDir';

use Naucon\File\File;
$fileObject = new File($path);
$iteratorObject = $fileObject->listAll();

foreach ($iteratorObject as $subFileObject) {
    $subFileObject->getBasename() . '<br/>';
    if ($subFileObject->isDir()) {
        foreach ($subFileObject->listAll() as $subChildFileObject) {
            echo $subChildFileObject->getBasename() . '<br/>';
        }
    }
}

The method listFiles() filters the result to file only. There for it implements the FileFilterType filter class.

$iteratorObject = $fileObject->listFiles();

foreach ($iteratorObject as $subFileObject) {
    echo $subFileObject->getBasename() . '<br/>';
}

To filter the result use a implementation of FilterIterator. The package contains already the filter class FileFilterType to filter after the file type (dir|file.

$iterator = new FileFilterType($fileObject->listAll(), 'dir');
foreach ($iteratorObject as $subFileObject) {
    echo $subFileObject->getBasename() . '<br/>';
}

FileReader

The FileReader class extends the File class to read the content of a given file in different ways.

Since PHP 5.1 the Standard PHP Library (SPL) contains a class SplFileObject that can access and change file content. The FileReader class nowadays use a instance of SplFileObject to perform read operations but do not inherit from it and is also not compatible.

Create a instance of FileReader class with a absolute file path string.

$filePath = __DIR__ . '/example_read.txt';

use Naucon\File\FileReader;
$fileObject = new FileReader($filePath, 'r', true);

Iterate lines

The FileReader class implements the iterater interface. The instance can be iterated with the foreach() command to retrieve lines of file content.

// iterate
foreach($fileObject as $line) {
    echo $line . '<br/>';
}

To navigate between line the following methods are provided isFirst(), firstLine(), isLast(), nextLine(), readLine($pointer)

// while
echo $fileObject->firstLine();
echo '<br/>';
while ( !$fileObject->isLast() ){
    echo $fileObject->nextLine();
    echo '<br/>';
}

echo $fileObject->firstLine();
echo '<br/>';
echo $fileObject->nextLine();
echo '<br/>';
echo $fileObject->nextLine();
echo '<br/>';
echo $fileObject->firstLine();
echo '<br/>';

echo $fileObject->readLine(3);
echo '<br/>';

echo $fileObject->readLine(7);
echo '<br/>';

When calling read() the file content is returned at once.

// read all
echo nl2br($fileObject->read());
echo '<br/>';

When calling readLines() the lines of file content are returned in a array at once.

$lines = $fileObject->readLines();   // return array
foreach ($lines as $line) {
    echo $line . '<br/>';
}

FileWriter

The FileWriter class extends the FileReader class to write content of a given file in different ways.

Since PHP 5.1 the Standard PHP Library (SPL) contains a class SplFileObject that can access and change file content. The FileWriter class nowadays use a instance of SplFileObject to perform read operations but do not inherit from it and is also not compatible.

Create a instance of FileWriter class with a absolute file path string.

$filePath = __DIR__ . '/example_write.txt';

use Naucon\File\FileWriter;
$fileObject = new FileWriter($filePath,'w+');   // file point at the beginning of the file, truncate existing content

Afterwards call write($sting) or writeLine($string) to write a given string to the file.

$string = 'Line01'.PHP_EOL;
$string.= 'Line02'.PHP_EOL;
$string.= 'Line03'.PHP_EOL;
$string.= 'Line04'.PHP_EOL;

$fileObject->write($string);

// iterate file lines
foreach($fileObject as $line) {
    echo $line . '<br/>';
}
echo '<br/>';

//Output:
//Line01
//Line02
//Line03
//Line04

The method writeLine($string) will add a line break a the given string.

$filePath = __DIR__ . '/example_write.txt';
$fileObject = new FileWriter($filePath,'a+');   // file point at the end of the file
$fileObject->writeLine("foo");
$fileObject->writeLine("bar");

foreach($fileObject as $line) {
    echo $line . '<br/>';
}
echo '<br/>';

//Output:
//Line01
//Line02
//Line03
//Line04
//foo
//bar

When calling clear() the file content will be removed

$fileObject->clear();   // remove all content

Lock

The Lock classes is a mechanism to lock processes by writing a lock file at the beginning of the process and deleting it at the end of the process. When the process is executed and the lock file already exists it will aborted. Thereby multiple processes can not be executed at the same time. You may have seen it when opening word document on windows.

First create a instance of LockHandler class with a absolute path where the lock file are written. Afterward create a instance of LockManager class with the LockHandlerinstance. TheLockManager` implements the singleton patter and is there for accessible everywhere.

$lockPath = __DIR__ . '/lock/';

use Naucon\File\LockHandler;
use Naucon\File\LockManager;
LockManager::init(new LockHandler($lockPath));

To perform locking create a instance of Lock with a unique identifier. Then call lock() to write the lock file.

use Naucon\File\Lock;
$lockObject = new Lock('foo');

$lockObject->lock();    // create lock file "~foo.lock"

When calling unlock() the lock file will be removed;

$lockObject->unlock(); // delete lock file "~foo.lock"

To verify if a a lock file exist call isLocked().

if ($lockObject->isLocked()) {
    $lockObject->unlock();  // make sure that file is not locked (deadlock)
}

Example:

$lockObject1 = new Lock('foo');
$lockObject1->lock(); // create lock file "~foo.lock"

$lockObject2 = new Lock('foo');
try {
    $lockObject2->lock(); // throw exception - lock file lock file "~foo.lock" already there
} catch (\Exception $e) {
    echo 'Already Locked<br/>';
}

$lockObject1->unlock(); // delete lock file "~foo.lock"

$lockObject2->lock(); // create lock file "~foo.lock" again
$lockObject2->unlock(); // delete lock file "~foo.lock" again

Example

Start the build-in webserver to see the examples in action:

cd examples
php -S 127.0.0.1:3000

open url in browser

http://127.0.0.1:3000/index.html

License

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

naucon / file

Maintainers

Details