高级 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 秒）。

以下代码段介绍了如何使用数据流选项：

appengine/php55/storage/app.php 
$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：

appengine/php55/storage/app.php 
$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 调用返回文件指针后，即可获得自定义元数据和内容类型。

appengine/php55/storage/app.php 
$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 重新缓存。

appengine/php55/storage/app.php 
$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);