README

Storage Component is a storage abstraction layer that simplifies the way you work with files and directories.

Install the component

The best way to install the component is using Composer.

composer require webiny/storage

For additional versions of the package, visit the Packagist page.

Usage

You will need to use storage drivers to access different storage providers like local disk, Amazon, Rackspace, etc.

Webiny Framework provides LocalStorageDriver and S3StorageDriver but using a set of built-in interfaces will help you to develop a new driver in no time.

The following driver interfaces are available:

DriverInterface - main storage driver interface
TouchableInterface - for drivers that support touch functionality (change of time modified)
SizeAwareInterface - for drivers that can access file size
DirectoryAwareInterface - for drivers that can work with directories
AbsolutePathInterface - for drivers that can provide absolute file path (ex: /var/www/app/storage/myFile.txt)

Configuring a storage service

The recommended way of using a storage is by defining a storage service. Here is an example of defining a service using LocalStorageDriver and S3StorageDriver: NOTE: you can use DIR to have your file paths built dynamically. DIR will be replaced with the directory path containing current config file.

Storage:
    # You can optionally specify parameters for use in services definitions
    Parameters:
        Storage.Class: \Webiny\Component\Storage\Storage
        Storage.S3DriverArgs:
            - yourAccessKeyID
            - yourSecretAccessKey
            - webiny # Bucket name
            - false # Date folder structure
            - http://d47gcb3uej2zar.cloudfront.net # CDN domain
    Services:
        LocalStorage:
            Class: %Storage.Class%
            Arguments:
                Driver:
                    Object: \Webiny\Component\Storage\Driver\Local\LocalStorageDriver
                    ObjectArguments:
                        - __DIR__/../../Public/Uploads # Absolute root path
                        - http://admin.w3.com/Uploads # Web root path
                        - false # DateFolderStructure
                        - true # Create folder if it doesn't exist
        CloudStorage:
            Class: %Storage.Class%
            Arguments:
                Driver:
                    Object: \Webiny\Component\Storage\Driver\AmazonS3\S3StorageDriver
                    ObjectArguments: %Storage.S3DriverArgs%
            Tags: [cloud]

(This is just one way of defining a service. For detailed documentation on defining a service refer to ServiceManager component.)

Using your new storage

To make use of local storage easier and more flexible, there are 2 classes: \Webiny\Component\Storage\File\File and \Webiny\Component\Storage\Directory\Directory. These 2 classes serve as wrappers so you never need to make calls to storage directly. Besides, they contain common methods you will need to perform actions on files and directories.

Let's take a look at how you would store a new file:

// use StorageTrait

// Get your storage service. Storage name is part of the service name after 'Storage.'
$storage = $this->storage('LocalStorage');

// Create a file object with a key (file name) and a $storage instance
$file = new File('file.txt', $storage);

$contents = file_get_contents('http://www.w3schools.com/images/w3schoolslogoNEW310113.gif');
$file->setContents($contents);

After calling setContents($contents) the contents is written to the storage immediately and a bool is returned.

Working with directories

Sometimes you need to read the whole directory, filter files by name, extension, etc. There is a special interface for this type of manipulation, \Webiny\Component\Storage\Directory\DirectoryInterface.

Since not all storage engines support directories, there is no generic implementation of this interface. There is, however, an implementation in form of Directory which works nicely with local file storage. There are 2 modes of reading a directory: recursive and non-recursive.

Recursive will read the whole directory structure recursively and build a one-dimensional array of files (directory objects are not created but their children files are returned). This is very useful when you need to read all files at once or filter them by name, extension, etc.
Non-recursive will only read current directory and return both child Directory and File objects. You can then loop through child Directory object to go in-depth.

Reading a directory (non-recursive mode)

// Get your storage service
$storage = $this->storage('LocalStorage');

// Create a directory object with a key (directory name), $storage instance
$dir = new Directory('2013', $storage);

// Loop through directory object
foreach($dir as $item){
    if($item->isDirectory()){
		// Do something with child Directory object
	} else {
		// Do something with File object
	}
}

NOTE: directory files are not being fetched from storage until you actually use the object.

Filtering files (recursive mode)

// Get your storage service
$storage = $this->storage('LocalStorage');

// Read recursively
$dir = new Directory('2013', $storage, true);

// Get only PDF files
$pdfFiles = $dir->filter('*.pdf');

// Count ZIP files
$zipFiles = $dir->filter('*.zip')->count();

// Get files starting with 'log_'
$logFiles = $dir->filter('log_*');

// You can also pass the result of filter directly to loops as `filter()` returns a new Directory object
foreach($dir->filter('*.txt') as $file){
    // Do something with your file
}

NOTE: calling filter() does not change the original Directory object, but creates a new Directory object with filtered result, so once you've read the root directory you can filter it using any condition as many times as you need:

// Get your storage service
$storage = $this->storage('LocalStorage');

// Read recursively and don't filter
$dir = new Directory('2013', $storage, true);

// Now you can manipulate the whole directory 

// Get number of all ZIP files in the directory tree
$zipFiles = $dir->filter('*.zip')->count();

// Get number of all RAR files in the directory tree
$zipFiles = $dir->filter('*.rar')->count();

// Get number of all LOG files in the directory tree
$zipFiles = $dir->filter('*.log')->count();

// Now output all files in the directory without filtering them
foreach($dir as $file){
    echo $file->getKey();
}

Deleting a directory

Deleting a directory (this is done recursively) is as simple as:

// Get your storage service
$storage = $this->storage('LocalStorage');

// Get directory
$dir = new Directory('2013', $storage);

// This will delete the whole directory structure and fire FILE_DELETED event for each file along the way
$dir->delete();

// If you don't want the events to be fired, pass as second parameter `false`:
$dir->delete(false);

Storage events

There are 3 types of events fired when certain actions are performed on a File:

wf.storage.file_saved (StorageEvent::FILE_SAVED) - fired after a file was saved successfully.
wf.storage.file_renamed (StorageEvent::FILE_RENAMED) - fired after a file is renamed.
wf.storage.file_deleted (StorageEvent::FILE_DELETED) - fired after a file is deleted.

All 3 events pass an instance of \Webiny\Component\Storage\StorageEvent to their event handlers. Once your handler gets executed, you can access the file objects using $event->getFile() method.

class Test {
    use EventManagerTrait;
    
    public function index(){
    
        // Listen for StorageEvent::FILE_SAVED
        $this->eventManager()->listen(StorageEvent::FILE_SAVED)->handler(function(StorageEvent $event){
            // Get the file object
            $file = $event->getFile();
        });
    }
}

StorageEvent::FILE_RENAMED event also assigns a special property called oldKey to the event object, which holds the value of file key before renaming (this will help you update your database records, etc.):

class Test {
    use EventManagerTrait;
    
    public function index(){
    
        // Listen for StorageEvent::FILE_RENAMED
        $this->eventManager()->listen(StorageEvent::FILE_RENAMED)->handler(function(StorageEvent $event){
        
            // Get the file object
            $file = $event->getFile();
            
            // $file now contains the file object with new key, and we need to get the old key
            $oldKey = $event->oldKey;
            $newKey = $file->getKey();
        });
    }
}

Resources

To run unit tests, you need to use the following command:

$ cd path/to/Webiny/Component/Storage/
$ composer.phar install
$ phpunit

webiny / storage

Maintainers

Details