4.9. Файловое хранилище

• 1. Введение
• 2. Конфигурация
  • 2.1. Локальный драйвер
  • 2.2. Публичный диск
  • 2.3. Предварительные требования к драйверам
  • 2.4. Файловые системы с ограниченной областью действия и только для чтения
  • Amazon S3 Compatible Filesystems
• Obtaining Disk Instances
  • On-Demand Disks
• Retrieving Files
  • Downloading Files
  • File URLs
  • Temporary URLs
  • File Metadata
• Storing Files
  • Prepending and Appending To Files
  • Copying and Moving Files
  • Automatic Streaming
  • File Uploads
  • File Visibility
• Deleting Files
• Directories
• Testing
• Custom Filesystems

1. Введение

Laravel предоставляет мощную абстракцию файловой системы благодаря замечательному PHP-пакету Flysystem от Фрэнка де Йонге. Интеграция Laravel с Flysystem предлагает простые драйверы для работы с локальными файловыми системами, SFTP и Amazon S3. Более того, переключение между этими вариантами хранилища между локальной машиной разработки и сервером в продакшене невероятно просто, так как API остаётся одинаковым для каждой системы.

2. Конфигурация

Файл конфигурации файловой системы Laravel находится по пути config/filesystems.php. В этом файле вы можете настроить все свои "диски" файловой системы. Каждый диск представляет собой конкретный драйвер хранилища и местоположение хранилища. Примеры конфигурации для каждого поддерживаемого драйвера включены в файл конфигурации, чтобы вы могли изменить настройки в соответствии с вашими предпочтениями и учётными данными.

Драйвер local работает с файлами, хранящимися локально на сервере, где запущено приложение Laravel, в то время как драйвер s3 используется для работы с облачным хранилищем Amazon S3.

2.1. Локальный драйвер

При использовании драйвера local все операции с файлами выполняются относительно директории root, указанной в файле конфигурации filesystems. По умолчанию это значение установлено на директорию storage/app. Таким образом, следующий метод запишет файл в storage/app/example.txt:

use Illuminate\Support\Facades\Storage;
 
Storage::disk('local')->put('example.txt', 'Contents');

2.2. Публичный диск

Диск public, указанный в файле конфигурации filesystems вашего приложения, предназначен для файлов, которые будут доступны публично. По умолчанию диск public использует драйвер local и сохраняет свои файлы в директории storage/app/public.

Чтобы сделать эти файлы доступными из интернета, вам следует создать символическую ссылку из исходной директории storage/app/public в целевую директорию public/storage. Использование этой структуры каталогов позволит хранить публично доступные файлы в одной директории, которую можно легко переносить между развертываниями при использовании систем с нулевым временем простоя, таких как Envoyer.

Для создания символической ссылки вы можете использовать Artisan-команду storage:link:

php artisan storage:link

После того как файл был сохранён и символическая ссылка создана, вы можете создать URL-адрес для файлов с помощью хелпера asset:

echo asset('storage/file.txt');

Вы можете настроить дополнительные символические ссылки в вашем конфигурационном файле filesystems. Каждая из настроенных ссылок будет создана, когда вы выполните команду storage:link:

'links' => [
    public_path('storage') => storage_path('app/public'),
    public_path('images') => storage_path('app/images'),
],

Команду storage:unlink можно использовать для удаления ваших настроенных символических ссылок:

php artisan storage:unlink

2.3. Предварительные требования к драйверам

2.3.1. Конфигурация драйвера S3

Перед использованием драйвера S3 вам нужно установить пакет Flysystem S3 через менеджер пакетов Composer:

composer require league/flysystem-aws-s3-v3 "^3.0" --with-all-dependencies

Массив конфигурации диска S3 находится в вашем конфигурационном файле config/filesystems.php. Обычно вам нужно настроить вашу информацию и учетные данные для S3, используя следующие переменные окружения, на которые ссылается конфигурационный файл config/filesystems.php:

AWS_ACCESS_KEY_ID=<your-key-id>
AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=<your-bucket-name>
AWS_USE_PATH_STYLE_ENDPOINT=false

Для удобства эти переменные окружения соответствуют соглашению о наименованиях, используемому в AWS CLI.

2.3.2. Конфигурация драйвера FTP

Перед использованием драйвера FTP вам нужно установить пакет Flysystem FTP через менеджер пакетов Composer:

composer require league/flysystem-ftp "^3.0"

Интеграции Flysystem в Laravel отлично работают с FTP; однако пример конфигурации не включен в стандартный конфигурационный файл config/filesystems.php фреймворка. Если вам нужно настроить файловую систему FTP, вы можете использовать приведенный ниже пример конфигурации:

'ftp' => [
    'driver' => 'ftp',
    'host' => env('FTP_HOST'),
    'username' => env('FTP_USERNAME'),
    'password' => env('FTP_PASSWORD'),
 
    // Optional FTP Settings...
    // 'port' => env('FTP_PORT', 21),
    // 'root' => env('FTP_ROOT'),
    // 'passive' => true,
    // 'ssl' => true,
    // 'timeout' => 30,
],

2.3.3. Конфигурация драйвера SFTP

Перед использованием драйвера SFTP вам нужно установить пакет Flysystem SFTP через менеджер пакетов Composer:

composer require league/flysystem-sftp-v3 "^3.0"

Интеграции Flysystem в Laravel отлично работают с SFTP; однако пример конфигурации не включен в стандартный конфигурационный файл config/filesystems.php фреймворка. Если вам нужно настроить файловую систему SFTP, вы можете использовать приведенный ниже пример конфигурации:

'sftp' => [
    'driver' => 'sftp',
    'host' => env('SFTP_HOST'),
 
    // Settings for basic authentication...
    'username' => env('SFTP_USERNAME'),
    'password' => env('SFTP_PASSWORD'),
 
    // Settings for SSH key based authentication with encryption password...
    'privateKey' => env('SFTP_PRIVATE_KEY'),
    'passphrase' => env('SFTP_PASSPHRASE'),
 
    // Settings for file / directory permissions...
    'visibility' => 'private', // `private` = 0600, `public` = 0644
    'directory_visibility' => 'private', // `private` = 0700, `public` = 0755
 
    // Optional SFTP Settings...
    // 'hostFingerprint' => env('SFTP_HOST_FINGERPRINT'),
    // 'maxTries' => 4,
    // 'passphrase' => env('SFTP_PASSPHRASE'),
    // 'port' => env('SFTP_PORT', 22),
    // 'root' => env('SFTP_ROOT', ''),
    // 'timeout' => 30,
    // 'useAgent' => true,
],

2.4. Файловые системы с ограниченной областью действия и только для чтения

Ограниченные диски позволяют определить файловую систему, в которой все пути автоматически дополняются заданным префиксом пути. Перед созданием ограниченного диска файловой системы вам нужно установить дополнительный пакет Flysystem через менеджер пакетов Composer: