README

A library for file management.

Install

composer

composer require mmdm/sim-file

Or you can simply download zip file from github and extract it, then put file to your project library and use it like other libraries.

Just add line below to autoload files:

require_once 'path_to_library/autoloader.php';

and you are good to go.

How to use

It has three parts to use:

Download
Upload
FileSystem

Download

Basic Usage

// create new Download instance
$download = new Download($path_to_your_file);
$download->download($your_new_name);

// or just use static function
$download = Download::makeDownloadFromPath($path_to_your_file);
$download->download($your_new_name);

Methods

`download(?string $name = null): void`

The download main method. If null passed as $name, the original file name will use as downloadable file name.

`getPath(): ?string`

Get the path of file.

`setName(string $name)`

Set downloadable file name.

`getName(): string`

Get name of downloadable file without extension.

`setExtension(string $extension)`

Set extension of downloadable file.

`getExtension(): ?string`

Get extension of downloadable file.

`getNameWithExtension(): string`

Get name of downloadable file with extension.

`setMimeType(string $mime_type)`

Set mimetype of downloadable file.

`getMimeType(): string`

Get mimetype of downloadable file.

`getSize(): int`

Get size of downloadable file.

`getFormattedSize(): string`

Get size of downloadable file in a human readable format like 2MB or 4KB etc.

`static makeDownloadFromPath(string $path): IDownload`

Make a download instance from a path with static calling.

Upload

To create a upload instance, you should pass a FileUpload instance to Upload constructor.

`FileUpload`

You should pass the key of $_FILES that have uploaded file.

Basic Usage

$fileUpload = new FileUpload($the_key_of_file_in_file_global_variable);

Methods

`setValidations(array $validations)`

You can pass some validations to validate a file while upload method called.

Please refer to Validations section at the very bottom

Note: If unit is not specified, it'll be in bytes.

// new size validation instance
$sizeValidation = new SizeValidation('2MB', '1MB');

`getValidations(): array`

Get array of validations.

`getExtension(): string`

Get extension of uploaded file.

`getSize(): int`

Get size of uploaded file.

`getOriginalName(): string`

Get original name of uploaded file without extension.

`getOriginalNameWithExtension(): string`

Get original name of uploaded file with extension.

`getErrors(): array`

Get errors of uploaded file. Basically it is standard error of uploaded file error and can have other errors too.

Note: Validation errors are not included here.

`addError(string $error)`

Add error to end of errors list.

`setError($key, string $error)`

Set error as a specific error in errors list.

`hasError(): bool`

Check if any error is set.

`errorMessagesTranslate(array $translate)`

Translate standard errors to your locally language.

Basic Usage

// create new Upload instance
$upload = new Upload();
$upload->upload($your_new_destination);

Methods

`upload(string $destination, bool $overwrite = false): bool`

Do upload operation. Default behavior is to not overwrite existing file.

`setName(string $name)`

Set new name of uploaded file.

`getName(): string`

Get new name of uploaded file without extension. Default name is original name unless it change.

`getNameWithExtension(): string`

Get new name of uploaded file with extension.

`getErrors(): array`

Get errors during upload progress including validation errors.

`addError(string $error)`

Add error end of errors list.

`setError(string $key, string $error)`

Set error as a specific error in errors list.

`hasError(): bool`

Check if any error is set.

FileSystem

You can use all methods in both normal instantiable way or use static methods of file system.

These methods works on both files and directories.

Note: Some of these methods that work only with directories, and have a little comment on method documentation that says:

Works only on directories.

Normal instantiable way methods:

`exists(): bool`

Check if specified file is exists.

`isReadable(): bool`

Check if specified file is readable.

`isWritable(): bool`

Check if specified file is writable.

`isFile(): bool`

Check if a path is file

`isDir(): bool`

Check if a path is directory

`isEmpty(): bool`

Check if a directory is empty or not.

Note: If you use file instead of directory, it'll use directory of that file to check.

`get($prefer = null): string`

Get all contents of a file as string

`read($prefer = null): string`

Alias of get method.

