README

一个用于文件管理的库。

安装

composer

composer require mmdm/sim-file

或者您可以直接从github下载zip文件，解压后将其放置在项目库中，然后像使用其他库一样使用。

只需添加以下行来自动加载文件

require_once 'path_to_library/autoloader.php';

然后您就可以开始了。

如何使用

它有三部分组成

• 下载

• 上传

• 文件系统

下载

基本用法

// 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);

方法

download(?string $name = null): void

下载的主要方法。如果传递了 null 作为 $name，则将使用原始文件名作为可下载文件的名称。

getPath(): ?string

获取文件的路径。

setName(string $name)

设置可下载文件的名称。

getName(): string

获取不带扩展名的可下载文件名称。

setExtension(string $extension)

设置可下载文件的扩展名。

getExtension(): ?string

获取可下载文件的扩展名。

getNameWithExtension(): string

获取带扩展名的可下载文件名称。

setMimeType(string $mime_type)

设置可下载文件的MIME类型。

getMimeType(): string

获取可下载文件的MIME类型。

getSize(): int

获取可下载文件的大小。

getFormattedSize(): string

以人类可读的格式（如2MB或4KB等）获取可下载文件的大小。

static makeDownloadFromPath(string $path): IDownload

通过静态调用从路径创建一个下载实例。

上传

要创建一个上传实例，您应该在 Upload 构造函数中传递一个 FileUpload 实例。

FileUpload

您应该传递 $_FILES 中上传文件的键。

基本用法

$fileUpload = new FileUpload($the_key_of_file_in_file_global_variable);

方法

setValidations(array $validations)

您可以在调用上传方法时传递一些验证来验证文件。

请参阅底部非常详细的 验证 部分

注意：如果没有指定单位，它将是字节。

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

getValidations(): array

获取验证数组。

getExtension(): string

获取上传文件的扩展名。

getSize(): int

获取上传文件的大小。

getOriginalName(): string

获取不带扩展名的上传文件的原始名称。

getOriginalNameWithExtension(): string

获取带扩展名的上传文件的原始名称。

getErrors(): array

获取上传文件的错误。基本上它是上传文件错误的标准化错误，也可能有其他错误。

注意：验证错误不包括在内。

addError(string $error)

将错误添加到错误列表的末尾。

setError($key, string $error)

将错误设置为错误列表中的特定错误。

hasError(): bool

检查是否设置了任何错误。

errorMessagesTranslate(array $translate)

将标准错误翻译为您的本地语言。

基本用法

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

方法

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

get 方法的别名。

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

将一些字符串数据写入文件，并返回写入文件的字节数，或在失败时返回 false。

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

write 方法的别名。

append(string $data)

将一些字符串数据追加到文件中，并在失败时返回写入文件的字节数或 false。

prepend(string $data): bool

将一些字符串数据追加到文件的开始。

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

将文件复制到新位置。如果希望覆盖现有文件，则将 true 作为 $overwrite 参数使用。

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

将文件移动到新位置。如果希望覆盖现有文件，则将 true 作为 $overwrite 参数使用。

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

使用新名称重命名文件。如果希望覆盖现有文件，则将 true 作为 $overwrite 参数使用。

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

获取文件的扩展名或返回 $prefer。

getMimeType($prefer = null): ?string

获取文件的 MIME 类型或返回 $prefer。

getOwner()

获取文件的用户名或返回 false。

getOwnerID()

文件所有者的用户 ID，或在失败时返回 false。

getGroup()

获取文件所属组。

getGroupID()

获取文件的组 ID。

getName(): string

获取文件名。

getBasename(): string

获取文件的 basename。

getInfo(int $options): array

返回文件的信息。信息可以是以下常量之一（常量的含义是显而易见的）

• 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

获取文件的大小。

注意： 目录的大小将递归计算。

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

使用指定模式创建目录。要递归创建目录，请将$recursive参数设置为true。

注意：此方法仅适用于目录。

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

将返回一个RecursiveIteratorIterator，用于遍历所有文件，或者在出错时返回null。

注意：此方法仅适用于目录。

注意：如果您需要获取文件的文件，它将使用该文件的目录作为所需的目录以获取文件。

注意：有关RecursiveIteratorIterator方法的更多信息，请参阅此链接。

用法示例

$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

将返回一个包含从$depth深度获取的文件类型的SplFileInfo的数组。

注意：此方法仅适用于目录。

注意：如果您需要获取文件的文件，它将使用该文件的目录作为所需的目录以获取文件。

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

将返回一个从$depth深度获取的过滤文件类型的SplFileInfo的数组。

