Rackspace Cloud Files and php

This article will explain how to use the Rackspace Cloud Files API with php using the php-cloudfiles bindings. All this information is available online, some on Rackspace KB articles, github, API docs. But for somebody who is just now starting with cloud files, it’s not possible to gather all this information without wasting few days time here and there. So, the objective of this article is to provide :

All the available links to Cloud Files documentation, API, and PHP bindings.
PHP Cloud Files binding installation
PHP Cloud Files binding coding examples

Cloud Files Documentation links:

Cloud Files FAQ: for answer to questions like, what is cloud files, what you can and you cannot do with cloud files. http://www.rackspace.com/knowledge_center/index.php/Cloud_Files_FAQ
API Introduction: API Introduction pdf file explains about Cloud Files product and it's use cases, features. http://docs.rackspace.com/files/api/cf-intro-latest.pdf
API Developer Guide: API Developer Guide lists RESTful API of cloud files, means how to query/store/retrive data from cloud files using a programming language, like php, asp, .NET, python, etc. http://docs.rackspace.com/files/api/cf-devguide-latest.pdf

In addition to all above Rackspace also have different language bindings which allows to interact with API easy. In this article we will concentrate on using php-cloudfiles language bindings.

PHP Cloud Files bindings on github.com https://github.com/rackspace/php-cloudfiles

PHP Cloud Files binding installation

Download a package from there using the Download link to your cloud server, and then extract it.

[root@web01 ~]# ls -la | grep cloudfiles
-rw-r--r--  1 root   root   496476 Oct  1 16:09 rackspace-php-cloudfiles-v1.7.9-0-gb5e5481.zip
[root@web01 ~]#
[root@web01 ~]# unzip rackspace-php-cloudfiles-v1.7.9-0-gb5e5481.zip
[root@web01 ~]#
[root@web01 ~]# ls -la | grep cloudfiles
drwxr-xr-x  6 root   root     4096 Oct  1 16:36 rackspace-php-cloudfiles-b5e5481
-rw-r--r--  1 root   root   496476 Oct  1 16:09 rackspace-php-cloudfiles-v1.7.9-0-gb5e5481.zip
[root@web01 ~]#

Once extracted, the folder should look something like this:

[root@web01 rackspace-php-cloudfiles-b5e5481]# ls
AUTHORS    cloudfiles_exceptions.php  cloudfiles.php  debian  phpdoc.ini   README  tests
Changelog  cloudfiles_http.php        COPYING         docs    phpunit.xml  share
[root@web01 rackspace-php-cloudfiles-b5e5481]#

Now we need to copy the cloudfiles API files to a place where they can be included in your php files, means source code files of API should be in PHP Include path.

As per the README file, following are the requirements for using API source code files:

Requirements
;; ------------------------------------------------------------------------
;;   [mandatory] PHP version 5.x (developed against 5.2.0)
;;   [mandatory] PHP's cURL module
;;   [mandatory] PHP enabled with mbstring (multi-byte string) support
;;   [suggested] PEAR FileInfo module (for Content-Type detection)
;;

You can check all these with the following commands:


[root@web01 ~]# php -v
PHP 5.1.6 (cli) (built: Nov 29 2010 16:47:46)
Copyright (c) 1997-2006 The PHP Group
Zend Engine v2.1.0, Copyright (c) 1998-2006 Zend Technologies
[root@web01 ~]#

Let’s check if curl is installed:

[root@web01 ~]# php -m | grep curl
curl
[root@web01 ~]#

Now let’s check mbstring

[root@web01 ~]# php -m | grep mbstring
[root@web01 ~]#

It looks like we don’t have mbstring installed, so let’s install it as well.

[root@web01 ~]# yum install php-mbstring

Similarly for FileInfo

[root@web01 ~]# php -m | grep file
[root@web01 ~]#
[root@web01 ~]# yum install php-pecl-Fileinfo
[root@web01 ~]# php -m | grep fileinfo
fileinfo
[root@web01 ~]#
[root@web01 ~]# cd rackspace-php-cloudfiles-b5e5481/
[root@web01 rackspace-php-cloudfiles-b5e5481]#

Remember you might have to change the folder name to reflect your own copy of the API

Now that we are in the source directory of php-cloudfiles, let’s move the required files to the right place. Run the following commands, and move them to /usr/share/php. This directory is part of the php include PATH.

[root@web01 rackspace-php-cloudfiles-b5e5481]# mkdir /usr/share/php
[root@web01 rackspace-php-cloudfiles-b5e5481]# cp cloudfiles* /usr/share/php/

After moving the php-cloudfiles API binding files into the php include PATH, now lets check it to make sure we have everything is setup ok. We will create a simple php file and include the php-cloudfiles binding file into it.

[root@web01 rackspace-php-cloudfiles-b5e5481]# cd /var/www/html/
[root@web01 html]# touch cfcheck.php

