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