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:
|
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:
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 |
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:
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.
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.
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.