Laravel - Digging Deeper - File Storage (官方文件原子化翻譯文件)

# 前言

學習一個框架, Ray 的想法是, 在深入理解底層實作的原理之前, 應該先知道這個框架的 使用方法; 先學習怎麼使用這個前人造的輪子, 再學習怎麼樣造一個輪子。
所以本篇文章重點在於細讀官方文件, 並將內容理解後以 Q&A 的方式記錄下來, 加速學習以及查詢。

# Configuration

# The Local Driver

以下的 Laravel example code 的意思是？

• Example:

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

• Answer:
  使用 local driver
  將 Contents 寫到 project/storage/app/example.txt 檔案裡

# The Public Disk

以下的 Laravel example command 的意思是？

• Example:

  php artisan storage:link

• Answer:
  會在 storage/app/public 跟 public/storage 之間建立一個 symlink

以下的 Laravel example code 的意思是？

• Example:

  <?php
  echo asset('storage/file.txt');

• Answer:
  產生一個可存取 project/public/storage/file.txt 檔案的 url
  預設根目錄為 public

以下位於 config/filesystem.php 的 Laravel example code 的意思是？

• Example:

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

• Answer:
  當執行 php artisan storage:link 時, Laravel 預設會將 project/storage/app/public 以及 project/public/storage 這兩個資料夾建立 symlink, 可在 link 內自定義要建立 symlink 的規則, 如上 example:
  在 project/public/storage 以及 project/storage/app/public 之間建立 symlink
  在 project/public/images 以及 project/storage/app/images 之間建立 symlink

# Driver Prerequisites

# Composer Packages

Laravel filesystem 中, 如果我要使用 S3, SFTP drivers, 需要另外安裝套件嗎？

要哦

Laravel filesystem 中, 如果我要使用 S3, SFTP drivers, 為何要安裝 cached adapter?

可以增進效能

# S3 Driver Configuration

Laravel filesystem 中, 如果我要使用 S3, 而我想要增加新的 env variable, naming convention 跟什麼一樣？

AWS CLI

# FTP Driver Configuration

以下位於 config/filesystem.php 的 Laravel example code 的意思是？

• Example:

  <?php
  'ftp' => [
      'driver' => 'ftp',
      'host' => 'ftp.example.com',
      'username' => 'your-username',
      'password' => 'your-password',
  
      // Optional FTP Settings...
      // 'port' => 21,
      // 'root' => '',
      // 'passive' => true,
      // 'ssl' => true,
      // 'timeout' => 30,
  ],

• Answer:
  當使用 FTP driver 的設定

# SFTP Driver Configuration

以下位於 config/filesystem.php 的 Laravel example code 的意思是？

• Example:

  <?php
  'sftp' => [
      'driver' => 'sftp',
      'host' => 'example.com',
      'username' => 'your-username',
      'password' => 'your-password',
  
      // Settings for SSH key based authentication...
      'privateKey' => '/path/to/privateKey',
      'password' => 'encryption-password',
  
      // Optional SFTP Settings...
      // 'port' => 22,
      // 'root' => '',
      // 'timeout' => 30,
  ],

• Answer:
  當使用 SFTP driver 的設定

# Caching

以下的 Laravel example code 的意思是？

• Example:

  <?php
  's3' => [
      'driver' => 's3',
  
      // Other Disk Options...
  
      'cache' => [
          'store' => 'memcached',
          'expire' => 600,
          'prefix' => 'cache-prefix',
      ],
  ],

• Answer:
  在 s3 driver 內定義 cache

# Obtaining Disk Instances

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use Illuminate\Support\Facades\Storage;
  
  Storage::put('avatars/1', $content);

• Answer:
  將 $content 寫到位於 default disk 的檔案 /avatars/1

以下的 Laravel example code 的意思是？

• Example:

  <?php
  Storage::disk('s3')->put('avatars/1', $content);

• Answer:
  將 $content 寫到位於 s3 disk 的檔案 /avatars/1

# Retrieving Files

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $contents = Storage::get('file.jpg');

• Answer:
  從 default disk 中取得檔案 /file.jpg, get('') 裡頭指定的為 default disk 下的相對路徑

以下的 Laravel example code 的意思是？

• Example:

  <?php
  if (Storage::disk('s3')->exists('file.jpg')) {
      // ...
  }

• Answer:
  判斷 s3 disk 下, /file.jpg 是否存在

以下的 Laravel example code 的意思是？

• Example:

  <?php
  if (Storage::disk('s3')->missing('file.jpg')) {
      // ...
  }

• Answer:
  判斷 s3 disk 下, /file.jpg 是否不存在

# Downloading Files

以下的 Laravel example code 的意思是？

• Example:

  <?php
  return Storage::download('file.jpg');
  
  return Storage::download('file.jpg', $name, $headers);

• Answer:
  使瀏覽器觸發一個下載動作, arg1 為檔案路徑, arg2 為檔案名稱, arg3 為 header

