HPCloud-PHP  1.2.0
PHP bindings for HPCloud and OpenStack services.
 All Classes Namespaces Files Functions Variables Pages
About HPCloud-PHP

This is the documentation for the HPCloud PHP library.

Overview

HPCloud provides public cloud infrastructure that is business-grade, open source-based, and developer focused. Built on OpenStack, it provides many cloud-based services that developers can take advantage of when building robust and reliable websites.

The HPCloud-PHP library provides PHP developers with a fully tested, robust, and feature-rich library for working with the HPCloud services.

Attention
Making use of this library will require that you have several pieces of account information for your HPCloud account (or OpenStack account, if you're using this library with non-HP OpenStack implentations):
  • account ID and secret key: For cases where you want account-wide authentication/authorization.
  • username/password: Typically, this is the same username/password you use to access the HPCloud console.
  • tenant ID: This associates an account or user with a bundle of services. You can find this information in your console.
  • endpoint: You will need the URL to the HPCloud endpoint responsible for authenticating users. This can be found in your console.

(If you are not sure what the "HPCloud Console" is, head over to http://docs.hpcloud.com. There you will find some articles and videos explaining the HPCloud structure.)

Where To Start

Cruising a list of methods and classes is not exactly the best way to get started with a library. It's better to know where to start. Here's what we suggest:

  • There are a few tutorials inside this documentation that will help you get started. One explains Stream Wrappers and the other the library itself.
  • Connecting and logging in is almost inevitably going to be your first task. For that, you will want to look at IdentityServices.
  • ObjectStorage (a.k.a. swift) is our cloud storage system. There are two ways to use it:
    • You can explore the object oriented API, starting with ObjectStorage.
    • You can use the PHP stream wrappers to access your object storage. This is explained in StreamWrapper.

Learn More

This documentation is intended to provide a detailed reference to the HPCloud-PHP library. But this ain't all we've got. Tutorials, videos, screencasts, a knowledge base, and active community forums are just a click away.

Head over to http://docs.hpcloud.com to find these and other resources.

Or maybe you'd just like to see a couple of examples.

Basic Example: Stream Wrappers

The super-simple stream API:

<?php
// This is only required if you don't have a PSR-0
// autoloader to do the hard work for you.
require 'HPCloud/Bootstrap.php';
// If you aren't using a PSR-0 autoloader,
// you might want to use this:
\HPCloud\Bootstrap::useAutoloader();
// Turn on stream wrappers.
\HPCloud\Bootstrap::useStreamWrappers();
// Create a stream context. You can get this
// information (including tenant ID) from your
// HPCloud console.
$cxt = stream_context_create(array(
'username' => 'matthew.butcher@hp.com',
'password' => 'secret',
'tenantid' => '123456',
'endpoint' => 'http://url.from.hpcloud.com/',
));
// Get an object from the remote object storage and read it as a string
// right into $myObject.
$myObject = file_get_contents('swift://mycontainer/foo.txt', FALSE, $cxt);
?>

With stream wrapper support, you can transparently read and write files to the HPCloud ObjectStorage service without using any fancy API at all. Use the normal file methods like this:

Basic Example: Identity Services

Stream wrappers are nice and all, but some of us love fancy APIs. So here's an example using the full API to log in and then dump a list of services that are available to you:

<?php
// This is only required if you don't have a PSR-0
// autoloader to do the hard work for you.
require 'HPCloud/Bootstrap.php';
// If you aren't using a PSR-0 autoloader,
// you might want to use this:
\HPCloud\Bootstrap::useAutoloader();
use \HPCloud\Services\IdentityServices;
// Create a new identity service object, and tell it where to
// go to authenticate. This URL can be found in your HPCloud
// console.
$identity = new IdentityServices('http://get.url.from.hpcloud.com');
// You can authenticate either with username/password (IdentityServices::authenticateAsUser())
// or as an account/secret key (IdentityServices::authenticateAsAccount()). In either
// case you can get the info you need from the console.
$account = '123456789098765';
$secret = 'dgasgasd';
$tenantId = '56545654';
// $token will be your authorization key when you connect to other
// services. You can also get it from $identity->token().
$token = $identity->authenticateAsAccount($account, $secret, $tenantId);
// Get a listing of all of the services you currently have configured on
// HPCloud.
$catalog = $identity->serviceCatalog();
var_dump($catalog);
?>
  1. Our classes use PHP namespaces to organize components. If you've never used them before, don't worry. They're easy to get the hang of.
  2. The Bootstrap class handles setting up HPCloud services. Read about it at HPCloud::Bootstrap.
  3. The IdentityServices class handles authenticating to HP, discovering services, and providing access to your account. HPCloud::Services::IdentityServices explains the details, but here are a few functions you'll want to know:

Basic Example: Object Storage

Assuming you have an object storage instance available in your service catalog, we could continue on with something like this:

<?php
// The explicit way:
// Find out where our ObjectStorage instance lives:
// $storageList = $identity->serviceCatalog('object-storage');
// $objectStorageUrl = storageList[0]['endpoints'][0]['publicURL'];
// Create a new ObjectStorage instance:
// $objectStore = new \HPCloud\Storage\ObjectStorage($token, $objectStorageUrl);
// Or let ObjectStorage figure out which instance to use:
$objectStore = \HPCloud\Storage\ObjectStorage::newFromIdentity($identity);
// List containers:
print_r($objectStore->containers());
// Get a container named 'stuff':
$container = $objectStore->container('stuff');
// List all of the objects in that container:
print_r($container->objects());
// Get an object named 'example.txt'
$obj = $container->object('example.txt');
// Print that object's contents:
print $obj->content();
// Actually, since it implements __tostring, we could do this:
print $obj;
?>

This shows you a few methods for accessing objects and containers on your HPCloud::Storage::ObjectStorage account. There are many functions for creating and modifying containers and objects, too.