README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle FileSystem

Безопасная работа с файловой системой для PHP 8.1+: атомарная запись, операции с каталогами и метаданными, лексические операции с путями с выявлением path traversal. Зависимости — только php и ext-fileinfo.

Установка

composer require cloud-castle/file-system

Требуется PHP 8.1+ и расширение fileinfo.

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

<?php

use CloudCastle\FileSystem\FileSystem;
use CloudCastle\FileSystem\Path;

// Атомарная запись (временный файл + rename) — без частично записанных файлов.
FileSystem::write('/var/app/config/app.php', '<?php return ["debug" => false];');

$content = FileSystem::read('/var/app/config/app.php');
$sha256 = FileSystem::hash('/var/app/config/app.php');
$mime = FileSystem::mimeType('/var/app/config/app.php');

// Каталоги.
FileSystem::makeDirectory('/var/app/cache');
$files = FileSystem::allFiles('/var/app');       // рекурсивно, отсортировано
FileSystem::deleteDirectory('/var/app/cache');   // рекурсивно

// Пути (без обращения к диску).
$path = Path::join('/var', 'app', 'config');     // «/var/app/config»
$safe = Path::normalize('/var/data/../../etc');  // «/etc» — виден выход за пределы
$ext = Path::extension('App.PHP');               // «php»

Возможности

Атомарная запись через временный файл + rename — исключает частично записанные файлы при сбое или гонке.
Файлы: чтение, построчное чтение, запись, дозапись в начало/конец, копирование, перемещение, удаление, touch, chmod.
Метаданные: размер, время модификации, хеш (sha256 и др.), MIME-тип.
Каталоги: создание (рекурсивно), гарантированное существование, рекурсивное удаление и очистка, листинг файлов/подкаталогов/рекурсивно.
Пути: join, лексическая normalize (выявление path traversal), isAbsolute, extension, filename, changeExtension, hasExtension.
Безопасность: отклонение байта NUL в путях, атомарность, контрактные исключения вместо предупреждений PHP.

Сравнение с аналогами

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug.

1. Функциональность

Возможность	🏆 CloudCastle	symfony	league	illuminate	nette	native¹
Атомарная запись (temp + rename)	✅	✅	❌	❌	❌	❌
Дозапись в начало и в конец файла	✅	❌	❌	❌	❌	❌
Хеш и MIME-тип файла из коробки	✅	❌	✅	✅	❌	❌
Рекурсивный листинг + лексические операции с путями	✅	❌	✅	✅	❌	❌
Нулевые внешние зависимости (кроме ext-fileinfo)	✅	✅	❌	❌	✅	✅
Всего	🏆 5	2	2	2	1	1

2. Безопасность и корректность

Свойство	🏆 CloudCastle	symfony	league	illuminate	nette	native¹
Атомарная запись (нет частичных файлов при сбое)	✅	✅	❌	❌	❌	❌
Блокировка при записи (LOCK_EX)	✅	✅	❌	❌	❌	❌
Отклонение байта NUL в пути	✅	❌	❌	❌	❌	❌
Выявление выхода за каталог (path traversal)	✅	❌	✅	❌	❌	❌
Контрактные исключения (маркер-интерфейс)	✅	✅	✅	❌	✅	❌
Всего	🏆 5	3	2	0	1	0

3. Производительность

Атомарная запись 512 Б + чтение, 4 000 раз (минимум из 4).

Решение	Время (мс)	Итог
native¹	397,4	базовый уровень (не библиотека)
🏆 illuminate	405,3	быстрейшее среди библиотек
nette	425,4	аналог
CloudCastle	476,8	аналог
league	480,5	аналог
symfony	563,3	аналог

4. Потребление памяти

Пик памяти на 4 000 операций (изолированный процесс, только целевая библиотека).

Решение	Пиковая память (KB)	Итог
🏆 CloudCastle	7 051	легчайшее среди библиотек
symfony	7 051	аналог
illuminate	7 051	аналог
nette	7 051	аналог
native¹	7 051	базовый уровень (не библиотека)
league	8 023	аналог

¹ Базовый уровень (нативные вызовы/примитивы без полноты решения) показан для контекста и не претендует на победу среди библиотек-аналогов.

_{Операция — АТОМАРНАЯ запись + чтение. Атомарную запись из коробки дают только
cloud-castle (write) и symfony (dumpFile); для illuminate, nette, league и
нативного вызова durability материализована тем же паттерном (временный файл со
случайным именем + rename) — эквивалентная работа. write cloud-castle вдобавок
берёт LOCK_EX и гарантирует существование каталога, поэтому на ~15 % медленнее
голого file_put_contents+rename, но безопаснее (см. таблицу безопасности).
Память измеряется в изоляции.}

Вывод: CloudCastle FileSystem — самый защищённый файловый пакет (атомарная запись, LOCK_EX, случайное имя temp, отклонение NUL и path traversal), быстрейший среди библиотек с атомарной записью из коробки и самый лёгкий по памяти при нулевых внешних зависимостях (кроме ext-fileinfo) и широчайшем наборе операций.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд с описаниями: composer run-script --list.

Документация

Репозиторий: https://gitverse.ru/cloud-castle/file-system
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия