phossa2/storage

A storage front for local or remote storage system

2.0.1 2016-08-23 01:31 UTC

This package is not auto-updated.

Last update: 2024-11-10 02:17:16 UTC


README

Build Status Code Quality Code Climate PHP 7 ready HHVM Latest Stable Version License

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

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