README

File Entity type for Arris µFramework. Simple OOP File wrapper.

Класс File предоставляет объектно-ориентированный интерфейс для работы с файлами в PHP. Инкапсулирует основные операции с файлами (чтение, запись, перемещение, копирование) и предоставляет метаданные (размер, MIME-тип, время изменения, хэш, владелец).

Требования

• PHP ^8.2
• ext-posix
• ext-fileinfo

Установка

composer require karelwintersky/arris.entity.file

Быстрый старт

use Arris\Entity\File;

// Чтение существующего файла
$file = new File('/path/to/file.txt');
$content = $file->getContent();

// Создание нового файла
$file = File::create('/path/to/new.txt', 'Hello World');

// Временный файл (автоматически удаляется через closeAndDelete())
$file = File::createTemp('upload_', 'data');
// ...работа с файлом...
$file->closeAndDelete();

Константы режимов открытия

Методы

Конструктор и фабрики

__construct(string $path, bool $force_open = false)

Создаёт объект для существующего файла. Если файл не существует — бросает FileException.

$file = new File('/path/to/file.txt');           // только запоминает путь
$file = new File('/path/to/file.txt', true);     // сразу открывает хэндлер

static create(string $path, string $content = ''): self

Создаёт новый файл. Бросает InvalidArgumentException если файл уже существует.

$file = File::create('/tmp/data.txt', 'contents');

static createTemp(string $prefix = '', string $content = ''): self

Создаёт временный файл в системном каталоге для temp-файлов.

$temp = File::createTemp('app_', 'temporary data');
$temp->isTemp(); // true

Работа с файловым хэндлером

open(string $mode = FM_APPEND): self

Открывает файл, создаёт хэндлер. Возвращает $this для цепочки.

$file->open(File::FM_READ)->getContent();

close(bool $just_in_case = true): self

Закрывает хэндлер. Не удаляет файл.

$file->close();      // молча, если не открыт
$file->close(false); // бросает исключение если не открыт

closeAndDelete(): self

Закрывает хэндлер и удаляет файл. Удобно для временных файлов.

$temp = File::createTemp('log_');
// ...записать данные...
$temp->closeAndDelete();

Чтение и запись

getContent(int $position = 0, ?int $length = null): string

Получить содержимое файла. С параметрами — чтение с позиции.

$all = $file->getContent();
$chunk = $file->getContent(1024, 512); // 512 байт с позиции 1024

putContent(string $content, int $flag = 0): int

Записать содержимое. Возвращает количество записанных байт.

$bytes = $file->putContent('data');
$file->putContent(' appended', FILE_APPEND);

writeFromPosition(string $content, int $position): int

Запись с указанной позиции (через хэндлер).

$file->writeFromPosition('NEW', 5); // заменяет с 5-й позиции

readFromPosition(int $position = 0, ?int $length = null): string

Чтение с указанной позиции (через хэндлер).

$chunk = $file->readFromPosition(10, 20);

truncate(int $size = 0): bool

Обрезает файл до указанного размера.

$file->truncate();     // обрезать до 0
$file->truncate(1024); // обрезать до 1024 байт

Перемещение и копирование

move(string $newPath): bool

Перемещает файл. Если $newPath заканчивается на /, сохраняет текущее имя.

$file->move('/new/path/file.txt');
$file->move('/new/directory/'); // переместит с тем же именем

copy(string $targetPath): self

Копирует файл. Возвращает новый объект File для копии.

$copy = $file->copy('/backup/file.txt');

Удаление

delete(bool $just_in_case = true): bool

Удаляет файл.

$file->delete();      // молча, если не существует
$file->delete(false); // бросает исключение если не существует

Метаданные

getPath(): string

Полный путь к файлу.

getFilename(): string

Имя файла с расширением (без пути): file.txt

getFilenameWithoutExtension(): string

Имя файла без расширения: file

getExtension(): string

Расширение без точки: txt

getDirectory(): string

Путь к директории: /path/to

getSize(): int / getLength(): int

Размер файла в байтах. getLength() — алиас.

getMimeType(): string

MIME-тип: text/plain, image/jpeg

getLastModifiedTime(): int

Timestamp последнего изменения.

getHash(string $algorithm = 'sha256'): string

Хэш файла. Поддерживает любой алгоритм из hash_algos().

getFileOwner(): array

Владелец файла (POSIX):

[
    'uid'   => 1000,
    'gid'   => 1000,
    'name'  => 'user',
    'group' => 'user',
    'dir'   => '/home/user',
    'shell' => '/bin/bash'
]

Проверки

Геттеры состояния

Статические методы

static match(string $pattern, string $test, int $flags): bool

Проверка совпадения строки с shell-шаблоном (обёртка над fnmatch()).

File::match('*.txt', 'file.txt', FNM_PATHNAME); // true

Исключения

Все ошибки файловых операций бросают Arris\Entity\Exceptions\FileException.

Статический фабричный метод:

FileException::create("File not found: %s", [$path]);

Примеры

Чтение с проверкой

$file = new File('/etc/config.json');

if ($file->isReadable()) {
    echo $file->getContent();
    echo "Size: {$file->getSize()} bytes";
    echo "Modified: " . date('Y-m-d H:i', $file->getLastModifiedTime());
}

Цепочки операций

$file = new File('/tmp/data.txt');
$file->open(File::FM_WRITE)
    ->writeFromPosition('PATCHED', 0)
    ->close();

Копирование и перемещение

$original = new File('/uploads/photo.jpg');
$backup = $original->copy('/backups/photo.jpg');
$original->move('/archive/photo.jpg');

Временный файл

$temp = File::createTemp('cache_', 'initial data');
$temp->putContent(' updated');
$content = $temp->getContent();
$temp->closeAndDelete(); // хэндлер закрыт, файл удалён

Работа с позициями

$file = File::create('/tmp/patch.bin', str_repeat('A', 1024));
$file->writeFromPosition('B', 512);
$middle = $file->readFromPosition(500, 24);