`put(string $data, ?int $mode = null)`

Write some string data to a file and return number of bytes that were written to the file, or false on failure.

`write(string $data, ?int $mode = null)`

Alias of write method.

`append(string $data)`

Append some string data to a file and return number of bytes that were written to the file, or false on failure.

`prepend(string $data): bool`

Append some string data to beginning of a file.

`copy(string $new_destination, bool $overwrite = false): bool`

Copy a file to a new destination. Use true as $overwrite parameter if want to overwrite the existence file.

`move(string $new_destination, bool $overwrite = false): bool`

Move a file to a new destination. Use true as $overwrite parameter if want to overwrite the existence file.

`rename(string $new_name, bool $overwrite = false): bool`

Rename a file with new name. Use true as $overwrite parameter if want to overwrite the existence file.

`delete(): bool`

Do delete operation.

Note: It will delete folders recursively.

`deleteFilteredFiles(array $filters = []): bool`

Do delete operation on filtered files.

Note: Only delete files in first level of a directory (This means no recursion)

`deleteAllFilteredFiles(array $filters = []): bool`

Do delete operation on filtered files.

Note: It will delete folders recursively.

`chmod(string $mode): bool`

Change mode of a file.

`chown($user): bool`

Change owner/user of a file.

`chgrp($group): bool`

Change group of a file.

`modificationTime()`

Get modification time of a file.

`touch(?int $time = null, ?int $atime = null): bool`

Change the touch time and access time of a file.

`getExtension($prefer = null): ?string`

Get extension of a file or returns $prefer.

`getMimeType($prefer = null): ?string`

Get mime type of a file or returns $prefer.

`getOwner()`

Get user name of a file or false.

`getOwnerID()`

The user ID of the owner of the file, or false on failure.

`getGroup()`

Get file's group.

`getGroupID()`

Get file's group id.

`getName(): string`

Get file's name.

`getBasename(): string`

Get file's basename.

`getInfo(int $options): array`

Returns file's information. Information can be one or many of following constants (meaning of constant is obvious):

INFO_FILENAME
INFO_BASENAME
INFO_DIRNAME
INFO_SIZE
INFO_EXT
INFO_MIME_TYPE
INFO_IS_READABLE
INFO_IS_WRITABLE
INFO_OWNER
INFO_OWNER_ID
INFO_GROUP
INFO_GROUP_ID

`getSize(): int`

Get size of a file.

Note: Size of directories will be calculated recursively.

`mkdir($mode = self::MODE_DIR_PUBLIC, bool $recursive = true): bool`

Make a directory with a specific mode. To make directory recursively, use true as $recursive parameter.

Note: This method is only for directories.

`getAllFiles(int $type = self::TYPE_FILE | self::TYPE_DIRECTORY): ?RecursiveIteratorIterator`

Will return a RecursiveIteratorIterator to iterate through all files or null on error.

Note: This method is only for directories.

Note: If you want a file's files, it'll use directory of that file as needed directory to get files from.

Note: Please see this link for more information about RecursiveIteratorIterator methods.

An example of usage:

$files = $fileSystem->getAllFiles();
$files->rewind();
while ($files->valid()) {
  /**
  * @var SplFileInfo $file
  */ 
  $file = $files->current();
  
  // do whatever you need with that file
  
  $files->next();
}

`getAllFilesInDepth(int $depth = 0, int $type = self::TYPE_FILE | self::TYPE_DIRECTORY): array`

Will return an array of files of type SplFileInfo from depth of $depth.

Note: This method is only for directories.

Note: If you want a file's files, it'll use directory of that file as needed directory to get files from.

`getAllFilteredFilesInDepth(int $depth = 0, array $filters = []): array`

Will return an array of filtered files of type SplFileInfo from depth of $depth.

Note: This method is only for directories.

Note: If you want a file's files, it'll use directory of that file as needed directory to get files from.

Please refer to Filters section at the very bottom.

`getFiles(int $type = self::TYPE_FILE | self::TYPE_DIRECTORY): array`

