PHP 5 進階檔案管理

權限、快取與中繼資料選項

Cloud Storage 適用的 App Engine 串流包裝函式提供下列串流設定選項:

選項 可能的值 說明
acl 值為下列其中之一:
  • private
  • public-read
  • public-read-write
  • authenticated-read
  • bucket-owner-read
  • bucket-owner-full-control
  • project-private
想瞭解這些設定在 Cloud Storage 中的作用,請參閱預先定義的 ACL 一節。如果您未設定 acl,Cloud Storage 會將這項參數設為 null,並使用與檔案所在值區相關聯的預設物件 ACL
Content-Type 任何有效的 MIME 類型 如果您在上傳物件時沒有指定內容類型,Google Cloud Storage 系統會在提供物件時將內容類型預設為 binary/octet-stream
Content-Disposition 任何有效的內容配置值 您可針對物件設定的標頭,用於指定物件資料如何傳送的陳述資訊。
Content-Encoding 任何有效的壓縮演算法 物件的壓縮演算法,例如 gzip。請注意,Google Cloud Storage 不會依據這個標頭自動壓縮或解壓縮物件。
Content-Language 任何有效的 ISO 639-1 語言代碼 內容的 ISO 639-1 語言代碼 (如需完整清單,請參閱表示語言名稱的代碼表)。
enable_cache true 或 false (預設為 true) 系統會將從 Cloud Storage 讀取的檔案快取到記憶體 (請參閱 Memcache 總覽) 以提高效能。如要關閉快取,請在串流結構定義中使用 enable_cache 指令。
enable_optimistic_cache true 或 false (預設為 false) 您可以啟用樂觀快取,從快取中讀取檔案物件,無需檢查 Cloud Storage 中的基礎物件自前次快取後是否發生變更。樂觀快取非常適合一次寫入、多次讀取的情境。
metadata 關聯陣列,例如 ['foo' => 'far', 'bar' => 'boo'],請參閱讀取及寫入自訂中繼資料一節。
read_cache_expiry_seconds 物件在快取中保持有效的秒數。 您可以使用 read_cache_expiry_seconds directive 變更快取物件保持有效的時間長度。這個選項會指定時間值,經過指定時間值後,系統會在下次嘗試讀取時重新快取物件。預設值為 1 小時 (3600)。
writable_cache_expiry_seconds 快取值區可寫入狀態的秒數。 Cloud Storage 串流包裝函式會快取值區的可寫入狀態,以提高效能。這表示當值區的 ACL 變更時,各種 stat() 相關函式傳回的可寫入位元可能會暫時無法同步。預設值為 10 分鐘 (600)。

下列程式碼片段顯示如何使用串流選項:

$options = ['gs' => ['Content-Type' => 'text/plain']];
$context = stream_context_create($options);
file_put_contents("gs://${my_bucket}/hello_options.txt", $newFileContent, 0, $context);

在上方的程式碼片段中,$options 是串流在寫入新物件時使用的一組引數,您可以使用 stream_context_set_default 將其設為預設選項。

Cloud Storage 上的 PHP 5 檔案系統函式支援

Cloud Storage 適用的 App Engine 串流包裝函式支援許多原生的 PHP 檔案系統函式,但部分函式不受支援,還有部分函式經過修改後支援。下表列出各個原生函式,並指出系統是否支援。如果函式受到支援但需修改或有所限制,亦會提供說明。

