phossa2/storage

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,

usePhossa2\Storage\Storage;
usePhossa2\Storage\Filesystem;
usePhossa2\Storage\Driver\LocalDriver;
// mount local dir '/www/storage' to '/local'$storage = newStorage(
'/local',
newFilesystem('/www/storage')
);
// add a file$filename = '/local/newfile.txt';
$storage->put($filename, 'this is the content');
// check existensif ($storage->has($filename)) {
// read file content$str = $storage->get($filename);
// delete the file$storage->del($filename);
}
// mount another filesystem$storage->mount('/aws', newFilesystem(newAwsDriver()));

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 dataif ($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 = newStorage(
  '/disk/d',
  newFilesystem(newLocalDriver('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',
  newFilesystem(
  '/home/www/public',
  Filesystem::PERM_READ
  )
  );
  // will fail$storage->put('/readonly/newfile.txt', 'this is the content');

  Different filesystem may use same driver,

  $driver = newLocalDriver('/home/www/public');
  // writable$storage->mount('/public', newFilesystem($driver));
  // readonly$storage->mount('/readonly', newFilesystem($driver, Filesystem::PERM_READ));

  Filesystems may overlapping on top of others,

  // mount root$storage->mount('/', newFilesystem(...));
  // mount var$storage->mount('/var', newFilesystem(...));
  // mount cache$storage->mount('/var/cache', newFilesystem(...));

• 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 itif (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