Файловая система

Каждое приложение так или иначе работает с файлами: загрузка аватаров, генерация отчётов, хранение резервных копий, парсинг конфигов. Компонент файловой системы даёт единый набор методов для всех этих задач – и неважно, где физически лежит файл: на локальном сервере, на FTP или в S3-совместимом хранилище.

Как это работает:

1. Вы определяете диски в конфигурации – каждый диск это "точка входа" в файловое хранилище.
2. Выбираете диск методом Storage::disk('avatars') – все пути внутри него относительны к его корневому каталогу.
3. Работаете знакомыми методами: put, get, delete, exists и десятком других.

Для облачного хранилища есть отдельный Storage::cloud() – он вернёт диск, указанный в параметре cloud конфига. Это удобно, если ваше основное хранилище – локальное, а для файлов пользователей вы используете S3.

А если нужно обратиться напрямую к файловой системе сервера?

Используйте класс File или помощник files(). В отличие от Storage, они принимают абсолютные пути и игнорируют настройки дисков. Подходят для служебных операций: загрузка конфигов, очистка кэша, работа с временными файлами.

Подробности доступны в разделах Файлы, Каталоги, Локальный диск, FTP-диск и S3-совместимый диск.

Конфигурирование дисков

Диски задаются в config/filesystem.php. Ключ default определяет диск для Storage::disk() без аргумента, а cloud – для Storage::cloud().

return [
    'default' => env('FILESYSTEM_DISK', 'local'),
    'cloud' => env('FILESYSTEM_CLOUD', 's3'),

    'disks' => [
        'local' => [
            'driver' => 'local',
            'root' => storage_path('app'),
            'throw' => true,
        ],

        'avatars' => [
            'driver' => 'local',
            'root' => public_path('avatars'),
            'throw' => false,
        ],

        's3' => [
            'driver' => 'simpleS3',
            'access_key' => env('AWS_ACCESS_KEY_ID'),
            'secret_key' => env('AWS_SECRET_ACCESS_KEY'),
            'endpoint' => env('AWS_ENDPOINT'),
            'bucket' => env('AWS_BUCKET'),
            'throw' => true,
        ],
    ],
];

Имя драйвера регистрозависимо: встроенные значения – local, ftp и simpleS3. У локального диска каталог root должен существовать к моменту создания диска. Несколько дисков могут использовать один драйвер и разные root.

Параметр throw передаётся драйверу: при true ошибки драйвера выбрасываются, при false драйвер возвращает false там, где это предусмотрено его методом. Проверяйте возвращаемые значения операций записи и удаления.

Получение диска

use Imhotep\Facades\Storage;

// Диск по умолчанию (default) или по имени
$local = Storage::disk();
$avatars = Storage::disk('avatars');

// Облачный диск по умолчанию (cloud) или по имени
$cloud = Storage::cloud();
$s3 = Storage::cloud('s3');

// То же через глобальный помощник
$disk = disk();
$avatars = disk('avatars');

$cloud = cloud();
$s = cloud('s3');

Чтобы сменить имя диска по умолчанию в рантайме, используйте:

Storage::setDefaultDriver('avatars');
// или
Storage::setDefaultCloudDriver('s3');

Прямой доступ к файловой системе сервера

Для прямого доступа к файловой системе сервера используется класс Imhotep\Filesystem\Filesystem. В большинстве случаев вы будете обращаться к нему через фасад File или глобальный помощник files(). В отличие от Storage, этот API не знает о дисках и не преобразует пути – вы передаёте полный абсолютный путь.

use Imhotep\Facades\File;

$path = storage_path('app/report.json');

File::put($path, json_encode(['ready' => true]));
$report = File::json($path);

if (File::missing($path)) {
    File::makeDirectory(dirname($path));
}

Методы require и requireOnce выбрасывают FileNotFoundException, если файла нет. Для локального API пути не преобразуются относительно диска.

Справочник локального API