檔案系統函式 是否支援? 說明
basename - 傳回路徑的後置名稱元件。 支援。
chgrp - 變更檔案群組。 不支援。 一律傳回 false
chmod - 變更檔案模式。 不支援。 一律傳回 false
chown - 變更檔案擁有者。 不支援。 一律傳回 false
clearstatcache - 清除檔案狀態快取。 支援。
copy - 複製檔案。 支援。
dirname - 傳回上層目錄路徑。 支援。 支援但加入 gs:// 前置字串。
disk_free_space - 傳回檔案系統或磁碟分區中的可用空間。 不支援。 已停用。
disk_total_space - 傳回檔案系統或磁碟分區的總大小。 不支援。 已停用。
diskfreespace - disk_free_space 的別名。
fclose - 關閉開啟的檔案指標。 支援。
feof - 測試檔案指標的檔案結尾。 支援。
fflush - 將輸出排清到檔案。 支援。 沒有影響 (一律傳回 true)。
fgetc - 從檔案指標取得字元。 支援。
fgetcsv - 從檔案指標取得行並剖析 CSV 欄位。 支援。
fgets - 從檔案指標取得行。 支援。
fgetss - 從檔案指標取得行,並去除 HTML 標記。 支援。
file_exists - 檢查檔案或目錄是否存在。 支援。
file_get_contents - 將整個檔案讀入字串。 支援。
file_put_contents - 將字串寫入檔案。 支援。
file - 將整個檔案讀入陣列。 支援。
fileatime - 取得檔案的前次存取時間。 不支援。 一律傳回 0。
filectime - 取得檔案的 inode 變更時間。 不支援。 一律傳回 0。
filegroup - 取得檔案群組。 不支援。 一律傳回 0。
fileinode - 取得檔案 inode。 不支援。 一律傳回 0。
filemtime - 取得檔案修改時間。 支援。
fileowner - 取得檔案擁有者。 不支援。 一律傳回 0。
fileperms - 取得檔案權限。 支援。 執行位元一律關閉。
filesize - 取得檔案大小。 支援。
filetype - 取得檔案類型。 支援。
flock - 可攜性建議檔案鎖定。 不支援。 一律傳回 false
fopen - 開啟檔案或網址。 支援。 只支援以下模式:rrbrtwwbwt
fpassthru - 輸出檔案指標的所有剩餘資料。 支援。
fputcsv - 將行格式化為 CSV 並寫入檔案指標。 支援。
fputs - fwrite 的別名。
fread - 讀取二進位安全檔案。 支援。
fscanf - 依據格式剖析檔案的輸入。 支援。
fseek - 使用檔案指標搜尋。 支援。 只支援使用讀取模式開啟的檔案。
fstat - 使用開啟的檔案指標取得檔案相關資訊。 支援。
ftell - 傳回檔案讀取/寫入指標的當前位置。 支援。
ftruncate - 將檔案截斷成指定長度。 不支援。 一律傳回 false
fwrite - 二進位安全檔案寫入。 支援。
glob - 尋找符合模式的路徑名稱。 支援。
is_dir - 告知檔案名稱是否為目錄。 支援。
is_executable - 告知檔案名稱是否為可執行檔。 不支援。 一律傳回 false
is_file - 告知檔案名稱是否為一般檔案。 支援。
is_link - 告知檔案名稱是否為符號連結。 不支援。 一律傳回 false
is_readable - 告知檔案是否存在,以及是否可以讀取。 支援。
is_uploaded_file - 告知是否透過 HTTP POST 上傳檔案。 支援。
is_writable - 告知檔案名稱是否可寫入。 支援。 系統會快取值,但該值未必能立即反映權限變更。
is_writeable - is_writable 的別名。
lchgrp - 變更符號連結的群組擁有權。 不支援。 已停用。
lchown - 變更符號連結的使用者擁有權。 不支援。 已停用。
link - 建立硬連結。 不支援。 已停用。
linkinfo - 取得連結的相關資訊。 不支援。 一律傳回 -1
lstat - 提供檔案或符號連結的相關資訊。 支援。
mkdir - 建立目錄。 支援。
move_uploaded_file - 將上傳的檔案移至新位置。 支援。
parse_ini_file - 剖析設定檔。 支援。
pathinfo - 傳回檔案路徑的相關資訊。 支援。
pclose - 關閉處理檔案指標。 不支援。 已停用。
popen - 開啟處理檔案指標。 不支援。 已停用。
readfile - 輸出檔案。 支援。
readlink - 傳回符號連結的目標。 不支援。 一律傳回 false
realpath - 傳回標準化絕對路徑名稱。 不支援。 一律傳回 false
rename - 重新命名檔案或目錄。 支援。
rewind - 倒轉檔案指標的位置。 支援。 僅支援讀取模式。
rmdir - 移除目錄。 支援。
set_file_buffer - stream_set_write_buffer 的別名。
stat - 提供檔案相關資訊。 支援。
symlink - 建立符號連結。 不支援。 已停用。
tempnam - 使用不重複的檔案名稱建立檔案。 支援。 請參閱這些附註
tmpfile - 建立暫存檔案。 支援。 傳回類似 php://memory 的記憶體備份檔案。
touch - 設定檔案的存取和修改時間。 不支援。 一律傳回 false
umask - 變更當前的 umask。 支援。 不適用於 Cloud Storage 檔案。
unlink - 刪除檔案。 支援。

