Data source: File

1Presentation

Temma can use a file tree as a data source. This can be useful for quickly setting up a storage solution, which can later be replaced by a relational database, a non-relational database, or outsourced file storage.

If you have set up the connection parameters correctly, Temma automatically creates an object of type \Temma\Datasources\File. By convention, we'll assume that you've named this connection file in the etc/temma.php file (see configuration documentation).

The connection is then available in the controller by writing:

$this->file

In other objects managed by the dependency injection component, the database connection can be accessed by writing:

$loader->dataSources['file']

2Configuration

In the etc/temma.php file (see configuration documentation), you declare the DSN (Data Source Name) which defines the file tree to be used.

The DSN used to define a file tree is: file://[UMASK]PATH
The umask is optional and is written in octal form, starting with a zero. If not defined, the system default umask is used.

Examples:

file:///var/data/tema
file://0777/var/data/temma

3Unified calls

3.1Array-like access

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

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

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

// data deletion
unset($this->file['path/key1']);

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

3.2General methods

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

// data deletion
$this->file->remove('user/1');

// multiple data deletion
$this->file->mRemove(['user/1', 'user/2', 'user/3']);

// deleting data from a mask
$this->file->clear('user/*');

// delete all data
$this->file->flush();

3.3Management of complex serialized data

// search for files matching a mask
$users = $this->file->search('user/*');

// mask-based key search, with data recovery (deserialized)
$users = $this->file->search('user/*', true);

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

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

// data writing (serialized)
$this->file->set('user/1', $userData);
// write (serialized) data with specific access rights
$this->file->set('user:1', $userData, 0600);

// multiple data writing (serialized)
$this->file->mSet([
    'user/1' => $user1data,
    'user/2' => $user2data,
    'user/3' => $user3data,
]);
// write multiple data, with specific access rights
$this->file->mSet([
    'user/1' => $user1data,
    'user/2' => $user2data,
], 0750);

3.4Raw data management

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

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

// copy data to a local file
$this->file->copyFrom('page/home', '/path/to/newpage.html');
// copy data to local file, with default value
$this->file->copyFrom('page/home', '/path/to/newpage.html', $defaultHtml);
// copy data to a local file, with data creation if necessary
$this->file->copyFrom('page/home', '/path/to/newpage.html', function() {
    return file_get_contents('/path/to/oldpage.html');
});
// copy data to a local file, with data creation if necessary
// (with a lifetime of one hour)
$this->file->copyFrom('page/home', '/path/to/newpage.html', function() {
    return file_get_contents('/path/to/oldpage.html');
}, 3600);

// data writing (raw)
$this->file->write('color/blue', '#0000ff');
// data writing (raw) with specific access rights
$this->file->write('color/blue', '#0000ff', 0660);

// write multiple (raw) data
$this->file->mWrite({
    'color/blue'  => '#0000ff',
    'color/red'   => '#ff0000',
    'color/green' => '#00ff00',
]);
// write multiple (raw) data with specific access rights
$this->file->mWrite({
    'color/blue'  => '#0000ff',
    'color/red'   => '#ff0000',
], 0600);

// write (raw) data from a local file
$this->file->copyTo('page/home', '/path/to/homepage.html');
// write (raw) data from a local file, with specific access rights
$this->file->copyTo('page/home', '/path/to/homepage.html', 0600);

// write multiple (raw) data from local files
$this->file->mCopyTo([
    'page/home'     => '/path/to/homepage.html',
    'page/admin'    => '/path/to/admin.html',
    'page/products' => '/path/to/products.html',
]);
// write multiple data from local files with a lifetime of one hour
$this->file->mCopyTo([
    'page/home'  => '/path/to/homepage.html',
    'page/admin' => '/path/to/admin.html',
], 3600);