Skip to content

Doc: improve readme #130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
christyjacob4 merged 1 commit into from
Apr 9, 2025
Merged

Doc: improve readme #130

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
244 changes: 225 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,54 +1,260 @@
# Utopia Storage

[![Build Status](https://travis-ci.org/utopia-php/ab.svg?branch=master)](https://travis-ci.com/utopia-php/storage)
[![Build Status](https://travis-ci.org/utopia-php/storage.svg?branch=master)](https://travis-ci.com/utopia-php/storage)
![Total Downloads](https://img.shields.io/packagist/dt/utopia-php/storage.svg)
[![Discord](https://img.shields.io/discord/564160730845151244?label=discord)](https://appwrite.io/discord)

Utopia Storage library is simple and lite library for managing application storage. It supports multiple storage adapters. We already support AWS S3 storage, Digitalocean Spaces storage, Backblaze B2 Cloud storage, Linode Object storage and Wasabi Cloud storage. This library is aiming to be as simple and easy to learn and use. This library is maintained by the [Appwrite team](https://appwrite.io).
Utopia Storage is a simple and lightweight library for managing application storage across multiple adapters. This library is designed to be easy to learn and use, with a consistent API regardless of the storage provider. This library is maintained by the [Appwrite team](https://appwrite.io).

This library is part of the [Utopia Framework](https://github.com/utopia-php/framework) project.


## Getting Started

Install using composer:
```bash
composer require utopia-php/storage
```

### Basic Usage

```php
<?php

require_once '../vendor/autoload.php';

use Utopia\Storage\Storage;
use Utopia\Storage\Device\Local
use Utopia\Storage\Device\S3
use Utopia\Storage\Device\DOSpaces
use Utopia\Storage\Device\Local;
use Utopia\Storage\Device\S3;
use Utopia\Storage\Device\DOSpaces;
use Utopia\Storage\Device\Backblaze;
use Utopia\Storage\Device\Linode;
use Utopia\Storage\Device\Wasabi;

// Set up a storage device (only need to 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;

// Initialize local storage
Storage::setDevice('files', new Local('/path/to/storage'));
```

### AWS S3

Store files in Amazon S3 or compatible services.

```php
use Utopia\Storage\Storage;
use Utopia\Storage\Device\S3;

// Initialize S3 storage
Storage::setDevice('files', new S3(
'root', // Root path in bucket
'YOUR_ACCESS_KEY',
'YOUR_SECRET_KEY',
'YOUR_BUCKET_NAME',
S3::US_EAST_1, // Region (default: us-east-1)
S3::ACL_PRIVATE // Access control (default: private)
));

// Available regions
// S3::US_EAST_1, S3::US_EAST_2, S3::US_WEST_1, S3::US_WEST_2, S3::AP_SOUTH_1,
// S3::AP_NORTHEAST_1, S3::AP_NORTHEAST_2, S3::AP_NORTHEAST_3, S3::AP_SOUTHEAST_1,
// S3::AP_SOUTHEAST_2, S3::EU_CENTRAL_1, S3::EU_WEST_1, S3::EU_WEST_2, S3::EU_WEST_3,
// And more - check the S3 class for all available regions

// Available ACL options
// S3::ACL_PRIVATE, S3::ACL_PUBLIC_READ, S3::ACL_PUBLIC_READ_WRITE, S3::ACL_AUTHENTICATED_READ
```

### DigitalOcean Spaces

Store files in DigitalOcean Spaces.

```php
use Utopia\Storage\Storage;
use Utopia\Storage\Device\DOSpaces;

// Initialize DO Spaces storage
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)
));

// Available regions
// DOSpaces::NYC3, DOSpaces::SGP1, DOSpaces::FRA1, DOSpaces::SFO2, DOSpaces::SFO3, DOSpaces::AMS3
```

### Backblaze B2

Store files in Backblaze B2 Cloud Storage.

```php
use Utopia\Storage\Storage;
use Utopia\Storage\Device\Backblaze;

// Initialize Backblaze storage
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)
));

// Available regions (clusters)
// Backblaze::US_WEST_000, Backblaze::US_WEST_001, Backblaze::US_WEST_002,
// Backblaze::US_WEST_004, Backblaze::EU_CENTRAL_003
```

### Linode Object Storage

Store files in Linode Object Storage.

```php
use Utopia\Storage\Storage;
use Utopia\Storage\Device\Linode;

// Initialize Linode storage
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)
));

// Available regions
// Linode::EU_CENTRAL_1, Linode::US_SOUTHEAST_1, Linode::US_EAST_1, Linode::AP_SOUTH_1
```

### Wasabi Cloud Storage

Store files in Wasabi Cloud Storage.

```php
use Utopia\Storage\Storage;
use Utopia\Storage\Device\Wasabi;

// Initialize Wasabi storage
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)
));

// Instantiating local storage
Storage::setDevice('files', new Local('path'));
// Available regions
// Wasabi::US_EAST_1, Wasabi::US_EAST_2, Wasabi::US_WEST_1, Wasabi::US_CENTRAL_1,
// Wasabi::EU_CENTRAL_1, Wasabi::EU_CENTRAL_2, Wasabi::EU_WEST_1, Wasabi::EU_WEST_2,
// Wasabi::AP_NORTHEAST_1, Wasabi::AP_NORTHEAST_2
```

// 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
// Get storage device
$device = Storage::getDevice('files');

//upload
$device->upload('file.png','path');
// Upload a file
$device->upload('/path/to/local/file.jpg', 'remote/path/file.jpg');

// Check if file exists
$exists = $device->exists('remote/path/file.jpg');

//delete
$device->delete('path');
// 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

// Multipart/chunked uploads
$device->upload('/local/file.mp4', 'remote/video.mp4', 1, 3); // Part 1 of 3

// Create directory
$device->createDirectory('remote/new-directory');

// List files in directory
$files = $device->listFiles('remote/directory');

// Delete file
$device->delete('remote/path/file.jpg');

// Delete directory
$device->deleteDirectory('remote/directory');

// Transfer files between storage devices
$sourceDevice = Storage::getDevice('source');
$targetDevice = Storage::getDevice('target');

$sourceDevice->transfer('source/path.jpg', 'target/path.jpg', $targetDevice);
```

## Adding New Adapters

For information on adding new storage adapters, see the [Adding New Storage Adapter](https://github.com/utopia-php/storage/blob/master/docs/adding-new-storage-adapter.md) guide.

## System Requirements

Utopia Framework requires PHP 7.4 or later. We recommend using the latest PHP version whenever possible.
Utopia Storage requires PHP 7.4 or later. We recommend using the latest PHP version whenever possible.

## Contributing

For security issues, please email [security@appwrite.io](mailto:security@appwrite.io) instead of posting a public issue in GitHub.

All code contributions - including those of people having commit access - must go through a pull request and be approved by a core developer before being merged. This is to ensure a proper review of all the code.

## Copyright and license
We welcome you to contribute to the Utopia Storage library. For details on how to do this, please refer to our [Contributing Guide](https://github.com/utopia-php/storage/blob/master/CONTRIBUTING.md).

The MIT License (MIT) [http://www.opensource.org/licenses/mit-license.php](http://www.opensource.org/licenses/mit-license.php)
## License

This library is available under the MIT License.

## Copyright

```
Copyright (c) 2019-2025 Appwrite Team <team@appwrite.io>
```