tereta / storage

0.0.10 2026-10-04 21:55 UTC

Requires

• php: >=8.2

Requires (Dev)

• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^11.0
• squizlabs/php_codesniffer: ^3.13

Suggests

• ext-ssh2: Required for the Tereta\Storage\Strategies\Sftp strategy

Apache-2.0

• Tereta Alexander

• file
• filesystem
• abstraction
• storage
• files
• sftp
• ssh2
• local

Published on Packagist.org on 2026-10-04 18:56 UTC

README

🌐 English | Русский | Українська

Introduction

Tereta/Storage is a package for working with file resources. You work with them the same way regardless of where the storage is located. The local and sftp drivers are supported out of the box.

Requirements

• PHP version 8.2 or newer.
• The ext-ssh2 extension - required only for the sftp driver. It is not needed for local storage (local).

Installation

composer require tereta/storage

Git Repository

https://gitlab.com/tereta/library/storage

Usage

All work is done through the Tereta\Storage\Filesystem facade. It is created by the Tereta\Storage\Factories\Filesystem factory: pass the strategy name (local or sftp) and its settings.

Available methods:

• exists(string $path) - check whether a file exists. Returns true or false.
• read(string $path) - read the file contents. Returns a string.
• write(string $path, string $contents, ?int $mode = 0644) - save (or create) a file.
• copy(string $source, string $destination, ?int $mode = 0644) - copy a file.
• move(string $source, string $destination, ?int $mode = 0644) - move or rename a file.
• remove(string $path, bool $recursively = false) - delete a file. To recursively delete a folder with all its contents, pass true as the second argument.
• list(string $path) - get the list of files in a folder. Returns an array of names.
• glob(string $pattern) - find files by a pattern, for example **/*.md. See Search files.
• resolve(string $path) - get the full path of a file inside the storage.

In write(), copy() and move() the $mode sets the file permissions. Pass null to keep the permissions that the server gives by default. This is useful where permissions can not be changed, for example on some SFTP servers.

Local filesystem

Use the local strategy for the local filesystem

use Tereta\Storage\Factories\Filesystem as FilesystemFactory;

$storage = (new FilesystemFactory())->create('local', '/var/www/files');

For files on an SFTP server - the sftp strategy

$storage = (new FilesystemFactory())->create('sftp', 'example.com', 'user', 'secret', '/home/user/files');

The connection to the SFTP server opens on the first operation, not when the storage is created. So a wrong host or password shows up as an error on the first read(), write() or other call.

You can also create the strategy yourself. Then the editor and static analysis check every parameter:

use Tereta\Storage\Filesystem;
use Tereta\Storage\Strategies\Local;

$storage = new Filesystem(new Local('/var/www/files'));

Examples

Below are the available methods and examples for working with the filesystem:

// Write a file
$storage->write('notes/hello.txt', 'Hello!');

// Read
$text = $storage->read('notes/hello.txt');

// Check whether a file exists
if ($storage->exists('notes/hello.txt')) {
    // ...
}

// Copy and move
$storage->copy('notes/hello.txt', 'notes/backup.txt');
$storage->move('notes/hello.txt', 'archive/hello.txt');

// View the list of files in a folder
$files = $storage->list('notes');

// Delete a file (or an entire folder - pass true as the second argument)
$storage->remove('archive/hello.txt');

Search files - glob()

glob() finds files by a pattern and returns their paths one by one:

foreach ($storage->glob('notes/*.txt') as $file) {
    echo $file; // notes/hello.txt
}

• * - any part of a name inside one folder.
• ** - any number of nested folders, including none.
• ** at the end, for example notes/**, returns everything inside the folder at any depth: files and folders.
• The pattern is counted from the storage root. A leading / is allowed and does not change anything.
• Paths are returned from the storage root, without a leading /, for example notes/hello.txt.
• .. in a pattern is not allowed, you can not search outside the storage.

// All .md files in all folders
foreach ($storage->glob('**/*.md') as $file) {
    $text = $storage->read($file);
}

Errors

• Tereta\Storage\Exceptions\Runtime - an operation failed: the file is not found, there is no access, the connection failed and so on. The message contains the reason, for example Unable to read file: notes/a.txt: ... No such file or directory.
• Tereta\Storage\Exceptions\InvalidArgument - the factory got an unknown strategy name, wrong strategy settings, or a class that is not a strategy.