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

Статистика: Символов — 15 377/13 062 без пробелов (8 433/7 212 без кода):, слов — 1 222
Разметка: Wiki
{{TOC}}

{{DOCVER 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11}}

== Введение ==
Laravel предоставляет мощную абстракцию для работы с файловой системой благодаря восхитительному PHP-пакету ((https://github.com/thephpleague/flysystem Flysystem)) от Франка де Жонге. Laravel Flysystem содержит простые в использовании драйвера для работы с локальными файловыми системами, Amazon S3 и Rackspace Cloud Storage. Более того, можно очень просто переключаться между этими вариантами хранения файлов, поскольку у всех одинаковый API.

== Настройка ==
Настройки файловой системы находятся в файле %%(t)config/filesystems.php%%. В нём вы можете настроить все свои "disks". Каждый диск представляет определенный драйвер и место хранения. В конфигурационном файле имеются примеры для каждого поддерживаемого драйвера. Поэтому вы можете просто немного изменить конфигурацию под ваши нужды!

Конечно, вы можете сконфигурировать столько дисков, сколько вам будет угодно, и даже можете иметь несколько дисков, которые используют один драйвер.

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
=== Общий диск ===
((#the-public-disk))
Диск %%(t)public%% предназначен для общего доступа к файлам. По умолчанию диск %%(t)public%% использует драйвер %%(t)local%% и хранит файлы в %%(t)storage/app/public%%. Чтобы сделать их доступными через веб, вам надо создать символьную ссылку из %%(t)public/storage%% на %%(t)storage/app/public%%. При этом ваши общедоступные файлы будут храниться в одной папке, которую легко можно использовать в разных развёртываниях при использовании систем обновления на лету, таких как ((https://envoyer.io Envoyer)).

Для создания символьной ссылки используйте Artisan-команду %%(sh)storage:link%%:
%%(sh)
php artisan storage:link
~%%

Само собой, когда файл сохранён и создана символьная ссылка, вы можете создать URL к файлу с помощью вспомогательной функции %%asset()%%:
~%%
echo asset('storage/file.txt');
~%%
%%

=== Драйвер %%(t)local%% ===
При использовании драйвера %%(t)local%% все файловые операции выполняются относительно каталога %%(t)root%%, определенного в вашем конфигурационном файле. По умолчанию это каталог %%(t)storage/app%%. Поэтому следующий метод сохранит файл в %%(t)storage/app/file.txt%%:
%%
Storage::disk('local')->put('file.txt', 'Contents');
%%

=== Требования к драйверам ===
**Пакеты Composer**

Перед использованием S3 или Rackspace вы должны установить соответствующие пакеты при помощи Composer:

  * Amazon S3: %%(t)league/flysystem-aws-s3-v3 ~1.0%%
  * Rackspace: %%(t)league/flysystem-rackspace ~1.0%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
**Настройка драйвера S3**

Настройки драйвера S3 находятся в файле %%(t)config/filesystems.php%%. Там есть пример массива настроек для драйвера S3. Вы можете отредактировать этот массив в соответствии с вашими настройками и учётными данными для S3.
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
**Настройка драйвера FTP**

Интеграция Flysystem отлично работает с FTP, но в стандартном файле настроек %%(t)filesystems.php%% нет примера настройки FTP. Если вам надо настроить файловую систему FTP, вы можете использовать в качестве примера приведенные ниже настройки:
~%%
'ftp' => [
  'driver'   => 'ftp',
  'host'     => 'ftp.example.com',
  'username' => 'ваш-логин',
  'password' => 'ваш-пароль',

  // Необязательные настройки FTP...
  // 'port'     => 21,
  // 'root'     => '',
  // 'passive'  => true,
  // 'ssl'      => true,
  // 'timeout'  => 30,
],
~%%

**Настройка драйвера Rackspace**

Интеграция Flysystem отлично работает с Rackspace, но в стандартном файле настроек %%(t)filesystems.php%% нет примера настройки Rackspace. Если вам надо настроить файловую систему Rackspace, вы можете использовать в качестве примера приведенные ниже настройки:
~%%
'rackspace' => [
  'driver'    => 'rackspace',
  'username'  => 'ваш-логин',
  'key'       => 'ваш-ключ',
  'container' => 'ваш-контейнер',
  'endpoint'  => 'https://identity.api.rackspacecloud.com/v2.0/',
  'region'    => 'IAD',
  'url_type'  => 'publicURL',
],
~%%
%%

== Получение экземпляров дисков ==
Для взаимодействия с любым из ваших сконфигурированных дисков можно использовать фасад %%(t)Storage%%. Например, вы можете использовать метод этого фасада %%put()%%, чтобы сохранить аватар на диск по умолчанию. Если вы вызовите метод фасада %%(t)Storage%% без предварительного вызова метода %%disk()%%, то вызов метода будет автоматически передан диску по умолчанию:
%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
~%%
use Illuminate\Support\Facades\Storage;

Storage::put('avatars/1', $fileContents);
~%%
%%

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
~%%
<?php

namespace App\Http\Controllers;

use Storage;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
  /**
   * Обновить аватар данного пользователя.
   *
   * @param  Request  $request
   * @param  int  $id
   * @return Response
   */
  public function updateAvatar(Request $request, $id)
  {
    $user = User::findOrFail($id);

    Storage::put(
      'avatars/'.$user->id,
      file_get_contents($request->file('avatar')->getRealPath())
    );
  }
}
~%%
%%

При использовании нескольких дисков вы можете обращаться к нужному диску с помощью метода %%disk()%% фасада %%(t)Storage%%:
%%
Storage::disk('s3')->put('avatars/1', $fileContents);
%%

== Чтение файлов ==
Методом %%get()%% можно получать содержимое файла. Он возвращает сырую строку содержимого файла. Не забывайте, все пути файлов необходимо указывать относительно настроенного для диска "корня":
%%
$contents = Storage::get('file.jpg');
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
Методом %%exists()%% можно определить существование файла на диске:
~%%
$exists = Storage::disk('s3')->exists('file.jpg');
~%%
%%

%%(DOCNEW 5.1=f60f8b3697b3ffe381df4ddb7e2875ffce940643 1.04.2016 17:39:10)
Методом %%has()%% можно определить существование файла на диске:
~%%
$exists = Storage::disk('s3')->has('file.jpg');
~%%
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016)
=== URL файла ===
При использовании драйвера %%(t)local%% или %%(t)s3%% вы можете использовать метод %%url()%% для получения URL для файла. При использовании драйвера %%(t)local%% в начало пути к файлу будет просто подставлено %%(t)/storage%%, и будет возвращён относительный URL. При использовании драйвера %%(t)s3%% будет возвращён полный удалённый URL:
~%%
use Illuminate\Support\Facades\Storage;

$url = Storage::url('file1.jpg');
~%%

.(alert)
При использовании драйвера %%(t)local%% все файлы, которые должны быть общедоступны, необходимо помещать в каталог %%(t)storage/app/public%%. Кроме того, вам надо ((#the-public-disk создать символьную ссылку)) в %%(t)public/storage%%, которая указывает на папку %%(t)storage/app/public%%.
%%

=== Метаданные файла ===
Помимо чтения и записи файлов Laravel может предоставить информацию о самих файлах. Например, для получения размера файла в байтах служит метод %%size()%%:
%%
use Illuminate\Support\Facades\Storage;

$size = Storage::size('file1.jpg');
%%

Для получения времени последней модификации файла (отметка времени UNIX) служит метод %%lastModified()%%:
%%
$time = Storage::lastModified('file1.jpg');
%%

=== Запись файлов ===
Для записи файла на диск служит метод %%put()%%. Также вы можете передать в метод %%put()%% PHP-%%(t)resource%%, чтобы использовать низкоуровневую поддержку потоков Flysystem. Очень рекомендуем использовать потоки при работе с большими файлами:
%%
use Illuminate\Support\Facades\Storage;

Storage::put('file.jpg', $contents);

Storage::put('file.jpg', $resource);
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
**Автоматическая работа с потоками**

Если вы хотите, чтобы Laravel автоматически использовал потоки для записи файла в хранилище, используйте методы %%putFile()%% или %%putFileAs()%%. Эти методы принимают объект %%(t)Illuminate\Http\File%% или %%(t)Illuminate\Http\UploadedFile%%, и автоматически используют потоки для размещения файла в необходимом месте:
~%%
use Illuminate\Http\File;

// Автоматическое генерирование UUID для имени файла...
Storage::putFile('photos', new File('/path/to/photo'));

// Ручное указание имени файла...
Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');
~%%

У метода %%putFile()%% есть несколько важных нюансов. Заметьте, мы указали только название каталога без имени файла. По умолчанию метод %%putFile()%% генерирует UUID в качестве имени файла. Метод вернёт путь к файлу, поэтому вы можете сохранить в БД весь путь, включая сгенерированное имя.

Методы %%putFile()%% и %%putFileAs()%% принимают также аргумент "видимости" сохраняемого файла. Это полезно в основном при хранении файлов в облачном хранилище, таком как S3, когда необходим общий доступ к файлам:
~%%
Storage::putFile('photos', new File('/path/to/photo'), 'public');
~%%
%%

**Добавление контента в начало / конец файла**

Для вставки контента в начало или конец файла служат методы %%prepend()%% и %%append()%%:
%%
Storage::prepend('file.log', 'Prepended Text');

Storage::append('file.log', 'Appended Text');
%%

**Копирование и перемещение файлов**

Метод %%copy()%% используется для копирования существующего файла в новое расположение на диске, а метод %%move()%% - для переименования или перемещения существующего файла в новое расположение:
%%
Storage::copy('old/file1.jpg', 'new/file1.jpg');

Storage::move('old/file1.jpg', 'new/file1.jpg');
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
=== Загрузка файлов ===
Загрузка файлов в веб-приложениях - это чаще всего загрузка пользовательских файлов, таких как аватар, фотографии и документы. В Laravel очень просто сохранять загружаемые файлы методом %%store()%% на экземпляре загружаемого файла. Просто вызовите метод %%store()%%, указав путь для сохранения загружаемого файла:
~%%
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Http\Controllers\Controller;

class UserAvatarController extends Controller
{
  /**
   * Обновление аватара пользователя.
   *
   * @param  Request  $request
   * @return Response
   */
  public function update(Request $request)
  {
    $path = $request->file('avatar')->store('avatars');

    return $path;
  }
}
~%%

В этом примере есть несколько важных моментов. Заметьте, мы указали только название каталога без имени файла. По умолчанию метод %%store()%% генерирует UUID в качестве имени файла. Метод вернёт путь к файлу, поэтому вы можете сохранить в БД весь путь, включая сгенерированное имя.

Также вы можете вызвать метод %%putFile()%% фасада %%(t)Storage%% для выполнения этой же операции над файлом, как показано в примере:
~%%
$path = Storage::putFile('avatars', $request->file('avatar'));
~%%

**Указание имени файла**

Если вы не хотите, чтобы файлу автоматически было назначено имя, можете использовать метод %%storeAs()%%, который принимает в виде аргументов путь, имя файла, и (необязательно) диск:
~%%
$path = $request->file('avatar')->storeAs(
  'avatars', $request->user()->id
);
~%%

Конечно, вы также можете использовать метод %%putFileAs()%% фасада %%(t)Storage%%, который выполняет такую же операцию:
~%%
$path = Storage::putFileAs(
  'avatars', $request->file('avatar'), $request->user()->id
);
~%%

**Указание диска**

По умолчанию этот метод использует диск по умолчанию. Если необходимо указать другой диск, передайте имя диска в качестве второго аргумента в метод %%store()%%:
~%%
$path = $request->file('avatar')->store(
  'avatars/'.$request->user()->id, 's3'
);
~%%
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
=== Видимость файлов ===
В интеграции Flysystem в Laravel "видимость" - это абстракция разрешений на файлы для использования на нескольких платформах. Файлы могут быть обозначены как %%(t)public%% или %%(t)private%%. Если файл отмечен как %%(t)public%%, значит он должен быть доступен остальным. Например, при использовании драйвера S3 вы можете получить URL для %%(t)public%%-файлов.

Вы можете задать видимость при размещении файла методом %%put()%%:
~%%
use Illuminate\Support\Facades\Storage;

Storage::put('file.jpg', $contents, 'public');
~%%

Если файл уже был сохранён, то получить и задать его видимость можно методами %%getVisibility()%% и %%setVisibility()%%:
~%%
$visibility = Storage::getVisibility('file.jpg');

Storage::setVisibility('file.jpg', 'public')
~%%
%%

== Удаление файлов ==
Метод %%delete()%% принимает имя одного файла или массив файлов для удаления с диска:
%%
use Illuminate\Support\Facades\Storage;

Storage::delete('file.jpg');

Storage::delete(['file1.jpg', 'file2.jpg']);
%%

== Папки ==
**Получение всех файлов из папки**

Метод %%files()%% возвращает массив всех файлов из указанной папки. Если вы хотите получить массив всех файлов папки и её подпапок, используйте метод %%allFiles()%%:
%%
use Illuminate\Support\Facades\Storage;

$files = Storage::files($directory);

$files = Storage::allFiles($directory);
%%

**Получение всех подпапок**

Метод %%directories()%% возвращает массив всех папок из указанной папки. Вдобавок, вы можете использовать метод %%allDirectories()%% для получения списка всех папок в данной папке и во всех её подпапках: 
%%
$directories = Storage::directories($directory);

// рекурсивно...
$directories = Storage::allDirectories($directory);
%%

**Создание папки**

Метод %%makeDirectory()%% создаёт указанную папку, включая необходимые подпапки:
%%
Storage::makeDirectory($directory);
%%

**Удаление директории**

И наконец, метод %%deleteDirectory()%% удаляет папку и все её файлы с диска:
%%
Storage::deleteDirectory($directory);
%%

== Пользовательские файловые системы == 
Laravel Flysystem предоставляет драйверы для нескольких "drivers" из коробки. Однако, Flysystem не ограничен ими и содержит в себе адаптеры для многих других систем хранения. Вы можете создать свой драйвер, если хотите использовать один из этих дополнительных адаптеров в вашем приложении Laravel.

Чтобы установить свою файловую систему, вы должны будете создать ((/docs/v5/providers сервис-провайдер)) такой как %%(t)DropboxServiceProvider%%. Для определения своего драйвера вы можете использовать метод %%extend()%% фасада %%(t)Storage%% в методе %%boot()%% провайдера:
%%
<?php

namespace App\Providers;

use Storage;
use League\Flysystem\Filesystem;
use Dropbox\Client as DropboxClient;
use Illuminate\Support\ServiceProvider;
use League\Flysystem\Dropbox\DropboxAdapter;

class DropboxServiceProvider extends ServiceProvider
{
  /**
   * Выполнение после-регистрационной загрузки сервисов.
   *
   * @return void
   */
  public function boot()
  {
    Storage::extend('dropbox', function ($app, $config) {
      $client = new DropboxClient(
        $config['accessToken'], $config['clientIdentifier']
      );

      return new Filesystem(new DropboxAdapter($client));
    });
  }

  /**
   * Регистрация привязок в контейнере.
   *
   * @return void
   */
  public function register()
  {
    //
  }
}
%%

Первый аргумент метода %%extend()%% - имя драйвера, второй - замыкание, которое получает переменные %%$app%% и %%$config%%. Замыкание должно возвратить экземпляр %%(t)League\Flysystem\Filesystem%%. Переменная %%$config%% содержит значения, определенные в %%(t)config/filesystems.php%% для указанного диска.

Когда вы создали сервис-провайдер для регистрации расширения, вы можете использовать драйвер %%(t)dropbox%% в своём файле с настройками %%(t)config/filesystems.php%%.