Get files of a specific directory as array of type SplFileInfo.

Note: This method is only for directories.

Note: If you want a file's files, it'll use directory of that file as needed directory to get files from.

`getFilteredFiles(array $filters = []): array`

Get filtered files of a specific directory as array of type SplFileInfo.

Please refer to Filters section at the very bottom.

Note: This method is only for directories.

Note: If you want a file's files, it'll use directory of that file as needed directory to get files from.

Static calling way methods:

Only difference of normal way and static way is, you should pass the file path you need to do the operation, to static methods.

`fileExists(string $filename): bool`

See exists in normal way.

`isFileReadable(string $filename): bool`

See isReadable in normal way.

`isFileWritable(string $filename): bool`

See isWritable in normal way.

`isItFile(string $filename): bool`

See isFile in normal way.

`isItDir(string $filename): bool`

See isDir in normal way.

`isDirEmpty(string $dir): bool`

See isEmpty in normal way.

`getFromFile(string $filename, $prefer = null): string`

See get in normal way.

`readFromFile(string $filename, $prefer = null): string`

See read in normal way.

`putToFile(string $filename, string $data, ?int $mode = null)`

See put in normal way.

`writeToFile(string $filename, string $data, ?int $mode = null)`

See write in normal way.

`appendToFile(string $filename, string $data)`

See append in normal way.

`prependToFile(string $filename, string $data): bool`

See prepend in normal way.

`copyFile(string $source, string $new_destination, bool $overwrite = false): bool`

See copy in normal way.

`moveFile(string $source, string $new_destination, bool $overwrite = false): bool`

See move in normal way.

`renameFile(string $old_name, string $new_name, bool $overwrite = false): bool`

See rename in normal way.

`deleteFile(string $filename): bool`

See delete in normal way.

`deleteDirFilteredFiles(string $filename, array $filters = []): bool`

See deleteFilteredFiles in normal way.

`deleteDirAllFilteredFiles(string $filename, array $filters = []): bool`

See deleteAllFilteredFiles in normal way.

`fileChmod(string $filename, string $mode): bool`

See chmod in normal way.

`fileChown(string $filename, $user): bool`

See chown in normal way.

`fileChgrp(string $filename, $group): bool`

See chgrp in normal way.

`fileModificationTime(string $filename)`

See modificationTime in normal way.

`touchFile(string $filename, ?int $time = null, ?int $atime = null): bool`

See touch in normal way.

`getFileExtension(string $filename, $prefer = null): ?string`

See getExtension in normal way.

`getFileMimeType(string $filename, $prefer = null): ?string`

See getMimeType in normal way.

`getFileOwner(string $filename)`

See getOwner in normal way.

`getFileOwnerID(string $filename)`

See getOwnerID in normal way.

`getFileGroup(string $filename)`

See getGroup in normal way.

`getFileGroupID(string $filename)`

See getGroupID in normal way.

`getFileName(string $filename): string`

See getName in normal way.

`getFileBasename(string $filename): string`

See getBasename in normal way.

`getFileInfo(string $filename, int $options): array`

See getInfo in normal way.

`getFileSize(string $filename): int`

See getSize in normal way.

`makeDir(string $dir, $mode = self::MODE_DIR_PUBLIC, bool $recursive = true): bool`

See mkdir in normal way.

`getDirAllFiles(string $dir, int $type = self::TYPE_FILE | self::TYPE_DIRECTORY): ?RecursiveIteratorIterator`

See getAllFiles in normal way.

`getDirAllFilesInDepth(string $dir, int $depth = 0, int $type = self::TYPE_FILE | self::TYPE_DIRECTORY): array`

See getAllFilesInDepth in normal way.

`getDirAllFilteredFilesInDepth(string $dir, int $depth = 0, array $filters = []): array`

See getAllFilteredFilesInDepth in normal way.

`getDirFiles(string $dir, int $type = self::TYPE_FILE | self::TYPE_DIRECTORY): array`

See getFiles in normal way.

`getDirFilteredFiles(string $dir, array $filters = []): array`

See getFilteredFiles in normal way.

