Advanced PHP 5 File Management

This API is supported for first-generation runtimes and can be used when upgrading to corresponding second-generation runtimes. If you are updating to the App Engine PHP 7/8 runtime, refer to the migration guide to learn about your migration options for legacy bundled services.

Permissions, caching and metadata options

The App Engine stream wrapper for Cloud Storage provides the following options to configure your stream:

Option	Possible Values	Description
acl	One of the following values: private public-read public-read-write authenticated-read bucket-owner-read bucket-owner-full-control project-private	For descriptions of what these settings do in Cloud Storage, see Predefined ACLs. If you do not set acl, Cloud Storage sets this parameter as null and uses the default object ACL associated with the bucket that contains the file.
Content-Type	Any valid MIME type	If you do not specify a content type when you upload an object, the Google Cloud Storage system defaults to binary/octet-stream when it serves the object.
Content-Disposition	Any valid content disposition value	A header you can set on an object that specifies presentational information about how the object data is to be transmitted.
Content-Encoding	Any valid compression algorithm	The compression algorithm for the object, such as gzip. Note that Google Cloud Storage does not automatically compress or decompress objects based on this header.
Content-Language	Any valid ISO 639-1 language code	The ISO 639-1 language code of the content (see Codes for the Representation of Names of Languages for a complete list).
enable_cache	true or false (true by default)	Files that are read from Cloud Storage are cached into memory (see memcache) for performance improvement. Caching can be turned off using the enable_cache directive in the stream context.
enable_optimistic_cache	true or false (false by default)	You can enable optimistic caching to read the file object from the cache without checking whether the underlying object was changed in Cloud Storage since the last time it was cached. Optimistic caching is ideal for write-once, read-many scenarios.
metadata	An associative array, eg.	['foo' => 'far', 'bar' => 'boo'] See Reading and writing custom metadata.
read_cache_expiry_seconds	The number of seconds that an object will remain valid in the cache	You can change the length of time that a cached object remains valid by using the read_cache_expiry_seconds directive. This specifies the time after which the object will be re-cached upon the next read attempt. By default this is set to 1 hour (3600).
writable_cache_expiry_seconds	The number of seconds that a bucket's writable state is cached	The Cloud Storage stream wrapper caches the writable state of buckets for performance improvement. This means that the writable bits returned by various stat() related functions can be temporarily out of sync when the bucket's ACL changes. By default this is set to 10 minutes (600).

The following snippet shows how to use stream options:

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

In the snippet above, $options is a set of arguments that the stream will use when writing new objects, which can be set as the default options using stream_context_set_default.

PHP 5 filesystem functions support on Cloud Storage

The App Engine stream wrapper for Cloud Storage supports many native PHP filesystem functions. Some functions are not supported, and some have modified support. The following table lists each of these native functions, indicating whether the function is supported or not. If a function is supported but with modifications or limitations, those are described.

