Getting started with Simpletools\Cloud

Requirements

Simpletools framework requires PHP version >= 5.3.0

Installation

To see how to install \Simpletools framework please click here.

To use \Simpletools\Cloud you also need to install each platform's client e.g. Google Cloud Platform:

composer require google/cloud

Configuration

To enable Simpletools\Cloud you just need to pass access keys as per each platform's client requirements e.g. for Google Cloud Platform:

Simpletools\Cloud\Google\Client::settings($settings);

Initialise File Object

To initialise your cloud file for read or writes you just need to provide an appropriate path to it as a first construct method argument and optionally to set extra meta info you can provide 2nd argument as an array.

The path argument should correspond to the following URI pattern:

{protocol}://{bucket}/{fileKey}

For example, to initialize Google Cloud Storage based file:

$file = new \Simpletools\Cloud\File("gs://my-bucket/path/to/my/file.txt");

Read from a File

To return content of the file as a string

$file = new \Simpletools\Cloud\File("gs://my-bucket/path/to/my/file.txt");
print $file->getBody();

To return a file pointer with read flag to the file

$file = new \Simpletools\Cloud\File("gs://my-bucket/path/to/my/file.txt");
$handle = $file->getHandler('r');
while (!feof($handle)) {
    print fread($handle, 8192);
}

Write to a File

To write a string to a file

$file = new \Simpletools\Cloud\File("gs://my-bucket/path/to/my/file.txt");
$file->setBody("My text")
     ->save();

To return a file pointer with write flag to the file

$file = new \Simpletools\Cloud\File("gs://my-bucket/path/to/my/file.txt");
$handle = $file->getHandler('w');
fwrite($handle,"My text");
$file->save();

Append to a File

Please note that appending to large files might be time consuming as time is needed to download them first into a local filesystem.

To append a string to a file

$file = new \Simpletools\Cloud\File("gs://my-bucket/path/to/my/file.txt");
$file->appendBody("My appended text")
     ->save();

To return a file pointer with append flag to the file

$file = new \Simpletools\Cloud\File("gs://my-bucket/path/to/my/file.txt");
$handle = $file->getHandler('a');
fwrite($handle,"My appended text");
$file->save();

Saving File Changes

In order to commit your changes to Cloud Platform Storage the following method needs to be invoked

$file->save();

Delete a File

In order to delete a file from Cloud Platform Storage the following method needs to be invoked

$file->delete();

Rename a File

In order to rename a file under Cloud Platform Storage the following method needs to be invoked

$file->renameTo('gs://my-bucket/path/to/my/my-new-file.txt');

Read JSON from a File

To return body as JSON object

$file = new \Simpletools\Cloud\File("gs://my-bucket/path/to/my/file.json");
var_dump($file->getJson());

Write JSON to a File

To write object or an array as JSON into file

$file = new \Simpletools\Cloud\File("gs://my-bucket/path/to/my/file.json");
$file->setJson([
    "key"   => "value"
])->save();

Setting up base path protocol

To simplify file initialisation and possible refactoring or storage platform migration in future, default protocol can be set instead of specifying one each time

\Simpletools\Cloud\File::setBaseProtocol('gs');

After that line files can be initialised without the protocol in the path e.g.

$file = new \Simpletools\Cloud\File("//my-bucket/path/to/my/file.txt");

*if protocol is presented in the path it will be prioritised over the base one

Setting up Bucket Prefix

To enable debugging or development environment and to prevent production files overwrite you can set bucket prefix option, basically once set, each path provided during the file initialisation will get bucket name prepended with provided string.

To set it up see example below:

\Simpletools\Cloud\File::setBucketPrefix('dev-');

Setting up Bucket Suffix

To enable debugging or development environment and to prevent production files overwrite you can set bucket suffix option, basically once set, each path provided during the file initialisation will get bucket name appended with provided string.

To set it up see example below:

\Simpletools\Cloud\File::setBucketSuffix('-dev');

Initialise Bucket Object

To initialise your cloud bucket you just need to provide an appropriate path to it as a first construct method argument.

The path argument should correspond to the following URI pattern:

{protocol}://{bucket}/

For example, to initialize Google Cloud Storage based bucket:

$bucket = new \Simpletools\Cloud\Bucket("gs://my-bucket/");

Search Files

To return list of cloud files matching prefix

$bucket = new \Simpletools\Cloud\Bucket("gs://my-bucket/");
$files  = $bucket->search([
    'prefix'    => 'path/to'
]);

foreach($files as $file){
    print $file->getBody();
}

Setting up base path protocol

To simplify bucket initialisation and possible refactoring or storage platform migration in future, default protocol can be set instead of specifying one each time

\Simpletools\Cloud\Bucket::setBaseProtocol('gs');

After that line buckets can be initialised without the protocol in the path e.g.

$file = new \Simpletools\Cloud\Bucket("//my-bucket/");

*if protocol is presented in the path it will be prioritised over the base one

Setting up Bucket Prefix

To enable debugging or development environment and to prevent production bucket overwrite you can set bucket prefix option, basically once set, each path provided during the bucket initialisation will get bucket name prepended with provided string.

To set it up see example below:

\Simpletools\Cloud\Bucket::setBucketPrefix('dev-');

Setting up Bucket Suffix

To enable debugging or development environment and to prevent production bucket overwrite you can set bucket suffix option, basically once set, each path provided during the bucket initialisation will get bucket name appended with provided string.

To set it up see example below:

\Simpletools\Cloud\Bucket::setBucketSuffix('-dev');