Advanced File Management

Permissions, caching and metadata options

You may need to write files using stream options. If so, you can specify the following options when configuring your stream:

The following snippet shows how to use stream options:

$options = ['gs' => ['Content-Type' => 'text/plain']];
$ctx = stream_context_create($options);
file_put_contents('gs://my_bucket/hello.txt', 'Hello', 0, $ctx);

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 filesystem functions support on Google Cloud Storage

Many of the native PHP filesystem functions are fully supported, but some are not, and still others 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.

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

Using PHP include and require

To help maintain the security of your application, the ability to include or require from a GCS 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 GCS using file_put_contents() , along with the metadata and content type:

// set metadata
$options = [
  'gs' => [
        'Content-Type' => 'text/plain',
        'metadata' => ['foo' => 'far', 'bar' => 'boo'],
  ],
];
$ctx = stream_context_create($options)
file_put_contents('gs://foo/bar', $ctx);

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.

// read content type and metadata
$fp = fopen('gs://foo/bar', 'r');
$content_type = CloudStorageTools::getContentType($fp);
var_dump($content_type);
$metadata = CloudStorageTools::getMetaData($fp);
var_dump($metadata);

/* expected output:

text/plain

array(2) {
  ['foo']=>
  string(3) 'far'
  ['bar']=>
  string(3) 'boo'
}
*/

Cached file reads

By default, the GCS stream wrapper 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.

$ctx = [
  'gs' => [
    'enable_cache' => true,
    'enable_optimistic_cache' => true,
    'read_cache_expiry_seconds' => 300,
  ]
];
// Use $ctx for the stream context and do read operation...

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .