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/publicpublic/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 的資料

Laravel - Digging Deeper - Helpers Recursion - 建立一個 N-level category tree

留言

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×