請注意,上表中的檔案統計函式 (file_existsfilemtimefilesizefstatis_fileis_diris_writablestat) 是依要求快取。您可以呼叫 clearstatcache 以清除這個快取。

此外,系統也支援以下 PHP 目錄讀取函式:

函式名稱
opendir
readdir
rewinddir
closedir

使用 PHP 5 includerequire

根據預設,為協助維持應用程式的安全性,系統會停用 Cloud Storage 檔案的 includerequire 功能,但您可以按照下列指示加以啟用:

如要在應用程式中 includerequire Google Cloud Storage 的 PHP 程式碼,您必須在 php.ini 檔案中使用 google_app_engine.allow_include_gs_buckets 指令,藉此指定哪些值區含有這些檔案。

讀取及寫入自訂中繼資料

如要將自訂中繼資料附加至要寫入 Google Cloud Storage 的檔案,請先將中繼資料新增至 $options,然後再建立用於 file_put_contents 呼叫的串流結構定義。

在本例中,名稱為 foo 的中繼資料具有指定值 far,而另一個名稱為 bar 的中繼資料則具有指定值 boo。本例也會將內容類型設為 text/plain。串流結構定義是使用 $options 中的這項資訊所建立 (如範例所示),並使用 file_put_contents() 及中繼資料和內容類型將檔案寫入 Cloud Storage:

$metadata = ['foo' => 'bar', 'baz' => 'qux'];
$options = [
    'Content-Type' => 'text/plain',
    'metadata' => $metadata
];
$context = stream_context_create(['gs' => $options]);
file_put_contents("gs://${my_bucket}/hello_metadata.txt", $newFileContent, 0, $context);

如要讀取檔案的自訂中繼資料和內容類型,請對該檔案呼叫 fopen,然後使用 CloudStorageTools::getContentType() 來取得內容類型,並利用 CloudStorageTools::getMetaData() 取得中繼資料。

只要 fopen 呼叫傳回檔案指標,您就能取得自訂中繼資料和內容類型。

$fp = fopen("gs://${my_bucket}/hello_metadata.txt", 'r');
$content_type = CloudStorageTools::getContentType($fp);
$metadata = CloudStorageTools::getMetaData($fp);

快取檔案讀取

根據預設,Cloud Storage 適用的 App Engine 串流包裝函式會將檔案讀取內容快取至 Memcache,以提高後續讀取的效能。如要關閉快取,請在串流結構定義中使用 enable_cache 指令。

如要更進一步提高效能,您還可以使用 enable_optimistic_cache 指令 (預設為 false) 啟用樂觀快取,這項功能會從快取中讀取檔案物件,而不檢查 Google Cloud Storage 中的基礎物件自前次快取後是否發生過變更。樂觀快取非常適合一次寫入、多次讀取的情境。

您也可以使用 read_cache_expiry_seconds 指令,變更快取物件維持有效的時間長度,經過這段時間後,系統會在下次嘗試讀取時重新快取物件。預設值為 1 小時 (3600)。

在本例中,樂觀快取已開啟,檔案物件設定為標示在 5 分鐘後從 Google Cloud Storage 重新快取。

$options = [
    'gs' => [
        'enable_cache' => true,
        'enable_optimistic_cache' => true,
        'read_cache_expiry_seconds' => 300,
    ]
];
$context = stream_context_create($options);
file_put_contents("gs://${my_bucket}/hello_caching.txt", $newFileContent, 0, $context);
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
PHP 5 適用的 App Engine 標準環境