README

phossa2/storage is a PHP storage library with support for local or cloud storage.

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.

Installation

Install via the composer utility.

composer require "phossa2/storage"

or add the following lines to your composer.json

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

Introduction

Simple restful like APIs.
Unified path syntax like /local/img/avatar.jpg for all systems.
Mounting and umounting filesystem.
Support for different drivers.
Support for stream.

Usage

Create the storage instance,

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

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

Others APIs like

meta()

Get the meta data of the file

// 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

// 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

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

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

Mounting and umounting filesystems

filesytem is a wrapper of different drivers with permissions. User may mount a read only filesystem as follows,

// 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,

$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,

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

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

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

Drivers

Support for different drivers inlucing local or cloud storage.

Streaming

Write and read streams as follows,

// 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
- bool has(string $path)
  
  check $path existens.
- null|string|array|resource get(string $path, bool $getAsStream)
  
  Get content of the $path.
  - If not found or failure, returns NULL.
  - If $path is a directory, returns an array of the full paths of the files under this $path.
  - If $getAsStream is true, returns a stream handler.
- bool put(string $path, string|resource|null $content, array $meta = [])
  
  Set the content or meta data of the $path.
- 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).
- bool copy(string $from, string $to) and bool copy(string $from, string $to)
  
  Copy or move $from to $to.
- array meta(string $path)
  
  Get the meta data of $path. If not found or error, returns [].
- Phossa2\Storage\Path path(string $path)
  
  Returns a Phossa2\Storage\Path object
Error related
- bool hasError()
  
  Has error ?
- string getError()
  
  Get previous error message. If no error, returns ''.
```
if (!$storage->copy('/local/from.txt', '/local/to.txt')) {
    $err = $storage->getError();
}
```
- string getErrorCode()
  
  Get a numeric string of the error code.

Change log

Please see CHANGELOG from more information.

Contributing

Please see CONTRIBUTE for more information.

Dependencies

PHP >= 5.4.0
phossa2/shared >= 2.0.23

License

MIT License

phossa2 / storage

Maintainers

Details