注意：此方法仅适用于目录。

注意：如果您需要获取文件的文件，它将使用该文件的目录作为所需的目录以获取文件。

请参阅底部最下的过滤器部分。

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

以SplFileInfo类型的数组获取指定目录的文件。

注意：此方法仅适用于目录。

注意：如果您需要获取文件的文件，它将使用该文件的目录作为所需的目录以获取文件。

getFilteredFiles(array $filters = []): array

以SplFileInfo类型的数组获取指定目录的过滤文件。

请参阅底部最下的过滤器部分。

注意：此方法仅适用于目录。

注意：如果您需要获取文件的文件，它将使用该文件的目录作为所需的目录以获取文件。

静态调用方式方法

与正常方式相比，唯一的不同是，您应将需要执行操作的文件路径传递给静态方法。

fileExists(string $filename): bool

参见正常方式的exists。

isFileReadable(string $filename): bool

参见正常方式的isReadable。

isFileWritable(string $filename): bool

参见正常方式的isWritable。

isItFile(string $filename): bool

参见正常方式的isFile。

isItDir(string $filename): bool

参见正常方式的isDir。

isDirEmpty(string $dir): bool

参见正常方式的isEmpty。

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

参见正常方式的get。

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

参见正常方式的read。

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

参见正常方式的put。

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

参见正常方式的write。

appendToFile(string $filename, string $data)

参见正常方式的append。

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

参见正常方式的prepend。

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

参见正常方式的copy。

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

参见正常方式的move。

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

参见正常方式的rename。

deleteFile(string $filename): bool

参见正常方式的delete。

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

参见正常方式的deleteFilteredFiles。

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

参见正常方式的deleteAllFilteredFiles。

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

参见正常方式的chmod。

fileChown(string $filename, $user): bool

参见正常方式的chown。

fileChgrp(string $filename, $group): bool

参见正常方式的chgrp。

fileModificationTime(string $filename)

参见正常方式的modificationTime。

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

参见正常方式的touch。

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

参见正常方式的getExtension。

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

参见正常方式的getMimeType。

getFileOwner(string $filename)

参见正常方式的getOwner。

getFileOwnerID(string $filename)

参见正常方式的getOwnerID。

getFileGroup(string $filename)

按照常规方式查看 getGroup。

getFileGroupID(string $filename)

按照常规方式查看 getGroupID。

getFileName(string $filename): string

按照常规方式查看 getName。

getFileBasename(string $filename): string

按照常规方式查看 getBasename。

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

按照常规方式查看 getInfo。

getFileSize(string $filename): int

按照常规方式查看 getSize。

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

按照常规方式查看 mkdir。

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

按照常规方式查看 getAllFiles。

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

按照常规方式查看 getAllFilesInDepth。

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

按照常规方式查看 getAllFilteredFilesInDepth。

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

按照常规方式查看 getFiles。

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

按照常规方式查看 getFilteredFiles。

如何操作

如何添加更多验证

要添加您的验证，您必须从 Abstracts 目录扩展 AbstractValidator 并实现以下方法

validate(FileUpload $file): bool

主要验证方法，需要 FileUpload 类型的文件。

如何翻译验证错误

要翻译验证错误，您需要在扩展 AbstractValidator 并在您类中设置本地消息到特定的错误键后使用 setMessage($key, $message) 方法。

每个类中的错误键

• 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!',
]

如何添加更多过滤器

要添加您的过滤器，您必须实现来自 Interfaces 目录的 IFilter 接口并实现以下方法

filter(SplFileInfo $file): bool

主要过滤器方法，需要 SplFileInfo 类型的文件。

过滤器

过滤器类

• 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

您应该在构造函数中传递一个正则表达式，以根据您需要没有扩展名的文件名。

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

• SizeFilter

您应该将最大大小作为第一个参数，最小大小作为第二个参数传递。

传递的参数可以以下格式

文件大小，使用以下之一 ['B', 'KB', 'MB', 'TB', 'PB']

注意：如果没有指定单位，它将是字节。

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

• TypeFilter

有两种类型： 文件 和 目录，可以通过以下常量指定

• IFileSystem::TYPE_FILE

• IFileSystem::TYPE_DIRECTORY

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

• RegexFilter

您应该传递一个正则表达式来过滤文件，并将其应用于名称和扩展名。

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

验证

目前有以下验证

• 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

您应该将最大大小作为第一个参数，最小大小作为第二个参数传递。

传递的参数可以以下格式

文件大小，使用以下之一 ['B', 'KB', 'MB', 'TB', 'PB']

许可

在 MIT 许可下。