Download the PHP package webiny/storage without Composer

Storage Component

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.

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.

(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:

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)

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

Filtering files (recursive mode)

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:

Deleting a directory

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

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.

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.):

Resources

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

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