Presentation
Installation
- Installation with Composer
- Manual installation
Configuration
Storing files on S3
Unified calls
Specific calls
- getUrl()

Data source: S3

1Presentation

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 etc/temma.php 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 S3 connection is accessible by writing:

$loader->dataSources['s3']

2Installation

To connect to AWS (Amazon Web Services), Temma needs access to the AWS PHP SDK. This can be done by installing it with Composer, or by installing it manually.

2.1Installation with Composer

To install the AWS PHP SDK with Composer, simply type this command from the project root:

$ composer require aws/aws-sdk-php

2.2Manual installation

To install the AWS PHP SDK manually, download the aws.phar file and place it in the project's lib/ directory. For example, by running the following command:

$ wget -O lib/aws.phar https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar

You can also choose to install the AWS PHP SDK at system level, so you don't have to reinstall it for each project. To do this, simply copy the aws.phar file to a directory that is part of the include paths, such as /usr/share/php (instead of putting it in your project's lib/ directory).

3Configuration

In the etc/temma.php 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

4Storing 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.

5Unified calls

5.1Array-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);

5.2General 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();

5.3Management 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);

5.4Raw 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
$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',
]);

6Specific calls

6.1getUrl()

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:

// retrieve the temporary URL
$url = $this->s3->getUrl('documents/report.pdf');

// redirection to this URL
$this->_redirect($url);