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 (or atompub) concepts.

The raws-client project contains a free open source library for PHP. It requires the Gdata component of the Zend Framework to be installed (see the raws-client's INSTALL.txt file for more info). Documentation for the client API can be downloaded or consulted online.

The complete source code for this tutorial is also part of the download package (= 'rass_basics_manage_file_dir.php' in the 'samples' directory). 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 './RawsClient/Raws/Rass.php';
$rass = new Rass("monty", "mypwd", "http://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_DirEntry object. Otherwise, it will raise a Zend_Gdata_App_Exception.

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

The returned $dir_entry object encapsulates the ATOM entry that was returned by the 'PUT dir' request. Behind the scenes, the XML elements and attributes are translated to data-members of the entry object. For instance, the relative path of our new directory on the CDN is now stored inside the 'path' data-member of $dir_entry (-> in the XML structure, 'path' is an attribute of the 'entry' root-element):

echo "Created directory with path: . " $dir_entry->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 postItem() 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 'path' member of our $dir_entry object. 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_entry = $rass->postItem($dir_entry->path, "taste.mp4", '../recordings/taste.mp4');

If the upload fails, the method call will raise a Zend_Gdata_App_Exception. If the upload succeeds, it will return a Rass_ItemEntry object, which encapsulates the ATOM entry that was returned by the 'POST item' request. This object has a 'path' data-member which points to the relative path of the file on the CDN.

echo "Created file with path: " . $item_entry->path . "\n";
>> Created file with path: /tutorial2/taste.mp4

In the same way, you can retrieve the filename by looking at the text inside the 'name' element.

echo "Filename: " . $item_entry->content->params->name->text . "\n";
>> Filename: taste.mp4

By calling get_enclosure_url() on the entry object, we can retrieve the URL for public download (-> which was returned inside a 'link' sub-element with its 'rel' attribute set to "enclosure").

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

Upload same file twice

If we POST 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 uses the path or filename returned by the web-service.

$item_entry2 = $rass->postItem($dir_entry->path, "taste.mp4", LOCAL_FILE);
echo "Created file with path: " . $item_entry2->path . "\n";
echo "Filename: " . $item_entry2->content->params->name->text . "\n";
echo "Public download location of the uploaded file: " . $item_entry2->get_enclosure_url() . "\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

You can avoid this behaviour by sending a 'PUT item' request to RASS (instead of a 'POST item' request). In that case, RASS will return an error response if a file with the same relative path already exists on the CDN. To do this, call createItem() on the connection object (instead of postItem()). This will cause a Zend_Gdata_App_Exception to be raised if the file already exists:

$item_entry2 = $rass->createItem($dir_entry->path . "/taste.mp4", LOCAL_FILE);

Delete file

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

$rass->deleteItem($item_entry2->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 (= default), 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->path, True);