FileSystem

1. Introduction

The Filesystem-Component provides functionality to access and modify the filesystem. Files ond directories are represented by the classes File and Folder. These classes not only contain data but also processing logic.

2. API for files

2.1. Creating files

To create a new file you need to import the class File into the current script. For thiy you can use the import() function or the (DI)ServiceManager.

PHP code
import('tools::filesystem', 'File'); $file = new File(); $file->create('path/to/my/new/file/filename.txt');

2.2. Open files

Do you want to fill the File-Domain-Object with the data of an existing file simply call the method open().

PHP code
import('tools::filesystem', 'File'); $file = new File(); $file->open('path/to/an/existing/file/filename.php');

2.3. Delete files

Before deleting a file it must be created with create() or opened with open(). Subsequently the file can be removed by calling delete().

PHP code
import('tools::filesystem', 'File'); $file = new File(); $file->create('path/to/my/new/file/filename.html'); $file->delete(); // or $file = new File(); $file->open('path/to/my/existing/file/filename.txt'); $file->delete();

2.4. Copy files

Using the method createCopy() you can create a copy of the currently opened file.
The function expects as its first parameter an instance of the class Folder, which serves as destination of the copy.

PHP code
import('tools::filesystem', 'Folder'); import('tools::filesystem', 'File'); // Creating destination directory $targetFolder = new Folder(); $targetFolder->create('target/folder/of/my/copy'); // or alternatively open an existing directory $targetFolder = new Folder(); $targetFolder->open('target/folder/of/my/copy'); // open file and make a copy of it $file = new File(); $file->open('path/to/an/existing/file/filename.php'); $file->createCopy($targetFolder);

By default the copy will be named as the original file. By passing the 2nd optional parameter the name but can be influenced:

PHP code
// ... $file->createCopy($targetFolder, 'NewNameOfTheCopy.php');

The return value of createCopy() method is a File object that references to the file copy.
In the following example first a new file is created, then it is copied, and at the end the contents of the copy is changed with the writeContent() method.

PHP code
$file = new File(); $file->create('folder/another/myFile.php'); ->createCopy($targetFolder) ->writeContent('Ich bin eine Kopie.');

Is the 3rd and last parameter of the createCopy() method set to false, a Boolean is returned instead of a File object.

2.5. Move files

The moveTo() method allows you to move a file to another directory. It only has one parameter, which defines the target directory (like createCopy()).

PHP code
$targetFolder = new Folder(); $targetFolder->open('my/target/folder'); $file = new File(); $file->open('path/to/my/file.php')->moveTo($targetFolder);

2.6. Rename files

Using the function renameTo() can rename files - returns a Boolean value.

PHP code
$file = new File(); $file->create('path/to/my/file.txt')->renameTo('myNewName.txt');

2.7. Modify the content of a file

For editing the contents of a file three methods are available:

  • writeContent($content) – overwrites the entire contents
  • appendContent($content) – content depends on the current
  • prependContent($content) – content is above the current
PHP code
$file = new File(); $file->open('path/to/my/file.txt') ->writeContent('PHP'); ->prependContent('Adventure ') ->appendContent(' Framework!'); echo $file->getContent(); // Result: Adventure PHP Framework!

2.8. Create Download

With the method makeDownload() can be created a download of the currently opened file:

PHP code
$file = new File(); $file->create('path/to/my/downloadable/file.pdf')->makeDownload();

The name of the file can be changed by using the optional parameter $filename. The following example create a download of the file filesystem.pdf with the content of the file file.pdf.

PHP code
$file = new File(); $file->open('path/to/my/downloadable/file.pdf')->makeDownload('filesystem.pdf');

2.9. Further methods

  • changeOwnerTo($owner)
  • Expect as parameter the new owner of the file.
  • changeModeTo($mode)
  • Change the permissions to the one in $mode (eg, 0755) defined.
  • isWritable()
  • Returns true if the file is writable – otherwise false.
  • isReadable()
  • Returns true if the file is readable – otherwise false.
  • getParentFolder()
  • Returns the parent directory in form of a Folder object.
  • getOwner()
  • Returns the owner of the file.
  • getPermissions()
  • Returns the permission of the file.
  • getName()
  • Returns the filename (eg, filename.txt).
  • getBasePath()
  • Returns the path to the file. For file my/folder/file.txt the function would return my/folder.
  • getPath()
  • Returns the complete path to the file (eg, my/folder/file.txt).
  • getSize()
  • Returns the filesize (in Bytes).
  • getContent()
  • Returns the content of the file.
  • getMimeType()
  • Returns the Mime-Type of the file. This method returns always null if the PHP extension fileinfo is not installed.
  • getExtension()
  • Returns the suffix of the file - for filename.txt txt.

