PHP bindings for HPCloud and OpenStack services.
In this tutorial, we will walk through the process of creating a simple tool that interacts with HP Cloud's Object Storage. The emphasis in this article is on getting started and learning the concepts, not building a polished product.
This tutorial focuses on the object-oriented API. The other way to work with this library is through the stream wrapper. That topic is covered in another tutorial.
HPCloud-PHP has been developed to require PHP 5.3 or later. You are strongly encouraged to also install the CURL PHP extension. Many distributions of PHP come with this enabled. Sometimes, though, you may need to do something like
apt-get php5-curl or similar. (Don't take our word for it – check your system's documentation.)
You can check for both of these conditions by checking the output of
php --info (on the commandline) or
<?php phpinfo(); ?>.
In our pre-flight check, we would be remiss if we didn't point out that there are some requirements for the pilot (that's you), too.
The HPCloud library is composed of two parts:
The object-oriented library makes ample use of PHP namespaces. If you've never seen these before, they look like this:
The namespace above is read like this: "The RemoteObject class is part of the ObjectStorage package in the Storage package in the base HPCloud package." Those familiar with Java, Python, and other languages will recognize this way of talking (though the backslash is an unfortunate symbol choice).
For our library, we followed the recommendation of SPR-0, which means that the class above can be found in the file at:
The pattern of matching namespace to file name should (we hope) make it easier for you to navigate our code.
If this namespace stuff continues to confuse you, you may want to take a look at the PHP documentation, or you may just prefer to keep on reading and learn by example. We don't do anything really fancy with namespaces.
**In this document, we sometimes replace the backslash (\) with double colons (
::) so that links are automatically generated.** So
\HPCloud\Bootstrap may appear as HPCloud::Bootstrap. The reason for this is explained elsewhere.
You can get the HPCloud-PHP library at the HPCloud GitHub Repository. The latest code is always available there.
The project also uses Composer, and this is the best method for adding HPCloud-PHP to your PHP project.
For our example, we will assume that the library is accessible in the default include path, so the following line will include the
The first thing to do in your application is make sure the HPCloud library is bootstrapped. When we say "bootstrap", what we really mean is letting the library initialize itself.
Bootstrapping does not always involve any manual interaction on your part. If you are using an SPR-0 autoloader that knows of the HPCloud directory, that is enough for the system to initialize itself.
Sometimes, though, you will need to bootstrap HPCloud in your own code, and this is done as follows:
The first line should be self-explanatory: We require the main
Bootstrap.php file (which contains the
After that, we declare a list of namespaced objects that we will use. This way we can refer to them by their short name, rather than by their fully qualified name.
The last line initializes the built-in HPCloud autoloader. What does this mean? It means that this is the only
include statement you need in your code. The library does the rest of the including for you, on demand, in a performance-sensitive way.
There are some other fancy things that HPCloud::Bootstrap can do for you. Most notably, you can pass configuration parameters into it. But for the time being, we are good to go.
Our library is boostrapped. Next up: Let's connect to our account.
Our programming goal, in this tutorial, is to interact with the Object Storage service on HP Cloud. (Object Storage is, for all intents and purposes, basically a service for storing files in the cloud.)
But before we can interact directly with Object Storage, we need to authenticate to the system. And to do this, we need the following four pieces of information:
Before you issue a forlorn sigh, envisioning some laborious task, let us point out that all of this information is available in one place, Log into the console and go to the
API Keys page. It's all there.
The HPCloud is composed of numerous services. There's the Compute service, the Object Storage service, the CDN service... and so on.
Authenticating separately to each of these would be a collosal waste of network resources. And behind the scenes, account management would be difficult on the server side.
That's where Identity Services comes in. It is a central service that handles all things authorization and authentication related. Roughly, it works as follows:
The token is valid for some fixed period of time (say, 30 minutes), during which time it can be used for every other service. Each request to an HPCloud service should send (along with other info) the token. The remote service then validates the token with identity services, saving our app the trouble of making another round trip.
The service catalog lists all of the HPCloud services that the present account can access.
With that little bit of theory behind us, we can now go about authenticating.
Assuming the variables above have been set to include valid data, this script can connect to HPCloud and authenticate.
authenticateAsAccount() method will authenticate to the Identity Services endpoint. For convenience, it returns the authorization token (
$token), though we can also get the token from
Note that the
IdentityServices object may throw various exceptions (all subclasses of HPCloud::Exception) during authentication. Failed authentication results in an HPCloud::Transport::AuthorizationException, while a network failure may result in an HPCloud::Transport::ServerException.
Earlier, we talked about the service catalog. Once we've authenticated, we can get the service catalog from
$idService->serviceCatalog(). It is an associative array, and you can get an idea of what it contains by dumping it with
var_dump(), should you so desire.
At this point, we have what we need from Identity Services. It's time to look at Object Storage.
Instances of HPCloud::Services::IdentityServices are responsible for:
The Object Storage system is concerned with two classes of things:
Your object storage can have any number of containers, and each container can have any number of objects.
In the object model for the HPCloud PHP library, a top-level object called HPCloud::Storage::ObjectStorage provides access to the Object Storage service. In this step, we will be working with that object.
Earlier, we created an
IdentityServices instance called
$idService. We will use that here to get the service catalog. Once we have the catalog, we can have a new
ObjectStorage instance created for us, configured to talk to our account's Object Storage instance in the HPCloud. Along with the service catalog, we also need our token that shows the Object Storage endpoint that we have already authenticated to Identity Services. Earlier, we captured that value in the
Now we can get a new HPCloud::Storage::ObjectStorage instance:
First we get the service catalog (
$catalog), and then we use the
ObjectStorage::newFromServiceCatalog() static method to create the new Object Storage instance.
The pattern of using a constructor-like static function is used throughout the HPCloud PHP library. Inspired by Objective-C constructors and the Factory design pattern, it makes it possible for a single class to have multiple constructors.
In particular, many top-level classes provide a
newFromServiceCatalog() constructor function, since these classes know how to construct instances from a service catalog, thus freeing the developer up from knowing the details of a service catalog entry.
Now we have an
ObjectStorage instance that is already configured to talk to our HPCloud object storage service. Next, we can create a container.
Instances of HPCloud::Storage::ObjectStorage are responsbile for:
Before we can start putting objects (files) into our Object Storage service, we need a place to put them. An Object Storage service can hold numerous containers (and each container can have different access controls – a topic we won't get into here).
Containers are represented in the library by the HPCloud::Storage::ObjectStorage::Container class. And creating a container is done by a method on the
ObjectStorage object that we created above:
$store is the name of our
ObjectStorage instance. In the first of the two lines above, we create a new container named
Example. Then in the second line, we get that container.
Why is this two steps? The answer is that the HPCloud PHP library mimics the architecture of the underlying API. This is two operations (which means it requires two network requests to the remote host), and so we must perform two operations.
createContainer() call actually creates the new container on the cloud's Object Storage. The second call connects to the remote object storage, and gets the new container. The container that is returned will have some additional information, such as the amount of space it takes up on the remote storage, and the access control rules for that container. All of this information will be available on the
$container instance is an instance of HPCloud::Storage::ObjectStorage::Container. This object can be used not only to find out about a container, but also to get information about the objects in that container.
Now that we have a
Container, we can add an object.
(Yes, we realize the irony of that title.)
A HPCloud::Storage::ObjectStorage::Container instance is responsible for the following:
Among the features of a Container, it can act like an
Iterator and is
Countable. That means you can loop through a Container in a
foreach loop and also use
count($container) to find out the number of objects in a Container.
Now we are ready to create an object, and then store it in our container.
Before diving too deeply, it is important to point out a detail: When working with a remote data storage service, we are typically working with a local copy and a remote copy. If our code isn't constructed correctly, it is possible for these two to get out of sync.
Earlier, we created a container directly on the remote side, and then fetched the container. As we create an object, we are going to do the opposite: We will create a local object, and then save it to the remote storage. Later, we will fetch the remote object.
In the code above, we create
$localObject with a
$content, and a
$mime type. Strictly speaking, only
$name is required.
The HPCloud::Storage::ObjectStorage::Object class is used primarily to describe a locally created object. Once we have our new
Object, we can save it remotely using the
save() method on our
$container object. This will push the object to the remote object storage service.
While we can continue manipulating
$localObject, we are working with the local version, not the latest version of what's on the server. This is fine if what we are doing is writing more data. However, when examining the content of the object, remember that we are working with the local copy, and its properties may differ from the remote copy's.
Objects, like files on a file system, are referenced by name. Any time you
save() an object, it will be pushed to the remote object storage server, which will happily replace the old content with your newly submitted content.
Next let's turn to loading objects from the remote object storage.
The HPCloud::Storage::ObjectStorage::Object instances are used for:
This class is also the base class for the
RemoteObject class that we will look at later.
The API is generally constructed so that a developer needn't worry about the differences between an
Object and a
RemoteObject. But in all but the edgiest of edge cases, you would only create an instance of
Object, never of
Containers not only provide the methods for saving objects, but also for loading objects. Thus, we can fetch the object that we just created:
$object variable now references an instance of a HPCloud::Storage::ObjectStorage::RemoteObject that contains the entire object.
RemoteObject represents an object that was loaded from the remote server. Along with providing the features of the
Object class we saw earlier, it also provides numerous optimizations for working over the network.
Now that we have the object, we print out several pieces of information –
type(). Then, using
content(), we fetch the content of the object.
The method we used above to fetch the object is perfect for our needs. It pulls the entire object down in a single request. But imagine this scenario: Our object storage has large media files, and we don't know at loading time whether or not we need to access the body content, or just the other data about the object.
It would be a time-consuming task to download the entire body of a large media file if we don't actually use the body. On the other hand, from an API standpoint it is great to be able to pass around a single object, and not require the application to know whether or not the body has been retrieved.
RemoteObject solves this problem using a technique known as "lazy
loading". That is, it can pull some of the data right away, but defer fetching the rest of the data until that data is actually needed.
To fetch an object this way, we can just swap out one line in the example above:
Instead of using
object(), we now use
proxyObject(). This method immediately loads the core data about the remote object, but defers fetching the content until the content is requested.
In the example above, then, one network request is issued by
proxyObject(), but another is initiated when
$object->content() is called.
Instances of a HPCloud::Storage::ObjectStorage::RemoteObject offer the following features:
RemoteObject instances can be updated and then passed to
Container::save() to update the copy on the server, too.
At this point we have created a very basic script that connects to HPCloud and works with object storage. Clearly, this only scratches the surface of what the HPCloud PHP library does. But hopefully this is enough to get you started with the library.
The entire library is well documented, and the documentation is available online. You can also build a local copy by installing doxygen (if you haven't already) and running
make docs in the root of the HPCloud PHP project. This will place the generated documents in