naucon / file
This package contains php classes to access, change, copy, delete, move, rename files and directories.
Installs: 20 450
Dependents: 3
Suggesters: 0
Security: 0
Stars: 25
Watchers: 3
Forks: 5
Open Issues: 4
Requires
- php: >=5.3.0
- naucon/utility: ~1.0
Requires (Dev)
- phpunit/phpunit: 4.8.*
This package is auto-updated.
Last update: 2024-09-29 04:20:00 UTC
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. The
LockManager` 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)
Copyright (c) 2015 Sven Sanzenbacher
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.