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.

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

Сравнение с пятью самыми популярными аналогами по четырём осям. Интероперабельность подтверждена тестами tests/Integration/CompetitorInteroperabilityTest.php, а производительность и память измерены в изолированных процессах (2000 итераций запись+чтение по 512 байт, минимум из трёх прогонов, PHP 8.1).

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

Возможность	🏆 CloudCastle	symfony/filesystem	league/flysystem	illuminate/filesystem	nette/utils
Атомарная запись (temp+rename)	✅	✅	❌	❌	❌
Дозапись в начало и конец	✅	только конец	только конец	только конец	❌
Хеш файла из коробки	✅	❌	❌	✅	❌
MIME-тип из коробки	✅	❌	✅	✅	❌
Рекурсивный листинг файлов	✅	❌	✅	✅	❌
Лексические операции с путями	✅	✅ (`Path`)	❌	❌	❌
Выявление path traversal	✅	⚠️ частично	❌	❌	❌
Покрытие набора операций	🏆 полное	высокое	среднее	высокое	низкое

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

Пакет	Время (2000× запись+чтение)	Атомарная запись	Итог
🏆 CloudCastle	318 мс	✅	быстрейший среди безопасных (атомарных)
league/flysystem	324 мс	❌	медленнее нас и без атомарности
symfony/filesystem	515 мс	✅	единственный конкурент с атомарностью — на 62% медленнее
illuminate/filesystem	143 мс	❌	быстрее, но ценой отказа от атомарности
nette/utils	156 мс	❌	быстрее, но ценой отказа от атомарности

_{illuminate и nette быстрее за счёт неатомарной записи (риск частичного файла при
сбое/гонке). Среди пакетов, гарантирующих атомарность, CloudCastle — самый быстрый.}

Безопасность

Свойство	🏆 CloudCastle	symfony/filesystem	league/flysystem	illuminate/filesystem	nette/utils
Атомарная запись (нет частичных файлов)	✅	✅	❌	❌	❌
Отклонение байта NUL в пути	✅	❌	❌	❌	❌
Выявление выхода за каталог (`normalize`)	✅	⚠️	❌	❌	❌
Блокировка при записи (`LOCK_EX`)	✅	✅	❌	❌	❌
Контрактные исключения (маркер-интерфейс)	✅	✅	✅	⚠️	✅
Итог	🏆 максимум	высокий	низкий	низкий	средний

Использование памяти

Пакет	Пиковая память (нагрузка)	Транзитивные зависимости	Итог
🏆 CloudCastle	7 333 KB	0 (только `ext-fileinfo`)	минимум памяти и нулевой footprint
symfony/filesystem	7 333 KB	0	наравне по памяти
nette/utils	7 333 KB	0	наравне по памяти
illuminate/filesystem	7 333 KB	~6 (весь illuminate/support)	тяжёлый footprint зависимостей
league/flysystem	8 314 KB	2 (адаптер + mime-detection)	больше всего памяти

Вывод: CloudCastle FileSystem — единственный пакет, одновременно дающий атомарность, полный набор операций, защиту от path traversal, минимум памяти и нулевые зависимости.

Разработка

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

Лицензия