Documentation

Data source: S3

Table of Contents 

Presentation

Amazon S3 is an inexpensive, infinite file storage space. Temma makes it easy to manipulate files stored on S3, accessing them like any other data source.

If you have correctly configured your S3 connection parameters, Temma automatically creates an object of type \Temma\Datasources\S3. By convention, we'll assume that you've named this connection s3in the temma.json file (see configuration documentation).

The connection is then available in the controller by writing:

$this->s3

In other objects managed by the dependency injection component, the database connection is accessible by writing:

$loader->dataSources['s3']

Installation

To connect to AWS (Amazon Web Services), Temma requires the aws.phar file to be downloaded and placed in the project's lib/ directory.

This file is available at https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar

It can be copied with the following command:
wget -O lib/aws.phar https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar

Configuration

In the temma.json file (see configuration documentation), you declare the DSN (Data Source Name) used to connect to S3.

The DSN used to connect to S3 is written as: s3://ACCESS_KEY:PRIVATE_KEY@REGION/BUCKET
The access key and private key are supplied by AWS.
The region is of the form "us-east-1", "eu-west-3", "ca-central-1", etc.
Example : s3://AKXYZ:PWD@eu-west-1/data.mydomain.com

Storing files on S3

By default, files registered by Temma on Amazon S3 in raw mode have the MIME type application/octet-stream, with private access.

When a file is registered, it is possible to specify another MIME type and/or a public access right.

Files saved on Amazon S3 in serialized mode always have the MIME type application/json.

Unified calls

Array-type access

// verification of file existence
if (isset($this->s3['path/key1']))
    doSomething();

// read file (deserialized)
$data = $this->s3['path/key1'];

// write file (serialized)
$this->s3['path/key1'] = $value;

// delete file
unset($this->s3['path/key1']);

// files count
$nbr = count($this->s3);

General methods

// verification of file existence
if ($this->s3->isSet('user/1'))
    doSomething();

// delete file
$this->s3->remove('user/1');

// delete multiple files
$this->s3->mRemove(['user/1', 'user/2', 'user/3']);

// delete files from a prefix
$this->s3->clear('user/');

// delete all files
$this->s3->flush();

Management of complex serialized data

// search files from a prefix
$users = $this->s3->search('user/');

// search files from a prefix, with data recovery
// (deserialized)
$users = $this->s3->search('user/', true);

// read (deserialized) file
$user = $this->s3->get('user/1');
// read file with default value
$color = $this->s3->get('color', 'blue');
// read file with file creation if needed
$user = $this->s3->get("user/$userId", function() use ($userId) {
    return $this->dao->get($userId);
});
// read file with file creation if needed,
// with public access
$user = $this->s3->get("user/$userId", function() use ($userId) {
    return $this->dao->get($userId);
}, true);

// read multiple (deserialized) files
$users = $this->s3->mGet(['user/1', 'user/2', 'user/3']);

// write (serialized) file
$this->s3->set('user/1', $userData);
// write (serialized) file with public access
$this->s3->set('user:1', $userData, true);

// write multiple (serialized) files
$this->s3->mSet([
    'user/1' => $user1data,
    'user/2' => $user2data,
    'user/3' => $user3data,
]);
// write multiple files, with public access
$this->s3->mSet([
    'user/1' => $user1data,
    'user/2' => $user2data,
], true);

Raw data management

// search files from a prefix
$colors = $this->s3->find('color/');

// search files from a prefix, with (raw) data recovery
$colors = $this->s3->find('color/', true);

// read file (raw)
$html = $this->s3->read('page/home');
// read file with default value
$html = $this->s3->read('page/home',
                        '<html><body><h1>Homepage</h1><body><html>');
// read file with file creation if needed
$html = $this->s3->read('page/home', function() {
    return file_get_contents('/path/to/homepage.html');
});

// read multiple files (raw)
$pages = $this->s3->mRead(['page/home', 'page/admin', 'page/products']);

