Filesystem Manager

The Hazaar\File\Manager class provides a unified interface for accessing various file storage backends. It allows you to perform file operations such as reading, writing, copying, moving, and deleting files across different storage systems using a consistent API.

This system is built around the Hazaar\File class, which represents a file object and uses the Hazaar\File\Manager to handle the actual storage operations.

Supported Backends

The following storage backends are currently supported:

• local - The local server filesystem.
• dropbox - Dropbox cloud storage.
• googledrive - Google Drive cloud storage.
• webdav - WebDAV servers (e.g., Nextcloud, ownCloud).
• dbi - Database-backed virtual filesystem.

Configuring the Manager

To use the filesystem manager, you need to instantiate Hazaar\File\Manager. You can specify the backend and its configuration options during instantiation.

Local Filesystem

The local backend is the default. It requires a root path configuration.

use Hazaar\File\Manager;

$config = ['root' => '/path/to/files'];
$manager = new Manager('local', $config);

Dropbox

The Dropbox backend requires an OAuth2 access token.

$config = [
    'access_code' => 'your-dropbox-access-code'
];
$manager = new Manager('dropbox', $config);

Google Drive

The Google Drive backend also requires an OAuth2 access token.

$config = [
    'access_code' => 'your-google-drive-access-code',
    'redirect_uri' => 'http://your-app/callback'
];
$manager = new Manager('googledrive', $config);

WebDAV

The WebDAV backend requires the server URL and potential authentication credentials.

$config = [
    'url'      => 'https://webdav.example.com/remote.php/dav/files/user/',
    'user'     => 'username',
    'password' => 'password'
];
$manager = new Manager('webdav', $config);

Working with Files

The Hazaar\File class is the primary way to interact with files. It can be initialized with a path relative to the manager's root.

Reading and Writing

use Hazaar\File;

// Get a file instance from the manager
$file = $manager->get('example.txt');

// Or create a new file instance directly (defaults to local manager if not provided)
// $file = new File('/path/to/local/file.txt');

// Write content
$file->putContents('Hello World!');

// Read content
echo $file->getContents(); // Output: Hello World!

File Metadata

You can retrieve various metadata about the file.

if ($file->exists()) {
    echo $file->size();             // File size in bytes
    echo $file->mimeContentType();  // Mime type (e.g., text/plain)
    echo $file->extension();        // File extension (e.g., txt)
    echo $file->basename();         // Filename (e.g., example.txt)
}

File Operations

Common operations like copying, moving, and deleting are supported.

// Copy file
$backup = $file->copy('backup/example.bak');

// Move/Rename file
$file->moveTo('archive/example.txt');

// Delete file
$file->unlink();

Encryption

Files can be encrypted and decrypted transparently.

// Encrypt the file
$file->encrypt();

// Check if encrypted
if ($file->isEncrypted()) {
    // Reading automatically decrypts the content in memory
    $content = $file->getContents(); 
}

// Decrypt the file permanently
$file->decrypt();

Working with Directories

You can list directory contents and manage folders using the Manager or Hazaar\File\Dir.

// Get a directory listing as Hazaar\File objects
$dir = $manager->get('/images');

if ($dir instanceof \Hazaar\File\Dir) {
    while($file = $dir->read()) {
        echo $file->basename() . "\n";
    }
}

// Create a directory
$manager->mkdir('/new-folder');

// Delete a directory
$manager->unlink('/new-folder');

Authentication Helper

For backends requiring OAuth (Dropbox, Google Drive), the manager provides authentication helpers.

if (!$manager->authorised()) {
    // Generate the authorization URL for the user
    $authUrl = $manager->buildAuthURL();
    
    // Redirect user to $authUrl...
}

// After user authorizes and returns with a code:
$manager->authoriseWithCode($code);