# File URLs

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use Illuminate\Support\Facades\Storage;
  
  $url = Storage::url('file.jpg');

• Answer:
  產生一個 default disk 中, 檔案 /file.jpg 的可被存取的 url

Laravel file storage 中, 要可被 public accessible 的檔案需置於哪個資料夾？

storage/app/public

Laravel 中, 當產生 public accessible url 時, 會 url encode 嗎？

不會, 所以務必確保使用可以成為 valid url 的檔名

# Temporary URLs

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $url = Storage::temporaryUrl(
      'file.jpg',
      now()->addMinutes(5),
      [
          'ResponseContentType' => 'application/octet-stream',
          'ResponseContentDisposition' => 'attachment; filename=file2.jpg',
      ]
  );

• Answer:
  當使用 s3 driver 時, 可使用 temporaryUrl() 產生一個暫時的 url, arg2 可指定失效時間, arg3 可指定 s3 的其他 request parameters

# URL Host Customization

以下的 Laravel example code 的意思是？

• Example:

  <?php
  'public' => [
      'driver' => 'local',
      'root' => storage_path('app/public'),
      'url' => env('APP_URL').'/storage',
      'visibility' => 'public',
  ],

• Answer:
  可在 ‘url’ 選項定義產生的 url 的 host

# File Metadata

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use Illuminate\Support\Facades\Storage;
  
  $size = Storage::size('file.jpg');

• Answer:
  取得該 file 的大小

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $time = Storage::lastModified('file.jpg');

• Answer:
  取得 last modified time, 格式為 UNIX timestamp

# File Paths

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use Illuminate\Support\Facades\Storage;
  
  $path = Storage::path('file.jpg');

• Answer:
  取得 local file 的 absolute path, 如果使用 s3, 會取得 s3 bucket 的 relative path

# Storing Files

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use Illuminate\Support\Facades\Storage;
  
  Storage::put('file.jpg', $contents);
  
  Storage::put('file.jpg', $resource);

• Answer:
  將內容寫到檔案, 或將檔案存到指定資料夾
  也可使用 PHP resource, 如下 demonstration
• Demonstration:

  <?php
  $userUpload = $request->file('fileName');
  $resource = fopen( $userUpload->getRealPath(), 'r');
  Storage::put('path/to/save/the/file', $resource);

# Automatic Streaming

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use Illuminate\Http\File;
  use Illuminate\Support\Facades\Storage;
  
  $path = Storage::putFile('photos', new File('/path/to/photo'));
  
  $path = Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');

• Answer:
  使用 putFile 或 putFileAs 指定儲存路徑, 檔案來源, 以及檔名 (若不指定會自動產生 Unique ID), 並 return 儲存位置的 path 包括檔名
  會採用 stream 的方式儲存檔案

以下的 Laravel example code 的意思是？

• Example:

  <?php
  Storage::putFile('photos', new File('/path/to/photo'), 'public');

• Answer:
  使用 putFile 指定儲存路徑以及檔案來源, arg3 為該檔案是否可被公開存取, public 表示可以

# Prepending & Appending To Files

以下的 Laravel example code 的意思是？

• Example:

  <?php
  Storage::prepend('file.log', 'Prepended Text');
  
  Storage::append('file.log', 'Appended Text');

• Answer:
  可以 prepend(開頭) 或 append(結尾) 內容寫入到指定的 file

# Copying & Moving Files

以下的 Laravel example code 的意思是？

• Example:

  <?php
  Storage::copy('old/file.jpg', 'new/file.jpg');
  
  Storage::move('old/file.jpg', 'new/file.jpg');

• Answer:
  使用 copy() 來複製檔案
  使用 move() 來移動檔案或重新命名檔案

# File Uploads

以下的 Laravel example code 的意思是？

• Example:

  <?php
  
  namespace App\Http\Controllers;
  
  use App\Http\Controllers\Controller;
  use Illuminate\Http\Request;
  
  class UserAvatarController extends Controller
  {
      public function update(Request $request)
      {
          $path = $request->file('avatar')->store('avatars');
  
          return $path;
      }
  }

• Answer:
  使用 store(), 將 file avatar 存到位置 avatars, 因為沒有指定檔名, 所以會自動產生 Unique ID, 會回傳包含檔名的 path

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $path = Storage::putFile('avatars', $request->file('avatar'));

• Answer:
  使用 store(), 將 file avatar 存到位置 avatars, 因為沒有指定檔名, 所以會自動產生 Unique ID, 會回傳包含檔名的 path

# Specifying A File Name

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $path = $request->file('avatar')->storeAs(
      'avatars', $request->user()->id
  );

• Answer:
  使用 storeAs(), 將 file avatar 存到位置 avatars, 並指定檔名為 $request->user()->id, 會回傳包含檔名的 path

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $path = Storage::putFileAs(
      'avatars', $request->file('avatar'), $request->user()->id
  );