// copy a data in a local file
$this->s3->copyFrom('page/home', '/path/to/newpage.html');
// copy data in a local file, with default value
$this->s3->copyFrom('page/home', '/path/to/newpage.html', $defaultHtml);
// copy data in a local file, with data creation if needed
$this->s3->copyFrom('page/home', '/path/to/newpage.html', function() {
    return file_get_contents('/path/to/oldpage.html');
});
// copy data in a local file, with data creation
// if needed (with a specific MIME type)
$this->s3->copyFrom('page/home', '/path/to/newpage.html', function() {
    return file_get_contents('/path/to/oldpage.html');
}, 'text/html');
// copy data in a local file, with data creation
// if needed (with public access)
$this->s3->copyFrom('page/home', '/path/to/newpage.html', function() {
    return file_get_contents('/path/to/oldpage.html');
}, true);
// copy data in a local file, with data creation
// if needed (wiith a specific MIME type and public access)
$this->s3->copyFrom('page/home', '/path/to/newpage.html', function() {
    return file_get_contents('/path/to/oldpage.html');
}, [
    'public'   => true,
    'mimetype' => 'text/html',
]);

// write file (raw)
$this->s3->write('user/1', $userData);
// write file (raw) with a specific MIME type
$this->s3->write('user:1', $userData, 'application/pdf');
// write file (raw) with public access
$this->s3->write('user:1', $userData, true);
// write file (raw) with a specific MIME type
// and public access
$this->s3->set('user:1', $userData, [
    'public'   => true,
    'mimetype' => 'application/pdf',
]);

// write multiple files (raw)
$this->s3->mWrite({
    'color/blue'  => '#0000ff',
    'color/red'   => '#ff0000',
    'color/green' => '#00ff00',
]);
// write multiple files with a specific MIME type
// écriture de plusieurs données avec un type MIME spécifique
$this->s3->mWrite({
    'color/blue'  => '#0000ff',
    'color/red'   => '#ff0000',
], 'text/plain');
// write multiple files with public access
$this->s3->mWrite({
    'color/blue'  => '#0000ff',
    'color/red'   => '#ff0000',
], true);
// write multiple files with a specific MIME type
// and public access
$this->s3->mWrite({
    'color/blue'  => '#0000ff',
    'color/red'   => '#ff0000',
], [
    'public'   => true,
    'mimetype' => 'text/plain',
]);

// write file (raw) from a local file
$this->s3->copyTo('page/home', '/path/to/homepage.html');
// write file (raw) from a local file, with a specific MIME type
$this->s3->copyTo('page/home', '/path/to/homepage.html', 'text/html');
// write file (raw) from a local file, with public access
$this->s3->copyTo('page/home', '/path/to/homepage.html', true);
// write file (raw) from a local file, with a specific MIME type
// and public access
$this->s3->copyTo('page/home', '/path/to/homepage.html', [
    'public'   => true,
    'miemtype' => 'text/html',
]);

// write multiple files (raw) from local files
$this->s3->mCopyTo([
    'page/home'     => '/path/to/homepage.html',
    'page/admin'    => '/path/to/admin.html',
    'page/products' => '/path/to/products.html',
]);
// write multiple files from local files with specific MIME type
$this->s3->mCopyTo([
    'page/home'  => '/path/to/homepage.html',
    'page/admin' => '/path/to/admin.html',
], 'text/html');
// write multiple files from local files with public access
$this->s3->mCopyTo([
    'page/home'  => '/path/to/homepage.html',
    'page/admin' => '/path/to/admin.html',
], true);
// write multiple files from local files, with specific MIME type
// and public access
$this->s3->mCopyTo([
    'page/home'  => '/path/to/homepage.html',
    'page/admin' => '/path/to/admin.html',
], [
    'public'   => true,
    'mimetype' => 'text/html',
]);

Specific calls

getUrl
getUrl(string $s3Path) : string

Basically, files stored on S3 with private access are not accessible to users who do not have an AWS account with access rights to the bucket or the file itself.

Nevertheless, it is possible to create temporary URLs, which allow access to files for a specified period of time. The getUrl() method can be used to create such "pre-signed" URLs, which are valid for 20 minutes.

These URLs are useful for offering access to files only to authenticated users on the website.

Example:

// récupération de l'URL temporaire
$url = $this->s3->getUrl('documents/report.pdf');

// redirection to this URL
$this->_redirect($url);
Previous: File
Next: Socket

Table of Contents