3. API for directories

3.1. Create directory

To create a new directory you need to import the class Folder into the current script. For this you can use the import() function or the (DI)ServiceManager.

PHP code
import('tools::filesystem', 'Folder'); $folder = new Folder(); $folder->create('path/to/my/new/folder');

3.2. Open directory

Do you want to fill the Folder-Domain-Object with the data of an existing directory simply call the method open().

PHP code
import('tools::filesystem', 'Folder'); $folder = new Folder(); $folder->open('path/to/an/existing/folder');

When trying to open a non-existent directory an exception of type FilesystemException is thrown.

3.3. Delete directory

Before deleting a directory it must be created with create() or opened with open(). Subsequently the file can be removed by calling delete().

PHP code
import('tools::filesystem', 'Folder'); $folder = new Folder(); $folder->create('path/to/my/new/folder'); $folder->delete(); // or $folder = new Folder(); $folder->open('path/to/my/existing/folder'); $folder->delete();

The methods create() and open() implements the fluent interface. You can also use the delete method directly to the return value:

PHP code
import('tools::filesystem', 'Folder'); $folder = new Folder(); $folder->create('path/to/my/new/folder')->delete(); // or $folder = new Folder(); $folder->open('path/to/my/existing/folder')->delete();

3.4. Copy directory

Using the method createCopy() you can create a copy of the the currently opened directory.
The function expects as its first parameter an instance of the class Folder, which serves as destination of the copy.

PHP code
import('tools::filesystem', 'Folder'); // Creating destination directory $targetFolder = new Folder(); $targetFolder->create('target/folder/of/my/copy'); // ...or alternatively open an existing directory $targetFolder = new Folder(); $targetFolder->open('target/folder/of/my/copy'); $folder->createCopy($targetFolder);

By default the copy will be named as the original directory. By passing the 2nd optional parameter the name but can be influenced:

PHP code
$folder->open('path/to/my/folder') ->createCopy($targetFolder, 'NewNameForTheCopy');

The return value of createCopy() method is a Folder object that references to the directory copy.
In the following example first a new directory is created, then it is copied, and at the end the copy gets deleted.

PHP code
$targetFolder = new Folder(); $targetFolder->open('target/folder/of/my/copy'); $folder = new Folder(); $folder->create('path/to/my/folder'); ->createCopy($targetFolder) ->delete();

Is the 3rd and last parameter of the createCopy() method set to false, a Boolean is returned instead of a Folder object.

3.5. Move directory

The moveTo() method allows you to move a directory to another directory. It only has one parameter, which defines the target directory (like createCopy()).

PHP code
$targetFolder = new Folder(); $targetFolder->open('my/target/folder'); $folder = new Folder(); $folder->open('path/to/my/folder')->moveTo($targetFolder);

3.6. Rename directory

Using the function renameTo() can rename directories - returns a Boolean value.

PHP code
$folder = new Folder(); $folder->create('path/to/my/folder')->renameTo('myNewFolderName');

3.7. Read content of directory

By using getContent() all directories and files located in the currently opened directory can be read. Return value of this function is an Array filled with File- and Folder objects which represents the content of the directory.

PHP code
$folder = new Folder(); $children = $folder->open('path/to/my/folder')->getContent();

3.8. Further methods

  • changeOwnerTo($owner)
  • Expect as parameter the new owner of the file.
  • changeModeTo($mode)
  • Change the permissions to the one in $mode (eg, 0755) defined.
  • isWritable()
  • Returns true if the directory is writable – otherwise false.
  • isReadable()
  • Returns true if the directory is readable – otherwise false.
  • getParentFolder()
  • Returns the parent directory in form of a Folder object.
  • getOwner()
  • Returns the owner of the directory.
  • getPermissions()
  • Returns the permission of the directory.
  • getName()
  • Returns the name of the directory.
  • getBasePath()
  • Returns the path to the directory. For directory path/to/my/folder the function would return path/to/my.
  • getPath()
  • Returns the complete path to the directory.
  • getSize()
  • Returns the size of the directory (in Bytes).