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

  1. Migration : How to upgrade from Temma 1.x to version 2
  2. Installation : Download Temma and install it to start your web project
  3. Configuration : All the configuration directives of the etc/temma.json file and the optional environment variables
  4. External libraries : How to use external function libraries
  5. Routing : Temma's default routing system, and advanced routing
  6. Log : Use of the log system, management by criticality levels
  7. Controllers : Essential parts of your web application
  8. Views : Smarty templates or JSON/CSV/RSS/iCal/INI exports
  9. Dependency injection : The backbone of your application developments
  10. Sessions : Extension of user sessions managed by PHP
  11. Data sources : Unified data access management
    1. SQL : Access to relational databases
    2. Memcache : Access to Memcached servers
    3. Redis : Access to Redis servers
    4. File : Access to local file storage
    5. S3 : Access to Amazon S3 storage
    6. Socket : Network communication
    7. SQS : Access to Amazon SQS message queues
    8. Beanstalk : Access to Beanstalkd message queue servers
    9. Smsmode : To send text messages to mobile phones
    10. Slack : To send notifications on Slack
    11. Pushover : To send push notifications to cell phones
  12. Model : How to use DAOs to access databases
  13. Execution flow : How to manage the execution flow, between plugins and the controller
  14. Plugins : How to use plugins, and create your own plugins to modularize your code
  15. Attributes : How to filter access to controllers and actions
  16. Tests : To write automated integration tests.
  17. Command-line interface : To create executable scripts on the command line, automatically initialized by Temma
  18. Helpers : Items offered by Temma to help you in various circumstances