README.md

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

  • Uploading a file
  • Uploading text
  • Uploading an entire folder
  • Downloading a file
  • Downloading your entire Space
  • Copy a Space file
  • List all files
  • Check if file exists
  • Retrieve file info
  • Create signed temporary sharing URL
  • Retrieve public file URL
  • Change a file's privacy
  • Delete a file
  • Delete an entire folder

• Spaces

  • Create a new Space
  • Use an existing Space
  • List all Spaces
  • Change your Space's privacy
  • List your Space's CORS rules
  • Change your Space's CORS rules
  • Destroy your Space

 

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

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

require_once("spaces.php");

 

b) The Composer Method

1. Make sure you have Composer.
2. Install Spaces-API:

composer require sociallydev/spaces-api:v2

3. 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();