How To

How to add more validations

To add your validation, you must extend from AbstractValidator from Abstracts directory and implement following method(s):

`validate(FileUpload $file): bool`

Main validation method that need a file of type FileUpload.

How translate validations error(s)

To translate validations error(s) you need to use setMessage($key, $message) method inside you class after extending AbstractValidator and set your locally message to specific error key.

Key of errors in each class are:

ExtensionValidation

[
  'extension' => 'Specified extension is not allowed!'
]

MimeTypeValidation

[
  'mimetype' => 'Specified mimetype is not allowed!',
]

SizeValidation

[
  'gt_size' => 'File size is greater than allowed file size!',
  'lt_size' => 'File size is less than allowed file size!',
]

How to add more filters

To add your filter, you must implement IFilter interface from Interfaces directory and implement following method(s):

`filter(SplFileInfo $file): bool`

Main filter method that need a file of type SplFileInfo.

Filters

Filter classes are:

ExtensionFilter

// new extension filterer instance
// pass array of allowed extensions without dot
$extFilter = new ExtensionFilter(['png', 'jpg', 'jpeg']);

MimeTypeFilter

// new mimetype filterer instance
// pass array of allowed mimetypes
$mimetypeFilter = new MimeTypeFilter(['image/png', 'image/jpg']);

NameFilter

You should pass a regex according to name of file you need without extension to constructor.

// new name filterer instance
// files that name of them ends with 'es'
$nameFilter = new NameFilter('/es$/i');

SizeFilter

You should pass max size as first parameter and min size as second parameter

Passed parameters can be in following format:

size of file with one of ['B', 'KB', 'MB', 'TB', 'PB']

Note: If unit is not specified, it'll be in bytes.

// new size filterer instance
$sizeFilter = new SizeFilter('2MB', '1MB');

TypeFilter

There are two types: file and directory that can specify through constants below:

IFileSystem::TYPE_FILE
IFileSystem::TYPE_DIRECTORY

// new type filterer instance
$typeFilter = new TypeFilter(IFileSystem::TYPE_FILE | IFileSystem::TYPE_DIRECTORY);

RegexFilter

You should pass a regex to filter a file and it'll apply on name and extension

// new regex filterer instance
$regexFilter = new RegexFilter('/es\.(png|jpe?g|gif)$/i');

Validation

Validations are as below for now:

ExtensionValidation

// new extension validation instance
// pass array of allowed extensions without dot
$extValidation = new ExtensionValidation(['png', 'jpg', 'jpeg']);

MimeTypeValidation

// new mimetype validation instance
// pass array of allowed mimetypes
$mimetypeValidation = new MimeTypeValidation(['image/png', 'image/jpg']);

SizeValidation

You should pass max size as first parameter and min size as second parameter

Passed parameters can be in following format:

size of file with one of ['B', 'KB', 'MB', 'TB', 'PB']

License

Under MIT license.

mmdm / sim-file

Maintainers

Details

README

Install

How to use

Download

Basic Usage

Methods

download(?string $name = null): void

getPath(): ?string

setName(string $name)

getName(): string

setExtension(string $extension)

getExtension(): ?string

getNameWithExtension(): string

setMimeType(string $mime_type)

getMimeType(): string

getSize(): int

getFormattedSize(): string

static makeDownloadFromPath(string $path): IDownload

Upload

FileUpload

Basic Usage

Methods

setValidations(array $validations)

getValidations(): array

getExtension(): string

getSize(): int

getOriginalName(): string

getOriginalNameWithExtension(): string

getErrors(): array

addError(string $error)

setError($key, string $error)

hasError(): bool

errorMessagesTranslate(array $translate)

Basic Usage

Methods

upload(string $destination, bool $overwrite = false): bool

setName(string $name)

getName(): string

getNameWithExtension(): string

getErrors(): array

addError(string $error)

setError(string $key, string $error)

hasError(): bool

FileSystem

Normal instantiable way methods:

exists(): bool

isReadable(): bool

isWritable(): bool

isFile(): bool