Open your favorite text editor, e.g. vi editor, and type the following into cfcheck.php file:

<?php
    require('cloudfiles.php'); 
?>

Save the file cfcheck.php and run this command from the prompt:

[root@web01 html]# php cfcheck.php
[root@web01 html]#

Check the error state of the last command. It should be 0.

[root@web01 html]# echo $?
0
[root@web01 html]#

If you are returned to the prompt with no errors the PHP API is installed

If you get an error like this:

PHP Fatal error:  require(): Failed opening required 'cloudfiles.php'
(include_path='.;C:\php5\pear') in cfcheck.php on line 1

Then you do not have the files located in the right place. This error should print out the include_path so make sure you have the files located there. Or you can change the include path in the php.ini but that is beyond the scope of this tutorial.

PHP Cloud Files binding coding examples

Okay.. I hope by now you have API installed. If yes, then let’s move onto actually trying some php cloud files code. If you are having problem with installing the API, then probably you should troubleshoot the above first before moving on.

For an easy access to php-cloudfiles documentation, run the following commands:

[root@web01 html]# cd rackspace-php-cloudfiles-b5e5481/
[root@web01 rackspace-php-cloudfiles-b5e5481]# cp -R docs/ /var/www/html/
[root@web01 rackspace-php-cloudfiles-b5e5481]# service httpd start

After this you can access the documentation at http:///docs url.

If you are a developer, then you can easily check the documentation and work from there, but let me put some examples here for non-developer or newbies.

Basically, whenever you put

require('cloudfiles.php');

line in any of your php file, the following classes become available into your php code.

Classes:

CF_Authentication: Class for handling Cloud Files Authentication, call it's authenticate() method to obtain authorized service urls and an authentication token.
CF_Connection: Class for establishing connections to the Cloud Files storage system.
CF_Container: Container operations
CF_Object: Object operations

Each class comes with it’s own methods and properties. Methods can be called on the objects of those classes and their properties can be set and queried. For e.g. CF_Authentication class provides methods for authentication against the cloud files using the username and API key of your cloud files accounts. CF_Connection class provides a connection object. Connection object has methods like create_container, delete_container. Let’s look at the following code example.

Continuing on our previous example of cfcheck.php file, let’s add some more code into it.

[root@web01 html]# vi cfcheck.php


<?php         
       require('cloudfiles.php');
       $username='your cloud user name';
       $api_key="your cloud api key";
       $auth = new CF_Authentication($username, $api_key);
       $auth->authenticate();

        if ( $auth->authenticated() )
                echo "CF Authentication successful \n";
        else
                echo "Authentication faile \n";
?>

[root@web01 html]# php cfcheck.php
CF Authentication successful
[root@web01 html]#

if the above command runs without producing any error, then it means you have successfully authenticated against CF using the above php code. In the above code, first we created an object of CF_Authentication named auth by passing it username and API key as variables. Then we run authenticate() method of the CF_Authentication class which actually authenticates against the cloud files. Similarly, authenticated() method returns a boolean value (true or false) depending on the state of the auth object. I cannot be more explicit than this. if you are having problem understanding this, then you should probably not be doing this by yourself and get a developer, but if you still following so far and it’s working fine, let’s move forward… and add some more lines to our code.

<?php         
       require('cloudfiles.php');
       $username='your cloud user name';
       $api_key="your cloud API key";
       $auth = new CF_Authentication($username, $api_key);
       $auth->authenticate();

       if ( $auth->authenticated() )
                echo "CF Authentication successful \n";
       else
                echo "Authentication faile \n";
       $conn = new CF_Connection($auth);
       $container_list = $conn->list_containers();
       print_r($container_list);

?>

[root@web01 html]# php cfcheck.php
CF Authentication successful
Array
(
    [0] => .CDN_ACCESS_LOGS
    [1] => cloudservers
    [2] => images
    [3] => sand
)
[root@web01 html]#

The output would be different depending on the containers you have in your cloud files and their names. Above are the name of the containers in my account. It might not list any containers if you don’t have one in your cloud files, but that’s okay. We will create container in the next lines. But as you can see in the code we added the following lines:


        $conn = new CF_Connection($auth);
        $container_list = $conn->list_containers();
        print_r($container_list);

we created a new CF_Connection object named conn and using this object, we got a list of all the containers with list_containers() method. list_containers() method gives us an array object in return containing the names of all the containers in your cloud files storage, in this examples I have used the print_r function to print the array in human readable format.

Well, I can add more code lines for creating container, deleting container, getting details of container like public URI, snet, etc., but that would be going too far and seems redundant as similar stuff is self explanatory in the API documentation.

But I do hope this article will give you a head start and helps you in finding the correct documentation and resources for your cloud files API and php coding. Do let me know how did you like it, and if there were any errors or typos, I would like to help back and improve it.

– Sandeep Sidhu