RAWS Tutorial 2 : basic RASS operations with PHP client

In our first tutorial we explained how to manage files and directories on the Rambla CDN, using curl and the Rambla Storage Service (RASS). In this tutorial we will perform the same operations, this time using a PHP client library. This will show how easy it is to access Rambla Web Services (RAWS) programmatically, once you have grasped the basic REST concepts.

The raws-php project contains a free open source library for PHP. It requires cURL support for PHP to be enabled.

The complete source code for this tutorial is also part of the download package. You can try running it yourself, after having edited the named constants on top of the script:

# Provide the path to a local test file, that can be uploaded via RASS
define('LOCAL_FILE', '../recordings/taste.mp4');
# Provide your own RASS credentials here
define('USER', 'monty'); # your user account name
define('PWD', 'mypwd'); # your user account pwd
define('CDN', "cdn01"); # your sub-cdn (e.g. "cdn01")

The connection object

Before we can start to send requests, we need to instantiate an object that manages the RASS connection. The constructor requires (at least) three arguments: username, password and the base URL for the web-service.

require_once 'raws_json/rass_service.php';

$rass = new Rass("monty", "mypwd", "rass.cdn01.rambla.be");

Create directory

We will first create a new directory named "tutorial2" inside our account on cdn01. Therefore, we call the createDir() method on our RASS connection object, passing it the name of the directory. The method will send a PUT http://rass.cdn01.rambla.be/dir/tutorial2 request and process the response from RASS. If the request succeeds, our method will return a RASS dir entry object. Otherwise, it will raise an exception.

$dir = $rass->createDir("tutorial2");

The returned $dir variable represents the JSON entry that was returned by the 'PUT dir' request. Behind the scenes, the JSON object is translated into a stdClass object. For instance, the relative path of our new directory on the CDN is stored inside the 'path' param :

echo "\nCreated file with path: " . $item->entry->content->params->path . "\n";
>> Created directory with path: /tutorial2

Upload file

Next, we will upload our local file 'taste.mp4' to the "tutorial2" directory on the CDN, by calling createItem() on our RASS connection object. This function takes three arguments.

• In the first argument, we pass the path to a directory on the CDN in which the file will be stored. Since we want to store our file inside the 'tutorial2' directory that we've just created, we pass the string inside the 'path' param. If you would want to store the file under the root-directory of your CDN account, you should pass "/" instead.
• In the second argument, we pass the name that we want our uploaded file to have on the CDN. In this case, we want our file to be named "taste.mp4".
• The third argument contains the (absolute or relative) local path to the file we want to upload.

$item = $rass->createItem($dir->entry->content->params->path, "taste.mp4", LOCAL_FILE);

If the upload fails, the method call will raise an exception. If the upload succeeds, it will return a RASS item entry object. This object also has a 'path' param, which points to the relative path of the file on the CDN.

echo "\nCreated file with path: " . $item->entry->content->params->path . "\n";
>> Created file with path: /tutorial2/taste.mp4

In the same way, you can retrieve the filename by looking at the 'filename' param.

echo "Filename: " . $item->entry->content->params->filename . "\n";
>> Filename: taste.mp4

By calling get_enclosure_url($item), we can retrieve the URL for public download (-> which was returned inside a 'link' with the 'rel' attribute set to "enclosure").

echo "Public download location of the uploaded file: " . $rass->getEnclosureLink($item) . "\n";
>> Public download location of the uploaded file: http://monty.cdn01.rambla.be/tutorial2/taste.mp4

Upload same file twice

If we PUT the file for a second time to the same location, we will see that RASS adds a numerical suffix to the filename before storing it. Therefore, it is important that your code verifies the path or filename returned by the web-service.

$item = $rass->createItem($dir->entry->content->params->path, "taste.mp4", LOCAL_FILE);
echo "\nCreated file with path: " . $item->entry->content->params->path . "\n";
echo "Filename: " . $item->entry->content->params->filename . "\n";
echo "Public download location of the uploaded file: " . $rass->getEnclosureLink($item) . "\n";
>> Created file with path: /tutorial2/taste000.mp4
>> Filename: taste000.mp4
>> Public download location of the uploaded file: http://monty.cdn01.rambla.be/tutorial2/taste000.mp4

Delete file

Call deleteItem(), passing it the relative path to the file on the CDN. If the request fails, an exception is raised.

$rass->deleteItem($item->entry->content->params->path);

Delete directory

Call deleteDir(), passing it the relative path to the directory on the CDN. The second argument determines whether the directory will be deleted recursively. If set to False, deleteDir() will raise an exception if the directory is not empty. If True, deleteDir() will delete the directory recursively (including all files and sub-directories).

$rass->deleteDir($dir->entry->content->params->path, True);