readme

Author: ChiragAgg5k

README.md

@@ -16,33 +16,206 @@ Install using composer:
 composer require utopia-php/storage
 ```
 
+### Basic Usage
+
 ```php
 <?php
 
 require_once '../vendor/autoload.php';
 
 use Utopia\Storage\Storage;
 use Utopia\Storage\Device\Local;
+
+// Set up a storage device (choose one)
+Storage::setDevice('files', new Local('/path/to/storage'));
+
+// Common operations with any device
+$device = Storage::getDevice('files');
+
+// Upload a file
+$device->upload('/local/path/to/file.png', 'destination/path/file.png');
+
+// Check if file exists
+$exists = $device->exists('destination/path/file.png');
+
+// Read file contents
+$contents = $device->read('destination/path/file.png');
+
+// Delete a file
+$device->delete('destination/path/file.png');
+```
+
+## Available Adapters
+
+### Local Storage
+
+Use the local filesystem for storing files.
+
+```php
+use Utopia\Storage\Storage;
+use Utopia\Storage\Device\Local;
+
+Storage::setDevice('files', new Local('/path/to/storage'));
+```
+
+### AWS S3
+
+Store files in Amazon S3.
+
+```php
+use Utopia\Storage\Storage;
+use Utopia\Storage\Device\AWS;
+
+Storage::setDevice('files', new AWS(
+    'root', // Root path in bucket
+    'YOUR_ACCESS_KEY',
+    'YOUR_SECRET_KEY',
+    'YOUR_BUCKET_NAME',
+    AWS::US_EAST_1, // Region (default: us-east-1)
+    AWS::ACL_PRIVATE // Access control (default: private)
+));
+```
+
+### Generic S3-Compatible Provider
+
+Store files in any S3-compatible service by providing the bucket host and region.
+
+```php
+use Utopia\Storage\Storage;
 use Utopia\Storage\Device\S3;
+
+Storage::setDevice('files', new S3(
+    'root', // Root path in bucket
+    'YOUR_ACCESS_KEY',
+    'YOUR_SECRET_KEY',
+    'YOUR_BUCKET_HOST', // e.g. your-bucket.s3.example.com
+    'us-east-1',
+    S3::ACL_PRIVATE
+));
+```
+
+### DigitalOcean Spaces
+
+Store files in DigitalOcean Spaces.
+
+```php
+use Utopia\Storage\Storage;
 use Utopia\Storage\Device\DOSpaces;
 
-// Instantiating local storage
-Storage::setDevice('files', new Local('path'));
+Storage::setDevice('files', new DOSpaces(
+    'root', // Root path in bucket
+    'YOUR_ACCESS_KEY',
+    'YOUR_SECRET_KEY',
+    'YOUR_BUCKET_NAME',
+    DOSpaces::NYC3, // Region (default: nyc3)
+    DOSpaces::ACL_PRIVATE // Access control (default: private)
+));
+```
+
+### Backblaze B2
+
+Store files in Backblaze B2 Cloud Storage.
+
+```php
+use Utopia\Storage\Storage;
+use Utopia\Storage\Device\Backblaze;
+
+Storage::setDevice('files', new Backblaze(
+    'root', // Root path in bucket
+    'YOUR_ACCESS_KEY',
+    'YOUR_SECRET_KEY',
+    'YOUR_BUCKET_NAME',
+    Backblaze::US_WEST_004, // Region (default: us-west-004)
+    Backblaze::ACL_PRIVATE // Access control (default: private)
+));
+```
+
+### Linode Object Storage
+
+Store files in Linode Object Storage.
+
+```php
+use Utopia\Storage\Storage;
+use Utopia\Storage\Device\Linode;
+
+Storage::setDevice('files', new Linode(
+    'root', // Root path in bucket
+    'YOUR_ACCESS_KEY',
+    'YOUR_SECRET_KEY',
+    'YOUR_BUCKET_NAME',
+    Linode::EU_CENTRAL_1, // Region (default: eu-central-1)
+    Linode::ACL_PRIVATE // Access control (default: private)
+));
+```
+
+### Wasabi Cloud Storage
+
+Store files in Wasabi Cloud Storage.
+
+```php
+use Utopia\Storage\Storage;
+use Utopia\Storage\Device\Wasabi;
+
+Storage::setDevice('files', new Wasabi(
+    'root', // Root path in bucket
+    'YOUR_ACCESS_KEY',
+    'YOUR_SECRET_KEY',
+    'YOUR_BUCKET_NAME',
+    Wasabi::EU_CENTRAL_1, // Region (default: eu-central-1)
+    Wasabi::ACL_PRIVATE // Access control (default: private)
+));
+```
 
-// Or you can use AWS S3 storage
-Storage::setDevice('files', new S3('path', AWS_ACCESS_KEY, AWS_SECRET_KEY,AWS_BUCKET_NAME, AWS_REGION, AWS_ACL_FLAG));
+## Common Operations
 
-// Or you can use DigitalOcean Spaces storage
-Storage::setDevice('files', new DOSpaces('path', DO_SPACES_ACCESS_KEY, DO_SPACES_SECRET_KEY, DO_SPACES_BUCKET_NAME, DO_SPACES_REGION, AWS_ACL_FLAG));
+All storage adapters provide a consistent API for working with files:
+
+```php
+use Utopia\Storage\Storage;
 
 $device = Storage::getDevice('files');
 
-//upload
-$device->upload('file.png','path');
+// Upload a file
+$device->upload('/path/to/local/file.jpg', 'remote/path/file.jpg');
+
+// Upload data from memory
+$device->uploadData($binary, 'remote/path/file.bin', 'application/octet-stream');
+
+// Check if file exists
+$exists = $device->exists('remote/path/file.jpg');
+
+// Get file size
+$size = $device->getFileSize('remote/path/file.jpg');
+
+// Get file MIME type
+$mime = $device->getFileMimeType('remote/path/file.jpg');
+
+// Get file MD5 hash
+$hash = $device->getFileHash('remote/path/file.jpg');
+
+// Read file contents
+$contents = $device->read('remote/path/file.jpg');
+
+// Read partial file contents
+$chunk = $device->read('remote/path/file.jpg', 0, 1024); // Read first 1KB
+
+// Create directory
+$device->createDirectory('remote/new-directory');
+
+// List files in directory
+$files = $device->getFiles('remote/directory');
+
+// Delete file
+$device->delete('remote/path/file.jpg');
+
+// Delete directory and its contents
+$device->deletePath('remote/directory');
 
-//delete
-$device->delete('path');
+// Transfer files between storage devices
+$sourceDevice = Storage::getDevice('source');
+$targetDevice = Storage::getDevice('target');
 
+$sourceDevice->transfer('source/path.jpg', 'target/path.jpg', $targetDevice);
 ```
 
 ## System Requirements