phossa2/storage

, _(*1)

phossa2/storage is a PHP storage library with support for local or cloud storage., _(*2)

It requires PHP 5.4, supports PHP 7.0+ and HHVM. It is compliant with PSR-1, PSR-2, PSR-3, PSR-4, and the proposed PSR-5., _(*3)

Installation

Install via the composer utility., _(*4)

composer require "phossa2/storage"

or add the following lines to your composer.json, _(*5)

{
    "require": {
       "phossa2/storage": "2.*"
    }
}

Introduction

Simple restful like APIs., _(*6)
Unified path syntax like /local/img/avatar.jpg for all systems., _(*7)
Mounting and umounting filesystem., _(*8)
Support for different drivers., _(*9)
Support for stream., _(*10)

Usage

Create the storage instance,, _(*11)

use Phossa2\Storage\Storage;
use Phossa2\Storage\Filesystem;
use Phossa2\Storage\Driver\LocalDriver;

// mount local dir '/www/storage' to '/local'
$storage = new Storage(
    '/local',
    new Filesystem('/www/storage')
);

// add a file
$filename = '/local/newfile.txt';
$storage->put($filename, 'this is the content');

// check existens
if ($storage->has($filename)) {
    // read file content
    $str = $storage->get($filename);

    // delete the file
    $storage->del($filename);
}

// mount another filesystem
$storage->mount('/aws', new Filesystem(new AwsDriver()));

Features

Restful APIs, _(*12)

Support for simple and instinctive APIs like get(), put(), has() and del() etc., _(*13)

Others APIs like, _(*14)

meta()

Get the meta data of the file, _(*15)

// get the meta data
if ($storage->has($file)) {
    $meta = $storage->meta($file);
}

// update meta data
$new = ['mtime' => time()];
$storage->put($file, null, $new);

copy() and move()

Copy or move files in or between filesystems, _(*16)

// move to another name
$storage->move('/local/README.txt', '/local/README.bak.txt');

// copy into another filesystem's directory
$storage->copy('/local/README.txt', '/aws/www/');

Unified path syntax, _(*17)

Uses unified path syntax like `/local/dir/file.txt' for all systems including windows. The underlying driver is responsible for translating path transparently., _(*18)
```
$storage = new Storage(
'/disk/d',
new Filesystem(new LocalDriver('D:\\\\'))
);

$storage->put('/disk/d/temp/newfile.txt', 'this is content');
```

Mounting and umounting filesystems, _(*19)

filesytem is a wrapper of different drivers with permissions. User may mount a read only filesystem as follows,, _(*20)

// mount as readonly, default is Filesystem::PERM_ALL
$storage->mount(
  '/readonly',
  new Filesystem(
    '/home/www/public',
    Filesystem::PERM_READ
  )
);

// will fail
$storage->put('/readonly/newfile.txt', 'this is the content');

Different filesystem may use same driver,, _(*21)

$driver = new LocalDriver('/home/www/public');

// writable
$storage->mount('/public', new Filesystem($driver));

// readonly
$storage->mount('/readonly', new Filesystem($driver, Filesystem::PERM_READ));

Filesystems may overlapping on top of others,, _(*22)

// mount root
$storage->mount('/', new Filesystem(...));

// mount var
$storage->mount('/var', new Filesystem(...));

// mount cache
$storage->mount('/var/cache', new Filesystem(...));

Drivers, _(*23)

Support for different drivers inlucing local or cloud storage., _(*24)

Streaming, _(*25)

Write and read streams as follows,, _(*26)

// read stream
$stream = $storage->get('/local/thefile.txt', true);

// write with stream
$storage->put('/local/anotherfile.txt', $stream);

// close it
if (is_resource($stream)) {
  fclose($stream);
}

APIs

\Phossa2\Storage\Storage, _(*27)
- bool has(string $path)
check $path existens., _(*28)
- null|string|array|resource get(string $path, bool $getAsStream)
Get content of the $path., _(*29)
- If not found or failure, returns NULL., _(*30)
- If $path is a directory, returns an array of the full paths of the files under this $path., _(*31)
- If $getAsStream is true, returns a stream handler., _(*32)
- bool put(string $path, string|resource|null $content, array $meta = []), _(*33)
Set the content or meta data of the $path., _(*34)
- bool del(string $path)
Remove the $path. If $path is a directory, will remove all files under this path and the path itself (unless it is a mount point)., _(*35)
- bool copy(string $from, string $to) and bool copy(string $from, string $to)
Copy or move $from to $to., _(*36)
- array meta(string $path)
Get the meta data of $path. If not found or error, returns []., _(*37)
- Phossa2\Storage\Path path(string $path)
Returns a Phossa2\Storage\Path object, _(*38)
Error related, _(*39)
- bool hasError()
Has error ?, _(*40)
- string getError()
Get previous error message. If no error, returns ''., _(*41)
```
if (!$storage->copy('/local/from.txt', '/local/to.txt')) {
    $err = $storage->getError();
}
```
- string getErrorCode()
Get a numeric string of the error code., _(*42)