Filesystem Function	Supported?	Details
basename — Returns trailing name component of path.	Supported.
chgrp — Changes file group.	Not supported.	Always returns false.
chmod — Changes file mode.	Not supported.	Always returns false.
chown — Changes file owner.	Not supported.	Always returns false.
clearstatcache — Clears file status cache.	Supported.
copy — Copies file.	Supported.
dirname — Returns parent directory's path.	Supported.	Supported but includes the gs:// prefix.
disk_free_space — Returns available space on filesystem or disk partition.	Not supported.	This is Disabled.
disk_total_space — Returns the total size of a filesystem or disk partition.	Not supported.	This is Disabled.
diskfreespace — Alias of disk_free_space.
fclose — Closes an open file pointer.	Supported.
feof — Tests for end-of-file on a file pointer.	Supported.
fflush — Flushes the output to a file.	Supported.	Has no effect. (Always returns true.)
fgetc — Gets character from file pointer.	Supported.
fgetcsv — Gets line from file pointer and parse for CSV fields.	Supported.
fgets — Gets line from file pointer.	Supported.
fgetss — Gets line from file pointer and strip HTML tags.	Supported.
file_exists — Checks whether a file or directory exists.	Supported.
file_get_contents — Reads entire file into a string.	Supported.
file_put_contents — Write a string to a file.	Supported.
file — Reads entire file into an array.	Supported.
fileatime — Gets last access time of file.	Not supported.	Always returns 0.
filectime — Gets inode change time of file.	Not supported.	Always returns 0.
filegroup — Gets file group.	Not supported.	Always returns 0.
fileinode — Gets file inode.	Not supported.	Always returns 0.
filemtime — Gets file modification time.	Supported.
fileowner — Gets file owner.	Not supported.	Always returns 0.
fileperms — Gets file permissions.	Supported.	The execute bit is always off.
filesize — Gets file size.	Supported.
filetype — Gets file type.	Supported.
flock — Portable advisory file locking.	Not Supported.	Always returns false.
fopen — Opens file or URL.	Supported.	Only supports these modes: r, rb, rt, w, wb, wt.
fpassthru — Output all remaining data on a file pointer.	Supported.
fputcsv — Format line as CSV and write to file pointer.	Supported.
fputs — Alias of fwrite.
fread — Binary-safe file read.	Supported.
fscanf — Parses input from a file according to a format.	Supported.
fseek — Seeks on a file pointer.	Supported.	Only supports files opened using read mode.
fstat — Gets information about a file using an open file pointer.	Supported.
ftell — Returns the current position of the file read/write pointer.	Supported.
ftruncate — Truncates a file to a given length.	Not supported.	Always returns false.
fwrite — Binary-safe file write.	Supported.
glob — Find pathnames matching a pattern.	Supported.
is_dir — Tells whether the filename is a directory.	Supported.
is_executable — Tells whether the filename is executable.	Not supported.	Always returns false.
is_file — Tells whether the filename is a regular file.	Supported.
is_link — Tells whether the filename is a symbolic link.	Not supported.	Always returns false.
is_readable — Tells whether a file exists and is readable.	Supported.
is_uploaded_file — Tells whether the file was uploaded via HTTP POST.	Supported.
is_writable — Tells whether the filename is writable.	Supported.	Value is cached and might not reflect permission changes immediately.
is_writeable — Alias of is_writable.
lchgrp — Changes group ownership of symlink.	Not supported.	This is Disabled.
lchown — Changes user ownership of symlink.	Not supported.	This is Disabled.
link — Create a hard link.	Not supported.	This is Disabled.
linkinfo — Gets information about a link.	Not supported.	Always returns -1.
lstat — Gives information about a file or symbolic link.	Supported.
mkdir — Makes directory.	Supported.
move_uploaded_file — Moves an uploaded file to a new location.	Supported.
parse_ini_file — Parse a configuration file.	Supported.
pathinfo — Returns information about a file path.	Supported.
pclose — Closes process file pointer.	Not supported.	This is Disabled.
popen — Opens process file pointer.	Not supported.	This is Disabled.
readfile — Outputs a file.	Supported.
readlink — Returns the target of a symbolic link.	Not supported.	Always returns false.
realpath — Returns canonicalized absolute pathname.	Not supported.	Always returns false.
rename — Renames a file or directory.	Supported.
rewind — Rewind the position of a file pointer.	Supported.	Supported only for read mode.
rmdir — Removes directory.	Supported.
set_file_buffer — Alias of stream_set_write_buffer.
stat — Gives information about a file.	Supported.
symlink — Creates a symbolic link.	Not supported.	This is Disabled.
tempnam — Create file with unique file name.	Supported.	See these notes.
tmpfile — Creates a temporary file.	Supported.	Returns a memory-backed file similar to php://memory.
touch — Sets access and modification time of file.	Not supported.	Always returns false.
umask — Changes the current umask.	Supported.	Does not apply to Cloud Storage files.
unlink — Deletes a file.	Supported.

Note that the file stat functions in the table above (file_exists, filemtime, filesize, fstat, is_file, is_dir, is_writable, and stat) are cached on a per-request basis. You can clear this cache by calling clearstatcache.

In addition, the following PHP directory-reading functions are supported:

Function Name
opendir
readdir
rewinddir
closedir

Note: As Cloud Storage listing operations are eventually consistent, readdir might not reflect the change immediately after an object is added, renamed or removed.

Using PHP 5 include and require

To help maintain the security of your application, the ability to include or require from a Cloud Storage file is disabled by default, but you can enable it, as follows:

To include or require PHP code from Google Cloud Storage in your application, you must specify which buckets contain those files using the google_app_engine.allow_include_gs_buckets directive in your php.ini file.

Reading and writing custom metadata

To attach custom metadata to a file being written to Google Cloud Storage, add the metadata to $options before creating the stream context used for the file_put_contents call.

In this example, metadata named foo is given the value far, and another named bar is given the value boo. The example also sets the content type to text/plain. The stream context is created using this information in $options as shown, and the file is written to Cloud Storage by using file_put_contents(), along with the metadata and content type:

$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);

To read the custom metadata and content type for a file, call fopen on the file and then use CloudStorageTools::getContentType() to get the content type and CloudStorageTools::getMetaData() to get the metadata.

The custom metadata and content type are available once you have the file pointer returned from the fopen call.

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

Cached file reads

By default, the App Engine stream wrapper for Cloud Storage caches file reads into memcache to improve performance on subsequent reads. Caching can be turned off using the enable_cache directive in the stream context.

Note: When caching is enabled, files read from Cloud Storage are cached as they are read, and the cache also contains the file information regarding writability. So, be aware that is_writable could be querying stale file information. Also, if you change the ACL on a Cloud Storage bucket to either grant or deny write permissions to the application, this change might take some time to be reflected.

For further performance improvement, you can also enable optimistic caching, which will read the file object from the cache without seeing whether the underlying object was changed in Google Cloud Storage since the last time it was cached, using the enable_optimistic_cache directive (set to false by default). Optimistic caching is ideal for write-once, read-many scenarios.

You can also change the length of time that a cached object remains valid by using the read_cache_expiry_seconds directive, after which time the object will be re-cached upon the next read attempt. By default this is set to 1 hour (3600).

In this example, optimistic caching is turned on, and file objects are configured to be marked for re-caching from Google Cloud Storage after 5 minutes.

$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);