API Documentation

\google\appengine\api\cloud_storage\CloudStorageTools

FINAL

CloudStorageTools allows the user to create and serve data with Google Cloud Storage.

Constants

GS_PREFIX

BLOB_KEY_HEADER

BLOB_RANGE_HEADER

MAX_IMAGE_SERVING_SIZE

LOCAL_ENDPOINT

PRODUCTION_HOST_SUBDOMAIN_FORMAT

PRODUCTION_HOST_PATH_FORMAT

GS_FILENAME_FORMAT

MAX_URL_EXPIRY_TIME_SECONDS

GS_DEFAULT_BUCKET_KEYWORD

GS_DEFAULT_BUCKET_APC_KEY

Methods

createUploadUrl

STATIC   

createUploadUrl(string  $success_path, array<mixed,mixed>  $options = array()) : string

Create an absolute URL that can be used by a user to asynchronously upload a large blob. Upon completion of the upload, a callback is made to the specified URL.

Parameters

Name	Description
$success_path	string A relative URL which will be invoked after the user successfully uploads a blob.
$options	array<mixed,mixed> A key value pair array of upload options. Valid options are: 'max_bytes_per_blob': integer The value of the largest size that any one uploaded blob may be. Default value: unlimited. 'max_bytes_total': integer The value that is the total size that sum of all uploaded blobs may be. Default value: unlimited. 'gs_bucket_name': string The name of a Google Cloud Storage bucket that the blobs should be uploaded to. Not specifying a value will result in the blob being uploaded to the application's default bucket. 'url_expiry_time_seconds': integer The number of seconds that the generated URL can be used for to upload files to Google Cloud Storage. Once this timeout expires, the URL is no longer valid and any attempts to upload using the URL will fail. Must be a positive integer, maximum value is one day (86400 seconds). Default Value: 600 seconds.

Throws

\InvalidArgumentException

If $success_path is not valid, or one of the options is not valid.

\google\appengine\api\cloud_storage\CloudStorageException

Thrown when there is a failure using the blobstore service.

Returns

string

The upload URL.

getImageServingUrl

STATIC   

getImageServingUrl(string  $gs_filename, array<mixed,mixed>  $options = array()) : string
         

Returns a URL that serves an image.

Parameters

Name	Description
$gs_filename	string The name of the Google Cloud Storage object to serve. In the format gs://bucket_name/object_name
$options	array<mixed,mixed> Array of additional options for serving the object. Valid options are: 'crop': boolean Whether the image should be cropped. If set to true, a size must also be supplied. Default value: false. 'secure_url': boolean Whether to request an https URL. Default value: false. 'size': integer The size of the longest dimension of the resulting image. Size must be in the range 0 to 1600, with 0 specifying the size of the original image. The aspect ratio is preserved unless 'crop' is specified. If you do not specify the size argument and the image has a dimension that is greater than 512 pixels, the API resizes the largest dimension to 512 pixels and scales the smaller dimension accordingly to match the original image's aspect ratio.

Throws

\InvalidArgumentException

if any of the arguments are not valid.

\google\appengine\api\cloud_storage\CloudStorageException

If there was a problem contacting the service.

Returns

string

The image serving URL.

deleteImageServingUrl

STATIC   

deleteImageServingUrl(string  $gs_filename) 
         

Deletes an image serving URL that was created using getImageServingUrl.

Parameters

Name	Description
$gs_filename	string The name of the Google Cloud Storage object that has an existing URL to delete. In the format gs://bucket_name/object_name

Throws

\InvalidArgumentException

if any of the arguments are not valid.

\google\appengine\api\cloud_storage\CloudStorageException

If there was a problem contacting the service.

getPublicUrl

STATIC   

getPublicUrl(string  $gs_filename, boolean  $use_https) : string
         

Get the public URL for a Google Cloud Storage filename.

Parameters

Name	Description
$gs_filename	string The Google Cloud Storage filename, in the format gs://bucket_name/object_name.
$use_https	boolean If True then return a HTTPS URL. Note that the development server ignores this argument and returns only HTTP URLs.

Throws

\InvalidArgumentException

if the filename is not in the correct format or $use_https is not a boolean.

Returns

string

The public URL.

getFilename

STATIC   

getFilename(string  $bucket, string  $object) : string
         

Get the filename of a Google Cloud Storage object.

Parameters

Name	Description
$bucket	string The Google Cloud Storage bucket name.
$object	string The Google Cloud Storage object name.

Throws

\InvalidArgumentException

if bucket or object name is invalid.

Returns

string

The filename in the format gs://bucket_name/object_name.

parseFilename

STATIC   

parseFilename(string  $filename,   $bucket,   $object) : boolean
         

Parse and extract the bucket and object names from the supplied filename.

Parameters

Name	Description
$filename	string The filename in the format gs://bucket_name or gs://bucket_name/object_name.
$bucket
$object

Returns

boolean

true if the filename is successfully parsed, false otherwise.

serve

STATIC   

serve(string  $gs_filename, array<mixed,mixed>  $options = array()) 
         

Serve a Google Cloud Storage file as the response.

Parameters

Name	Description
$gs_filename	string The name of the Google Cloud Storage object to serve.
$options	array<mixed,mixed> Array of additional options for serving the object. 'content_type': string Content-Type to override when known. 'save_as': boolean If True then send the file as an attachment. 'start': int Start index of content-range to send. 'end': int End index of content-range to send. End index is inclusive. 'use_range': boolean Use provided content range from the request's Range header. Mutually exclusive with start and end.

Throws

\InvalidArgumentException

If invalid options are supplied.

getDefaultGoogleStorageBucketName

STATIC   

getDefaultGoogleStorageBucketName() : string
         

Return the name of the default Google Cloud Storage bucket for the application, if one has been configured.

Returns

string

The bucket name, or an empty string if no bucket has been configured.

setSendHeaderFunction

STATIC   

setSendHeaderFunction(mixed  $new_header_func) 
         

This function is used for unit testing only, it allows replacement of the send_header function that is used to set headers on the response.

Parameters

Name	Description
$new_header_func	mixed The function to use to set response headers. Set to null to use the inbuilt PHP method header().

getMetaData

STATIC   

getMetaData(resource  $handle) : array
         

Get metadata from a Google Cloud Storage file pointer resource.

Parameters

Name	Description
$handle	resource A Google Cloud Storage file pointer resource that is typically created using fopen().

Throws

\InvalidArgumentException

If $handler is not a Google Cloud Storage file pointer resource.

Returns

array

An array that maps metadata keys to values.

getContentType

STATIC   

getContentType(resource  $handle) : string
         

Get content type from a Google Cloud Storage file pointer resource.

Parameters

Name	Description
$handle	resource A Google Cloud Storage file pointer resource that is typically created using fopen().

Throws

\InvalidArgumentException

If $handler is not a Google Cloud Storage file pointer resource.

Returns

string

The content type of the Google Cloud Storage object.