isDir(): bool

isEmpty(): bool

get($prefer = null): string

read($prefer = null): string

put(string $data, ?int $mode = null)

write(string $data, ?int $mode = null)

append(string $data)

prepend(string $data): bool

copy(string $new_destination, bool $overwrite = false): bool

move(string $new_destination, bool $overwrite = false): bool

rename(string $new_name, bool $overwrite = false): bool

delete(): bool

deleteFilteredFiles(array $filters = []): bool

deleteAllFilteredFiles(array $filters = []): bool

chmod(string $mode): bool

chown($user): bool

chgrp($group): bool

modificationTime()

touch(?int $time = null, ?int $atime = null): bool

getExtension($prefer = null): ?string

getMimeType($prefer = null): ?string

getOwner()

getOwnerID()

getGroup()

getGroupID()

getName(): string

getBasename(): string

getInfo(int $options): array

`download(?string $name = null): void`

`getPath(): ?string`

`setName(string $name)`

`getName(): string`

`setExtension(string $extension)`

`getExtension(): ?string`

`getNameWithExtension(): string`

`setMimeType(string $mime_type)`

`getMimeType(): string`

`getSize(): int`

`getFormattedSize(): string`

`static makeDownloadFromPath(string $path): IDownload`

`FileUpload`

`setValidations(array $validations)`

`getValidations(): array`

`getExtension(): string`

`getSize(): int`

`getOriginalName(): string`

`getOriginalNameWithExtension(): string`

`getErrors(): array`

`addError(string $error)`

`setError($key, string $error)`

`hasError(): bool`

`errorMessagesTranslate(array $translate)`

`upload(string $destination, bool $overwrite = false): bool`

`setName(string $name)`

`getName(): string`

`getNameWithExtension(): string`

`getErrors(): array`

`addError(string $error)`

`setError(string $key, string $error)`

`hasError(): bool`

`exists(): bool`

`isReadable(): bool`

`isWritable(): bool`

`isFile(): bool`

`isDir(): bool`

`isEmpty(): bool`

`get($prefer = null): string`

`read($prefer = null): string`

`put(string $data, ?int $mode = null)`

`write(string $data, ?int $mode = null)`

`append(string $data)`

`prepend(string $data): bool`

`copy(string $new_destination, bool $overwrite = false): bool`

`move(string $new_destination, bool $overwrite = false): bool`

`rename(string $new_name, bool $overwrite = false): bool`

`delete(): bool`

`deleteFilteredFiles(array $filters = []): bool`

`deleteAllFilteredFiles(array $filters = []): bool`

`chmod(string $mode): bool`

`chown($user): bool`

`chgrp($group): bool`

`modificationTime()`

`touch(?int $time = null, ?int $atime = null): bool`

`getExtension($prefer = null): ?string`

`getMimeType($prefer = null): ?string`

`getOwner()`

`getOwnerID()`

`getGroup()`

`getGroupID()`

`getName(): string`

`getBasename(): string`

`getInfo(int $options): array`

`getSize(): int`

`mkdir($mode = self::MODE_DIR_PUBLIC, bool $recursive = true): bool`

`getAllFiles(int $type = self::TYPE_FILE | self::TYPE_DIRECTORY): ?RecursiveIteratorIterator`

`getAllFilesInDepth(int $depth = 0, int $type = self::TYPE_FILE | self::TYPE_DIRECTORY): array`

`getAllFilteredFilesInDepth(int $depth = 0, array $filters = []): array`

`getFiles(int $type = self::TYPE_FILE | self::TYPE_DIRECTORY): array`

`getFilteredFiles(array $filters = []): array`

`fileExists(string $filename): bool`

`isFileReadable(string $filename): bool`

`isFileWritable(string $filename): bool`

`isItFile(string $filename): bool`

`isItDir(string $filename): bool`

`isDirEmpty(string $dir): bool`

`getFromFile(string $filename, $prefer = null): string`

`readFromFile(string $filename, $prefer = null): string`

`putToFile(string $filename, string $data, ?int $mode = null)`