README

Makes using DigitalOcean's Spaces object storage super easy.

Makes everything super simple.
Automatically handles multipart & stream uploads for large files.
Uses Spaces terminology for objects instead of S3.

Example

Create a Space & upload, it's as easy as that.

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Upload some text.
$my_space->upload("Super cool content", "example.txt");

//Uploaded!

tl;dr

Files
Spaces

Installing Spaces-API

There are two ways to install Spaces-API. You can either download the project & put it directly in your code's folder, or you can use Composer.

a) The Manual Method

Download Spaces-API & place it in your project.
Load it from your code:

require_once("spaces.php");

b) The Composer Method

Make sure you have Composer.
Install Spaces-API:

composer require sociallydev/spaces-api:v2

Make sure your code has the Composer autoloader:

require_once("vendor/autoload.php");

Setup

You'll need a DigitalOcean account & API keys to use Spaces-API. You should be able to generate a pair of keys from the DigitalOcean Dashboard. In the API page, there should be a section with the title "Spaces access keys". Click "Generate New Key" & follow the steps. That'll give you an access key & a secret key.

We'll be using these keys to initiate a Spaces instance:

$spaces = Spaces("ACCESS KEY", "SECRET KEY");

Usage

Once you have a Spaces instance, you can do pretty much anything the Spaces API allows.

Here is an example of downloading all your files to a local directory:

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Download entire Space to a directory.
$my_space->downloadToDirectory("local_backup");

Top-Level Spaces Functions

These are all the functions a Spaces instance can perform.

Create a new Space

$spaces = Spaces("ACCESS KEY", "SECRET KEY");

//Creates a new Space.
$spaces->create("my-new-space", "nyc3", "private");

The third (Space privacy) argument is optional. Defaults to private.
Returns a new single Space instance. Same as $spaces->space("my-new-space").

Use an existing Space

$spaces = Spaces("ACCESS KEY", "SECRET KEY");

//Get an existing Space.
$my_space = $spaces->space("my-space", "nyc3");

List all Spaces

$spaces = Spaces("ACCESS KEY", "SECRET KEY");

//Returns an array of all available Spaces.
$spaces->listSpaces();

Single Space Functions

These are all the functions a Space instance (From $spaces->space("my-new-space")) can perform!

Upload a stored file

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Upload a local stored file.
$my_space->uploadFile("path/to/my/file.txt", "path/on/space.txt", "private");

The second (Save as) argument is optional. Spaces-API attempts to use the original file path as the path on your Space if no save as path is provided.
The third argument (File privacy) is optional. It defaults to private.
Returns available info on the file.

Upload text directly

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Upload a local stored file.
$my_space->upload("my content", "path/on/space.txt", "private");

The first argument (Content) can be a string, but it can also be a StreamInterface or PHP stream resource.
The third argument (File privacy) is optional. It defaults to private.
Returns available info on the file.

Upload a local folder

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Uploads an entire local directory.
$my_space->uploadDirectory("my-local-folder");

You can provide a second argument which can be a folder inside your Space where to upload all the files inside the local folder.

Download a file

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Returns the file content as result.
$content = $my_space->downloadFile("my-file.txt");

//Saves the file content to the local path, and returns file info.
$info = $my_space->downloadFile("my-file.txt", "save-path/file.txt");

Download your Space to a local folder

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Uploads an entire local directory.
$my_space->downloadToDirectory("my-local-folder");

You can provide a second argument which can be a folder on your Space. Spaces-API will only download the files inside this folder.

Copy a file inside your Space

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Copies the file to the same Space.
$my_space->copyFile("my-file.txt", "my-new-file.txt");

//Copies the file to another Space.
$my_space->copyFile("my-file.txt", "my-new-file.txt", "my-other-space");

DigitalOcean only allows copying across Spaces in the same region.
You can supply a fourth argument to set the new file's privacy (public/private).
Returns info on the new file.

List all files inside your Space

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Lists all files inside your Space.
$my_space->listFiles();

//Lists all files in a folder inside your Space.
$my_space->listFiles("my-folder");

This function automatically iterates till it gets all files but you can set the second argument to false if you want to handle pagination yourself.
If you set the second argument to false, you can set the third argument to a ContinuationToken.
Returns an array of files but if the second argument is set to false, the original object is returned.

Check whether a file exists

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Returns true if this file exists, otherwise false.
$my_space->fileExists("my-file.txt");

Get info on a file

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Returns all available data on a file.
$my_space->fileInfo("my-file.txt");

Create a signed URL (Used for sharing private files)

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Returns a URL that'll work for 15 minutes for this file.
$my_space->signedURL("my-file.txt", "15 minutes");

Create an unsigned URL (Used for sharing public files)

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Returns a URL that'll work as long as the file is public.
$my_space->url("my-file.txt");

Change a file's privacy (Public & Private ACL)

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Make a file public.
$my_space->filePrivacy("my-file.txt", "public");

//Make a file private.
$my_space->filePrivacy("my-file.txt", "private");

Delete a file

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Deletes a single file.
$my_space->deleteFile("my-file.txt");

Delete an entire folder

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Deletes all content of a folder (Or any file paths that match the provided check string).
$my_space->deleteFolder("my-folder");

Change your Space's privacy (ACL)

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Makes your Space public. All your Space's files will be displayed to anyone.
$my_space->privacy("public");

//Makes your Space private.
$my_space->privacy("private");

List your Space's CORS rules

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Returns an array of your Space's CORS rules.
$my_space->getCORS();

This will throw an error if no CORS rules exist.

Set your Space's CORS rules

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//This allows all sources to use your file.
$my_space->setCORS([["origins" => ["*"], "methods" => ["GET", "HEAD", "OPTIONS"]]]);

Destroy your Space

Also deletes all files inside your Space

$my_space = Spaces("ACCESS KEY", "SECRET KEY")->space("my_space", "nyc3");

//Destroys your Space & deletes all its files.
$my_space->destroy();

isaacongoma / spaces-api

Maintainers

Details