• Answer:
  使用 putFileAs(), 將 file avatar 存到位置 avatars, 並指定檔名為 $request->user()->id, 會回傳包含檔名的 path

# Specifying A Disk

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $path = $request->file('avatar')->store(
      'avatars/'.$request->user()->id, 's3'
  );

• Answer:
  使用 store() 將 file avatar 存到 s3 disk, 路徑為 'avatars/'.$request->user()->id

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $path = $request->file('avatar')->storeAs(
      'avatars',
      $request->user()->id,
      's3'
  );

• Answer:
  使用 storeAs(), arg1 為 disk 內路徑, arg2 為檔名, arg3 為要使用的 disk

# Other Uploaded File Information

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $name = $request->file('avatar')->getClientOriginalName();

• Answer:
  取得上傳檔案原本的 name

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $extension = $request->file('avatar')->extension();

• Answer:
  取得上傳檔案的 extension

# File Visibility

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use Illuminate\Support\Facades\Storage;
  
  Storage::put('file.jpg', $contents, 'public');

• Answer:
  將 $content 寫 到 default disk 的 'file.jpg', 並定義 visibility 為 public, 即可公開被存取

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $visibility = Storage::getVisibility('file.jpg');
  
  Storage::setVisibility('file.jpg', 'public');

• Answer:
  取得該檔案的 visibility
  設定該檔案的 visibility

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $path = $request->file('avatar')->storePublicly('avatars', 's3');
  
  $path = $request->file('avatar')->storePubliclyAs(
      'avatars',
      $request->user()->id,
      's3'
  );

• Answer:
  儲存檔案並設定 visibility, 檔名自動產生
  儲存檔案並設定 visibility, 指定檔名為 $request->user()->id

# Local Files & Visibility

以下位於 config/filesystem.php 的 Laravel example code 的意思是？

• Example:

  <?php
  'local' => [
      'driver' => 'local',
      'root' => storage_path('app'),
      'permissions' => [
          'file' => [
              'public' => 0664,
              'private' => 0600,
          ],
          'dir' => [
              'public' => 0775,
              'private' => 0700,
          ],
      ],
  ],

• Answer:
  當使用 local driver 時, visibility 設為 public 時, 資料夾為 755, 檔案為 644, 可在 config/filesystem.php 自定義

# Deleting Files

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use Illuminate\Support\Facades\Storage;
  
  Storage::delete('file.jpg');
  
  Storage::delete(['file.jpg', 'file2.jpg']);

• Answer:
  刪除 default disk 內的檔案, 一個或多個

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use Illuminate\Support\Facades\Storage;
  
  Storage::disk('s3')->delete('path/file.jpg');

• Answer:
  刪除 s3 disk 中的指定檔案

# Directories

# Get All Files Within A Directory

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use Illuminate\Support\Facades\Storage;
  
  $files = Storage::files($directory);
  
  $files = Storage::allFiles($directory);

• Answer:
  files() 取得 $directory 中所有的 files
  allFiles() 取得 $directory 中所有的 files, 包含 subdirectories 內的 files

# Get All Directories Within A Directory

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $directories = Storage::directories($directory);
  
  $directories = Storage::allDirectories($directory);

• Answer:
  directories() 取得 $directory 內所有的 directories
  allDirectories() 取得 $directory 內所有的 directories, 包含 subdirectories

# Create A Directory

以下的 Laravel example code 的意思是？

• Example:

  <?php
  Storage::makeDirectory($directory);

• Answer:
  makeDirectory() 建立 $directory, 包含所有子目錄

# Delete A Directory

以下的 Laravel example code 的意思是？

• Example:

  <?php
  Storage::deleteDirectory($directory);

• Answer:
  刪除 $directory

# Custom Filesystems

以下的 Laravel example code 的意思是？

• Example:

  <?php
  composer require spatie/flysystem-dropbox

• Answer:
  若要使用 custom filesystem, 需安裝 adaptor

以下的 Laravel example code 的意思是？

• Example:

  <?php
  
  namespace App\Providers;
  
  use Illuminate\Support\Facades\Storage;
  use Illuminate\Support\ServiceProvider;
  use League\Flysystem\Filesystem;
  use Spatie\Dropbox\Client as DropboxClient;
  use Spatie\FlysystemDropbox\DropboxAdapter;
  
  class AppServiceProvider extends ServiceProvider
  {
      public function register()
      {
          //
      }
  
      public function boot()
      {
          Storage::extend('dropbox', function ($app, $config) {
              $client = new DropboxClient(
                  $config['authorization_token']
              );
  
              return new Filesystem(new DropboxAdapter($client));
          });
      }
  }

• Answer:
  在 AppServiceProvider 的 boot() 中註冊 custom filesystem
  extend() 的 arg1 為 custom filesystem name, arg2 為 closure, 需 return 一個 Filesystem class
  $config 為定義在 config/filesystems.php 的資料