注意：PHP 5 已于 2024 年 1 月 30 日达到支持终止期限。现有的 PHP 5 应用将继续运行并接收流量。但是，App Engine 可能会阻止重新部署使用支持终止日期之后的运行时的应用。我们建议您迁移到最新支持的 PHP 版本。

高级 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 - 打开文件或网址。	受支持。	仅支持以下模式：`r`、`rb`、`rt`、`w`、`wb`、`wt`。
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_exists、filemtime、filesize、fstat、is_file、is_dir、is_writable 和 stat）基于每个请求进行缓存。您可以通过调用 clearstatcache 清除此缓存。

此外，还支持以下 PHP 目录读取函数：

函数名称
`opendir`
`readdir`
`rewinddir`
`closedir`

使用 PHP 5 `include` 和 `require`

为了帮助维护应用的安全性，Cloud Storage 文件的 include 或 require 功能会默认停用，但您可以按如下方法启用该功能：

如需在应用中 include 或 require 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);