Documentation changes to OpenStack branding
This commit is contained in:
Matt Farina
parent
3ff94e9060
commit
1daffdb76a
23
README.md
23
README.md
@ -1,21 +1,21 @@
|
||||
# HPCloud-PHP
|
||||
# OpenStack PHP-Client
|
||||
|
||||
This package provides PHP OpenStack bindings for the HP Cloud.
|
||||
This package provides PHP OpenStack bindings.
|
||||
|
||||
You can use this library to:
|
||||
|
||||
* Authenticate your application to the HP Cloud.
|
||||
* Authenticate your application to OpenStack.
|
||||
* Interact with Object Storage (aka Swift).
|
||||
|
||||
Coming soon:
|
||||
|
||||
* Intect with the Compute (Nova) manager.
|
||||
* Interact with other HP Cloud services
|
||||
* Interact with other OpenStack services
|
||||
|
||||
## Requirements
|
||||
|
||||
* PHP 5.3
|
||||
* An active HPCloud account with the desired services.
|
||||
* An active OpenStack account with the desired services.
|
||||
|
||||
### Suggestions
|
||||
|
||||
@ -37,7 +37,7 @@ builds because these cover our needs.
|
||||
#### Method #1:
|
||||
|
||||
Use [Composer](http://getcomposer.org) to download and install the
|
||||
latest version of HPCloud-PHP.
|
||||
latest version of OpenStack.
|
||||
|
||||
#### Method #2:
|
||||
|
||||
@ -63,23 +63,23 @@ reading and writing files into object storage.
|
||||
|
||||
#### Autoloading
|
||||
|
||||
HPCloud is [PSR-0 compliant](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md),
|
||||
OpenStack PHP-Client is [PSR-0 compliant](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md),
|
||||
which means that it should work with any PSR-0 autoloader. However,
|
||||
it also comes with its own autoloader for apps that don't yet make use
|
||||
of a standard autoloader.
|
||||
|
||||
#### Composer Support
|
||||
|
||||
HPCloud-PHP is available as part of the Packagist archive, which means
|
||||
OpenStack PHP-Client is available as part of the Packagist archive, which means
|
||||
you can use Composer to automatically download, install, and manage
|
||||
revisions to HPCloud-PHP from within your project.
|
||||
revisions to OpenStack from within your project.
|
||||
|
||||
We're big fans of [Composer](http://getcomposer.org).
|
||||
|
||||
|
||||
## More information
|
||||
|
||||
[HP Cloud](http://hpcloud.com) is a cloud computing platform that
|
||||
[OpenStack](http://OpenStack.org) is a cloud computing platform that
|
||||
provides many services, inlcuding compute installs, object and block
|
||||
storage, and a host of hosted services.
|
||||
|
||||
@ -88,6 +88,3 @@ This library provides access to those services.
|
||||
The best source of documentation is the official API documentation,
|
||||
which is available at
|
||||
http://hpcloud.github.com/HPCloud-PHP/doc/api/html/index.html
|
||||
|
||||
----
|
||||
HPCloud-PHP is maintained by the Developer Experience team at HP Cloud Services.
|
||||
|
||||
@ -22,6 +22,6 @@
|
||||
"curl": ">=7.0.0"
|
||||
},
|
||||
"autoload": {
|
||||
"psr-0": { "HPCloud": "src", "OpenStack": "src" }
|
||||
"psr-0": { "OpenStack": "src" }
|
||||
}
|
||||
}
|
||||
|
||||
@ -1,36 +1,28 @@
|
||||
<?php
|
||||
/** @mainpage About HPCloud-PHP
|
||||
/** @mainpage About the OpenStack PHP-Client
|
||||
*
|
||||
* This is the documentation for the HPCloud PHP library.
|
||||
* This is the documentation for the OpenStack PHP-Client library.
|
||||
*
|
||||
* @section about_package Overview
|
||||
*
|
||||
* <a href="http://hpcloud.com">HPCloud</a> provides public cloud
|
||||
* infrastructure that is business-grade, open source-based, and developer
|
||||
* focused. Built on <a href="http://openstack.org">OpenStack</a>, it provides
|
||||
* many cloud-based services that developers can take advantage of when
|
||||
* building robust and reliable websites.
|
||||
* <a href="http://www.openstack.org">OpenStack</a> is open source software for
|
||||
* building public and private clouds.
|
||||
*
|
||||
* The HPCloud-PHP library provides PHP developers with a fully tested,
|
||||
* robust, and feature-rich library for working with the HPCloud services.
|
||||
* The PHP-Client library provides PHP developers with a fully tested,
|
||||
* robust, and feature-rich library for working with the OpenStack 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 information for your OpenStack account:
|
||||
* - 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.
|
||||
* to access the 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
|
||||
* - endpoint: You will need the URL to the OpenStack endpoint responsible for
|
||||
* <i>authenticating users</i>. 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.)
|
||||
*
|
||||
* @section where_to_start Where To Start
|
||||
*
|
||||
* Cruising a list of methods and classes is not exactly the best way to get
|
||||
@ -42,7 +34,7 @@
|
||||
* the other [the library itself](@ref oo-tutorial).
|
||||
*- 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
|
||||
*- ObjectStorage (a.k.a. swift) is the 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
|
||||
@ -51,13 +43,8 @@
|
||||
* @section learn_more 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.
|
||||
* PHP-Client library. To learn more about the APIs and OpenStack visit
|
||||
* http://api.openstack.org/ and http://docs.openstack.org/.
|
||||
*
|
||||
* @section intro_example_sw Basic Example: Stream Wrappers
|
||||
*
|
||||
@ -67,20 +54,20 @@
|
||||
* <?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';
|
||||
* require 'OpenStack/Bootstrap.php';
|
||||
*
|
||||
* // If you aren't using a PSR-0 autoloader,
|
||||
* // you might want to use this:
|
||||
* \HPCloud\Bootstrap::useAutoloader();
|
||||
* \OpenStack\Bootstrap::useAutoloader();
|
||||
*
|
||||
* // Turn on stream wrappers.
|
||||
* \HPCloud\Bootstrap::useStreamWrappers();
|
||||
* \OpenStack\Bootstrap::useStreamWrappers();
|
||||
*
|
||||
* // Create a stream context. You can get this
|
||||
* // information (including tenant ID) from your
|
||||
* // HPCloud console.
|
||||
* // OpenStack console.
|
||||
* $cxt = stream_context_create(array(
|
||||
* 'username' => 'matthew.butcher@hp.com',
|
||||
* 'username' => 'foo@example.com',
|
||||
* 'password' => 'secret',
|
||||
* 'tenantid' => '123456',
|
||||
* 'endpoint' => 'http://url.from.hpcloud.com/',
|
||||
@ -95,7 +82,7 @@
|
||||
* @endcode
|
||||
*
|
||||
* 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
|
||||
* ObjectStorage service without using any fancy API at all. Use the
|
||||
* normal file methods like this:
|
||||
*
|
||||
*- fopen()/fclose()
|
||||
@ -105,9 +92,9 @@
|
||||
*- is_readable()/is_writable()
|
||||
*- And so on (http://us3.php.net/manual/en/ref.filesystem.php).
|
||||
*
|
||||
* Learn more about this at HPCloud::Storage::ObjectStorage::StreamWrapper.
|
||||
* Learn more about this at OpenStack::Storage::ObjectStorage::StreamWrapper.
|
||||
*
|
||||
* @section intro_example_ident Basic Example: Identity Services
|
||||
* @section intro_example_ident Basic Example: Identity Service
|
||||
*
|
||||
* Stream wrappers are nice and all, but
|
||||
* some of us love fancy APIs. So here's an example using the full API
|
||||
@ -117,21 +104,20 @@
|
||||
* <?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';
|
||||
* require 'OpenStack/Bootstrap.php';
|
||||
*
|
||||
* // If you aren't using a PSR-0 autoloader,
|
||||
* // you might want to use this:
|
||||
* \HPCloud\Bootstrap::useAutoloader();
|
||||
* \OpenStack\Bootstrap::useAutoloader();
|
||||
*
|
||||
* use \HPCloud\Services\IdentityServices;
|
||||
* use \OpenStack\Services\IdentityService;
|
||||
*
|
||||
* // 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');
|
||||
* // go to authenticate. This URL can be found in your console.
|
||||
* $identity = new IdentityService('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
|
||||
* // You can authenticate either with username/password (IdentityService::authenticateAsUser())
|
||||
* // or as an account/secret key (IdentityService::authenticateAsAccount()). In either
|
||||
* // case you can get the info you need from the console.
|
||||
* $account = '123456789098765';
|
||||
* $secret = 'dgasgasd';
|
||||
@ -141,8 +127,8 @@
|
||||
* // 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.
|
||||
* // Get a listing of all of the services you currently have configured in
|
||||
* // OpenStack.
|
||||
* $catalog = $identity->serviceCatalog();
|
||||
*
|
||||
* var_dump($catalog);
|
||||
@ -152,16 +138,16 @@
|
||||
*
|
||||
*-# 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.
|
||||
*-# The Bootstrap class handles setting up HPCloud services. Read about it at HPCloud::Bootstrap.
|
||||
*-# The IdentityServices class handles authenticating to HP, discovering services, and providing
|
||||
* access to your account. HPCloud::Services::IdentityServices explains the details, but here are
|
||||
*-# The Bootstrap class handles setting up OpenStack services. Read about it at OpenStack::Bootstrap.
|
||||
*-# The IdentityServices class handles authenticating to OpenStack, discovering services, and providing
|
||||
* access to your account. OpenStack::Services::IdentityService explains the details, but here are
|
||||
* a few functions you'll want to know:
|
||||
* - HPCloud::Services::IdentityServices::__construct() tells the object where to connect.
|
||||
* - HPCloud::Services::IdentityServices::authenticateAsUser() lets you log
|
||||
* - OpenStack::Services::IdentityService::__construct() tells the object where to connect.
|
||||
* - OpenStack::Services::IdentityService::authenticateAsUser() lets you log
|
||||
* in with username and password.
|
||||
* - HPCloud::Services::IdentityServices::authenticateAsAccount() lets you log
|
||||
* - OpenStack::Services::IdentityService::authenticateAsAccount() lets you log
|
||||
* in with account number and secret key.
|
||||
* - HPCloud::Services::IdentityServices::serviceCatalog() tells you about
|
||||
* - OpenStack::Services::IdentityService::serviceCatalog() tells you about
|
||||
* the services you have activated on this account.
|
||||
*
|
||||
* @section intro_example_swift Basic Example: Object Storage
|
||||
@ -177,10 +163,10 @@
|
||||
* // $objectStorageUrl = storageList[0]['endpoints'][0]['publicURL'];
|
||||
*
|
||||
* // Create a new ObjectStorage instance:
|
||||
* // $objectStore = new \HPCloud\Storage\ObjectStorage($token, $objectStorageUrl);
|
||||
* // $objectStore = new \OpenStack\Storage\ObjectStorage($token, $objectStorageUrl);
|
||||
*
|
||||
* // Or let ObjectStorage figure out which instance to use:
|
||||
* $objectStore = \HPCloud\Storage\ObjectStorage::newFromIdentity($identity);
|
||||
* $objectStore = \OpenStack\Storage\ObjectStorage::newFromIdentity($identity);
|
||||
*
|
||||
* // List containers:
|
||||
* print_r($objectStore->containers());
|
||||
@ -203,36 +189,36 @@
|
||||
* @endcode
|
||||
*
|
||||
* This shows you a few methods for accessing objects and containers on your
|
||||
* HPCloud::Storage::ObjectStorage account. There are many functions for
|
||||
* OpenStack::Storage::ObjectStorage account. There are many functions for
|
||||
* creating and modifying containers and objects, too.
|
||||
*
|
||||
*- HPCloud::Storage::ObjectStorage is where you will start.
|
||||
*- Container services are in HPCloud::Storage::ObjectStorage::Container
|
||||
*- OpenStack::Storage::ObjectStorage is where you will start.
|
||||
*- Container services are in OpenStack::Storage::ObjectStorage::Container
|
||||
*- There are two classes for objects:
|
||||
* - HPCloud::Storage::ObjectStorage::Object is for creating new objects.
|
||||
* - HPCloud::Storage::ObjectStorage::RemoteObject provides better network
|
||||
* - OpenStack::Storage::ObjectStorage::Object is for creating new objects.
|
||||
* - OpenStack::Storage::ObjectStorage::RemoteObject provides better network
|
||||
* performance when reading objects.
|
||||
*
|
||||
*/
|
||||
// Note that Doxygen assumes that dot (.) is the namespace separator in
|
||||
// package descriptions.
|
||||
/**
|
||||
* @package HPCloud
|
||||
* The HPCloud PHP library.
|
||||
* @package OpenStack
|
||||
* The OpenStack PHP-Client library.
|
||||
*/
|
||||
/**
|
||||
* @namespace HPCloud.Services
|
||||
* HPCloud classes providing access to various services.
|
||||
* @namespace OpenStack.Services
|
||||
* OpenStack classes providing access to various services.
|
||||
*
|
||||
* HPCloud offers a number of services, including Compute (Nova),
|
||||
* and IdentityServices.
|
||||
* OpenStack offers a number of services, including Compute (Nova),
|
||||
* and IdentityService.
|
||||
*
|
||||
* This package is reserved for classes that provide access to
|
||||
* services.
|
||||
*/
|
||||
/**
|
||||
* @package HPCloud.Storage
|
||||
* HPCloud classes for remote storage.
|
||||
* @package OpenStack.Storage
|
||||
* OpenStack classes for remote storage.
|
||||
*
|
||||
* Services for now and the future:
|
||||
*
|
||||
@ -241,13 +227,13 @@
|
||||
*
|
||||
*/
|
||||
/**
|
||||
* @package HPCloud.Storage.ObjectStorage
|
||||
* @package OpenStack.Storage.ObjectStorage
|
||||
* Classes specific to ObjectStorage.
|
||||
*
|
||||
* The main class is HPCloud::Storage::ObjectStorage.
|
||||
* The main class is OpenStack::Storage::ObjectStorage.
|
||||
*/
|
||||
/**
|
||||
* @package HPCloud.Transport
|
||||
* @package OpenStack.Transport
|
||||
* HTTP/REST/JSON classes.
|
||||
*
|
||||
* HTTP/HTTPS is the transport protocol for OpenStack's RESTful services.
|
||||
|
||||
@ -1,11 +1,11 @@
|
||||
# Using the HPCloud PHP API
|
||||
# Using the OpenStack PHP-CLient API
|
||||
|
||||
This tutorial explains how you can use the PHP API to connect to your HP
|
||||
Cloud services and interact programmatically.
|
||||
This tutorial explains how you can use the PHP API to connect to your OpenStack
|
||||
services and interact programmatically.
|
||||
|
||||
## Object Storage (Swift)
|
||||
|
||||
One of the services that HP Cloud offers is called "Object Storage".
|
||||
One of the services that OpenStack offers is called "Object Storage".
|
||||
This service provides a useful means of storing objects (usually files)
|
||||
on a service that you control, but that is available to other services
|
||||
in your cloud (and optionally is availably publically).
|
||||
@ -18,28 +18,26 @@ interact with the Object Storage service.
|
||||
There are two ways to authenticate to Object Storage:
|
||||
|
||||
- Legacy Swift authentication
|
||||
- Control Services authentication (Coming soon!)
|
||||
- Control Services authentication
|
||||
|
||||
For legacy swift authentication, you will need to use your Account ID
|
||||
and your secret Key, along with the URL to the Object Storage endpoint.
|
||||
If you are an existing HP Cloud customer, you can find all of this
|
||||
information on your console dashboard.
|
||||
For legacy swift authentication, you will need to use your Tenant ID, your username,
|
||||
and your password, along with the URL to the Object Storage endpoint.
|
||||
|
||||
### Using Stream Wrappers
|
||||
|
||||
There are two main methods for accessing HPCloud through this library.
|
||||
There are two main methods for accessing OpenStack through this library.
|
||||
The first is through PHP *stream wrappers*. In PHP, stream wrappers
|
||||
provide a facility with which you can access various data streams (like
|
||||
a webpage, the data in a ZIP file, or an HP Cloud object store) as if
|
||||
a webpage, the data in a ZIP file, or an OpenStack object store) as if
|
||||
they were local files on your file system.
|
||||
|
||||
Stream wrappers have a huge advantage for you: You can use the normal
|
||||
file system functions (`fread()`, `mkdir()`, `file_get_contents()`, etc)
|
||||
to access things not necessarily on your local filesystem. The HP Cloud
|
||||
to access things not necessarily on your local filesystem. The PHP-Client
|
||||
library integrates with this facility of PHP.
|
||||
|
||||
|
||||
### Using the HPCloud Classes
|
||||
### Using the PHP-Client Classes
|
||||
|
||||
While the stream wrappers are a fantastic way to accomplish many common
|
||||
tasks, sometimes you need a finer level of control, or you wish to use
|
||||
@ -54,14 +52,14 @@ data-access layer.
|
||||
|
||||
#### Main Classes
|
||||
|
||||
- \HPCloud\Bootstrap: Provides services for bootstrapping the library.
|
||||
- \OpenStack\Bootstrap: Provides services for bootstrapping the library.
|
||||
It's not necessary, but it can be helpful.
|
||||
- \HPCloud\ObjectStorage: The main interface to the OpenStack object
|
||||
- \OpenStack\ObjectStorage: The main interface to the OpenStack object
|
||||
storage.
|
||||
|
||||
## Slightly Irreverant Glossary
|
||||
|
||||
*Account ID:* You service provider (ahem, HPCloud) will provide you with
|
||||
*Tenant ID:* You service provider will provide you with
|
||||
an account ID and a secret key, along with a URL, that can be used to
|
||||
access the cloud APIs.
|
||||
|
||||
@ -69,9 +67,8 @@ access the cloud APIs.
|
||||
space with pseudo-containment logical units. Or, a directory. (see
|
||||
_Object Storage_)
|
||||
|
||||
*Object Storage:* A service provided by OpenStack (and implemented by
|
||||
HPCloud) that allows you to store entire files on the cloud. Files can
|
||||
be organized into _containers_, which are rough analogs to file system
|
||||
directories (or folders).
|
||||
*Object Storage:* A service provided by OpenStack that allows you to store
|
||||
entire files on the cloud. Files can be organized into _containers_, which are
|
||||
rough analogs to file system directories (or folders).
|
||||
|
||||
|
||||
|
||||
@ -1,21 +1,21 @@
|
||||
<?php
|
||||
require_once __DIR__ . '/../src/HPCloud/Bootstrap.php';
|
||||
require_once __DIR__ . '/../src/OpenStack/Bootstrap.php';
|
||||
|
||||
use \HPCloud\Bootstrap;
|
||||
use \HPCloud\Services\IdentityServices;
|
||||
use \HPCloud\Storage\ObjectStorage;
|
||||
use \HPCloud\Storage\ObjectStorage\Object;
|
||||
use \OpenStack\Bootstrap;
|
||||
use \OpenStack\Services\IdentityService;
|
||||
use \OpenStack\Storage\ObjectStorage;
|
||||
use \OpenStack\Storage\ObjectStorage\Object;
|
||||
|
||||
Bootstrap::useAutoloader();
|
||||
|
||||
// Load these from an ini file.
|
||||
$ini = parse_ini_file(getenv('HOME') . '/.hpcloud.ini');
|
||||
$ini = parse_ini_file(getenv('HOME') . '/.OpenStack.ini');
|
||||
$account = $ini['account'];
|
||||
$key = $ini['secret'];
|
||||
$tenantId = $ini['tenantId'];
|
||||
$endpoint = $ini['url'];
|
||||
|
||||
$idService = new IdentityServices($endpoint);
|
||||
$idService = new IdentityService($endpoint);
|
||||
$token = $idService->authenticateAsAccount($account, $key, $tenantId);
|
||||
|
||||
$catalog = $idService->serviceCatalog();
|
||||
|
||||
@ -1,12 +1,10 @@
|
||||
Tutorial: Using HPCloud-PHP {#oo-tutorial}
|
||||
Tutorial: Using OpenStack PHP-Client
|
||||
=================
|
||||
|
||||
HPCloud-PHP provides PHP language bindings for the HPCloud APIs. HPCloud
|
||||
is an OpenStack-based cloud service offering a wide (and ever-expanding)
|
||||
variety of services.
|
||||
PHP-Client provides PHP language bindings for the OpenStack APIs.
|
||||
|
||||
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
|
||||
tool that interacts with OpenStack's Object Storage. The emphasis in this
|
||||
article is on getting started and learning the concepts, not building a
|
||||
polished product.
|
||||
|
||||
@ -16,7 +14,7 @@ covered in [another tutorial](@ref streams-tutorial).
|
||||
|
||||
## Pre-flight Check
|
||||
|
||||
HPCloud-PHP has been developed to require PHP 5.3 or later. You are
|
||||
PHP-Client 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
|
||||
@ -30,7 +28,7 @@ You can check for both of these conditions by checking the output of
|
||||
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 PHP-Client library is composed of two parts:
|
||||
|
||||
1. The Object-Oriented part, which is the subject of this tutorial.
|
||||
2. The Stream Wrapper, which is the subject of another tutorial.
|
||||
@ -38,14 +36,12 @@ 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:
|
||||
|
||||
~~~{.php}
|
||||
<?php
|
||||
\HPCloud\Storage\ObjectStorage\RemoteObject
|
||||
?>
|
||||
~~~
|
||||
<?php
|
||||
\OpenStack\Storage\ObjectStorage\RemoteObject
|
||||
?>
|
||||
|
||||
The namespace above is read like this: "The RemoteObject class is part
|
||||
of the ObjectStorage package in the Storage package in the base HPCloud
|
||||
of the ObjectStorage package in the Storage package in the base OpenStack
|
||||
package." Those familiar with Java, Python, and other languages will
|
||||
recognize this way of talking (though the backslash is an unfortunate
|
||||
symbol choice).
|
||||
@ -53,9 +49,7 @@ 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:
|
||||
|
||||
~~~
|
||||
src/HPCloud/Storage/ObjectStorage/RemoteObject.php
|
||||
~~~
|
||||
src/OpenStack/Storage/ObjectStorage/RemoteObject.php
|
||||
|
||||
The pattern of matching namespace to file name should (we hope) make it
|
||||
easier for you to navigate our code.
|
||||
@ -67,51 +61,47 @@ 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
|
||||
`\OpenStack\Bootstrap` may appear as OpenStack::Bootstrap. The reason for
|
||||
this is [explained elsewhere](@ref styleguide).
|
||||
|
||||
## Step 1: Getting the Library
|
||||
|
||||
You can get the HPCloud-PHP library at the [HPCloud GitHub
|
||||
You can get the OpenStack PHP-CLient library at the [HPCloud GitHub
|
||||
Repository](https://github.com/hpcloud). The latest code is always
|
||||
available there.
|
||||
|
||||
The project also uses [Composer](http://packagist.org/), and this is the
|
||||
best method for adding HPCloud-PHP to your PHP project.
|
||||
best method for adding PHP-Client 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
|
||||
`Bootstrap.php` file:
|
||||
|
||||
~~~{.php}
|
||||
include 'HPCloud/Bootstrap.php';
|
||||
~~~
|
||||
include 'OpenStack/Bootstrap.php';
|
||||
|
||||
## Step 2: Bootstrap the Library
|
||||
|
||||
The first thing to do in your application is make sure the HPCloud
|
||||
The first thing to do in your application is make sure the OpenStack
|
||||
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
|
||||
part. If you are using an PSR-0 autoloader that knows of the OpenStack
|
||||
directory, that is enough for the system to initialize itself.
|
||||
|
||||
Sometimes, though, you will need to bootstrap HPCloud in your own code,
|
||||
Sometimes, though, you will need to bootstrap OpenStack in your own code,
|
||||
and this is done as follows:
|
||||
|
||||
~~~{.php}
|
||||
<?php
|
||||
require_once 'HPCloud/Bootstrap.php';
|
||||
<?php
|
||||
require_once 'OpenStack/Bootstrap.php';
|
||||
|
||||
use \HPCloud\Bootstrap;
|
||||
use \HPCloud\Services\IdentityServices;
|
||||
use \HPCloud\Storage\ObjectStorage;
|
||||
use \HPCloud\Storage\ObjectStorage\Object;
|
||||
use \OpenStack\Bootstrap;
|
||||
use \OpenStack\Services\IdentityService;
|
||||
use \OpenStack\Storage\ObjectStorage;
|
||||
use \OpenStack\Storage\ObjectStorage\Object;
|
||||
|
||||
\HPCloud\Bootstrap::useAutoloader();
|
||||
?>
|
||||
~~~
|
||||
\OpenStack\Bootstrap::useAutoloader();
|
||||
?>
|
||||
|
||||
The first line should be self-explanatory: We require the main
|
||||
`Bootstrap.php` file (which contains the `Bootstrap` class).
|
||||
@ -120,12 +110,12 @@ 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
|
||||
The last line initializes the built-in OpenStack autoloader. What does
|
||||
this mean? It means that this is the only `require` or `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
|
||||
There are some other fancy things that OpenStack::Bootstrap can do for
|
||||
you. Most notably, you can pass configuration parameters into it. But
|
||||
for the time being, we are good to go.
|
||||
|
||||
@ -134,29 +124,28 @@ Our library is boostrapped. Next up: Let's connect to our account.
|
||||
## Step 3: Connecting
|
||||
|
||||
Our programming goal, in this tutorial, is to interact with the Object
|
||||
Storage service on HP Cloud. (Object Storage is, for all intents and
|
||||
Storage service on OpenStack. (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:
|
||||
|
||||
- Account ID: The account number.
|
||||
- Secret key: The shared secret that, when paired with account number,
|
||||
authenticates the client.
|
||||
- Username: The username for an account.
|
||||
- Password: The password associated with the username.
|
||||
- Tenant ID: An identifier that maps an account to a set of services.
|
||||
(In theory at least, one account can have multiple tenant IDs, and one
|
||||
tenant ID can be linked to multiple accounts.)
|
||||
- Endpoint URL: The URL to the Identity Services endpoint at HPCloud.
|
||||
- Endpoint URL: The URL to the Identity Services endpoint for OpenStack.
|
||||
|
||||
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](https://console.hpcloud.com) and go to the `API Keys`
|
||||
into the console and go to the `API Keys`
|
||||
page. It's all there.
|
||||
|
||||
### Identity Services
|
||||
|
||||
The HPCloud is composed of numerous services. There's the Compute
|
||||
OpenStack is composed of numerous services. There's the Compute
|
||||
service, the Object Storage service... and so on.
|
||||
|
||||
Authenticating separately to each of these would be a collosal waste of
|
||||
@ -174,11 +163,11 @@ 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
|
||||
to an OpenStack 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
|
||||
The *service catalog* lists all of the OpenStack services that the present
|
||||
account can access.
|
||||
|
||||
### Authenticating
|
||||
@ -186,50 +175,48 @@ account can access.
|
||||
With that little bit of theory behind us, we can now go about
|
||||
authenticating.
|
||||
|
||||
~~~{.php}
|
||||
<?php
|
||||
$account = 'ADD ACCOUNT HERE';
|
||||
$key = 'ADD KEY HERE';
|
||||
$tenantId = 'ADD TENANT ID HERE';
|
||||
$endpoint = 'ADD ENDPOINT URL HERE';
|
||||
<?php
|
||||
$username = 'ADD USERNAME HERE';
|
||||
$password = 'ADD PASSWORD HERE';
|
||||
$tenantId = 'ADD TENANT ID HERE';
|
||||
$endpoint = 'ADD ENDPOINT URL HERE';
|
||||
|
||||
$idService = new \HPCloud\Services\IdentityServices($endpoint);
|
||||
$token = $idService->authenticateAsAccount($account, $key, $tenantId);
|
||||
?>
|
||||
~~~
|
||||
$idService = new \OpenStack\Services\IdentityService($endpoint);
|
||||
$token = $idService->authenticateAsUser($username, $password, $tenantId);
|
||||
?>
|
||||
|
||||
Assuming the variables above have been set to include valid data, this
|
||||
script can connect to HPCloud and authenticate.
|
||||
script can connect to OpenStack and authenticate.
|
||||
|
||||
When we construct a new HPCloud::Services::IdentityServices object, we must pass it the
|
||||
endpoint URL for HPCloud Identity Services. Typically, that URL will
|
||||
When we construct a new OpenStack::Services::IdentityService object, we must pass it the
|
||||
endpoint URL for OpenStack Identity Service. Typically, that URL will
|
||||
look something like this:
|
||||
|
||||
~~~
|
||||
https://region-a.geo-1.identity.hpcloudsvc.com:35357
|
||||
~~~
|
||||
|
||||
The `authenticateAsAccount()` method will authenticate to the
|
||||
The `authenticateAsUser()` method will authenticate to the
|
||||
Identity Services endpoint. For convenience, it returns the
|
||||
authorization token (`$token`), though we can also get the token from
|
||||
`$idService->token()`.
|
||||
|
||||
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.
|
||||
Note that the `IdentityService` object may throw various exceptions
|
||||
(all subclasses of OpenStack::Exception) during authentication. Failed
|
||||
authentication results in an OpenStack::Transport::AuthorizationException, while
|
||||
a network failure may result in an OpenStack::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
|
||||
At this point, we have what we need from Identity Service. It's time to
|
||||
look at Object Storage.
|
||||
|
||||
### IdentityServices in a Nutshell
|
||||
### IdentityService in a Nutshell
|
||||
|
||||
Instances of HPCloud::Services::IdentityServices are responsible for:
|
||||
Instances of OpenStack::Services::IdentityService are responsible for:
|
||||
|
||||
- Authentication
|
||||
- Accessing the service catalog
|
||||
@ -247,40 +234,38 @@ 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
|
||||
In the object model for the OpenStack PHP-Client library, a top-level object
|
||||
called OpenStack::Storage::ObjectStorage provides access to the Object
|
||||
Storage service. In this step, we will be working with that object.
|
||||
|
||||
### Getting an ObjectStorage Instance
|
||||
|
||||
Earlier, we created an `IdentityServices` instance called `$idService`.
|
||||
Earlier, we created an `IdentityService` 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
|
||||
configured to talk to our account's Object Storage instance in
|
||||
OpenStack. 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 `$token`
|
||||
variable.
|
||||
|
||||
Now we can get a new HPCloud::Storage::ObjectStorage instance:
|
||||
Now we can get a new OpenStack::Storage::ObjectStorage instance:
|
||||
|
||||
~~~{.php}
|
||||
<?php
|
||||
$catalog = $idService->serviceCatalog();
|
||||
<?php
|
||||
$catalog = $idService->serviceCatalog();
|
||||
|
||||
$store = ObjectStorage::newFromServiceCatalog($catalog, $token);
|
||||
$store = ObjectStorage::newFromServiceCatalog($catalog, $token);
|
||||
|
||||
// UPDATE: As of Beta 6, you can use newFromIdentity():
|
||||
// $store = ObjectStorage::newFromIdentity($idService);
|
||||
?>
|
||||
~~~
|
||||
// UPDATE: As of Beta 6, you can use newFromIdentity():
|
||||
// $store = ObjectStorage::newFromIdentity($idService);
|
||||
?>
|
||||
|
||||
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
|
||||
throughout the OpenStack PHP-Client library. Inspired by Objective-C constructors
|
||||
and the Factory design pattern, it makes it possible for a single class
|
||||
to have multiple constructors.
|
||||
|
||||
@ -290,12 +275,12 @@ 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
|
||||
talk to our OpenStack object storage service. Next, we can create a
|
||||
container.
|
||||
|
||||
### ObjectStorage in a Nutshell
|
||||
|
||||
Instances of HPCloud::Storage::ObjectStorage are responsbile for:
|
||||
Instances of OpenStack::Storage::ObjectStorage are responsbile for:
|
||||
|
||||
- Providing high-level information about the Object Storage service
|
||||
- Creating, deleting, loading, and listing Containers
|
||||
@ -309,22 +294,20 @@ 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
|
||||
OpenStack::Storage::ObjectStorage::Container class. And creating a
|
||||
container is done by a method on the `ObjectStorage` object that we
|
||||
created above:
|
||||
|
||||
~~~{.php}
|
||||
<?php
|
||||
$store->createContainer('Example');
|
||||
$container = $store->container('Example');
|
||||
?>
|
||||
~~~
|
||||
<?php
|
||||
$store->createContainer('Example');
|
||||
$container = $store->container('Example');
|
||||
?>
|
||||
|
||||
Recall that `$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
|
||||
Why is this two steps? The answer is that the OpenStack PHP-Client 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.
|
||||
@ -338,7 +321,7 @@ container. All of this information will be available on the `$container`
|
||||
instance.
|
||||
|
||||
Our `$container` instance is an instance of
|
||||
HPCloud::Storage::ObjectStorage::Container. This object can be used not
|
||||
OpenStack::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.
|
||||
|
||||
@ -348,7 +331,7 @@ 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:
|
||||
A OpenStack::Storage::ObjectStorage::Container instance is responsible for the following:
|
||||
|
||||
- Accessing information about the container
|
||||
- Creating, saving, deleting, and listing objects in the container
|
||||
@ -377,22 +360,20 @@ 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.
|
||||
|
||||
~~~{.php}
|
||||
<?php
|
||||
$name = 'hello.txt';
|
||||
$content = 'Hello World';
|
||||
$mime = 'text/plain';
|
||||
<?php
|
||||
$name = 'hello.txt';
|
||||
$content = 'Hello World';
|
||||
$mime = 'text/plain';
|
||||
|
||||
$localObject = new Object($name, $content, $mime);
|
||||
$container->save($localObject);
|
||||
?>
|
||||
~~~
|
||||
$localObject = new Object($name, $content, $mime);
|
||||
$container->save($localObject);
|
||||
?>
|
||||
|
||||
In the code above, we create `$localObject` with a `$name`, some
|
||||
`$content`, and a `$mime` type. Strictly speaking, only `$name` is
|
||||
required.
|
||||
|
||||
The HPCloud::Storage::ObjectStorage::Object class is used primarily to
|
||||
The OpenStack::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.
|
||||
@ -414,7 +395,7 @@ Next let's turn to loading objects from the remote object storage.
|
||||
|
||||
### The Object in a Nutshell
|
||||
|
||||
The HPCloud::Storage::ObjectStorage::Object instances are used for:
|
||||
The OpenStack::Storage::ObjectStorage::Object instances are used for:
|
||||
|
||||
- Creating a local object to be stored remotely
|
||||
|
||||
@ -431,19 +412,17 @@ the edgiest of edge cases, you would only create an instance 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:
|
||||
|
||||
~~~{.php}
|
||||
<?php
|
||||
$object = $container->object('hello.txt');
|
||||
<?php
|
||||
$object = $container->object('hello.txt');
|
||||
|
||||
printf("Name: %s \n", $object->name());
|
||||
printf("Size: %d \n", $object->contentLength());
|
||||
printf("Type: %s \n", $object->contentType());
|
||||
print $object->content() . PHP_EOL;
|
||||
?>
|
||||
~~~
|
||||
printf("Name: %s \n", $object->name());
|
||||
printf("Size: %d \n", $object->contentLength());
|
||||
printf("Type: %s \n", $object->contentType());
|
||||
print $object->content() . PHP_EOL;
|
||||
?>
|
||||
|
||||
The `$object` variable now references an instance of a
|
||||
HPCloud::Storage::ObjectStorage::RemoteObject that contains the entire
|
||||
OpenStack::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
|
||||
@ -474,16 +453,14 @@ 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:
|
||||
|
||||
~~~{.php}
|
||||
<?php
|
||||
$object = $container->proxyObject('hello.txt');
|
||||
<?php
|
||||
$object = $container->proxyObject('hello.txt');
|
||||
|
||||
printf("Name: %s \n", $object->name());
|
||||
printf("Size: %d \n", $object->contentLength());
|
||||
printf("Type: %s \n", $object->contentType());
|
||||
print $object->content() . PHP_EOL;
|
||||
?>
|
||||
~~~
|
||||
printf("Name: %s \n", $object->name());
|
||||
printf("Size: %d \n", $object->contentLength());
|
||||
printf("Type: %s \n", $object->contentType());
|
||||
print $object->content() . PHP_EOL;
|
||||
?>
|
||||
|
||||
Instead of using `object()`, we now use `proxyObject()`. This method
|
||||
immediately loads the core data about the remote object, but defers
|
||||
@ -495,7 +472,7 @@ called.
|
||||
|
||||
### The RemoteObject in a Nutshell
|
||||
|
||||
Instances of a HPCloud::Storage::ObjectStorage::RemoteObject offer the following features:
|
||||
Instances of a OpenStack::Storage::ObjectStorage::RemoteObject offer the following features:
|
||||
|
||||
- Access to an object stored on the remote object storage
|
||||
- A proxying mechanism for lazily loading objects
|
||||
@ -509,15 +486,15 @@ Instances of a HPCloud::Storage::ObjectStorage::RemoteObject offer the following
|
||||
## Summary
|
||||
|
||||
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
|
||||
OpenStack and works with object storage. Clearly, this only scratches the
|
||||
surface of what the OpenStack PHP-Client 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](https://github.com/hpcloud). You can also build a
|
||||
local copy by installing [doxygen](http://www.stack.nl/~dimitri/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
|
||||
OpenStack PHP-Client project. This will place the generated documents in
|
||||
`docs/api/html`.
|
||||
|
||||
\see oo-tutorial-code.php
|
||||
|
||||
@ -1,11 +1,11 @@
|
||||
<?php
|
||||
require_once __DIR__ . '/../src/HPCloud/Bootstrap.php';
|
||||
require_once __DIR__ . '/../src/OpenStack/Bootstrap.php';
|
||||
|
||||
use \HPCloud\Bootstrap;
|
||||
use \OpenStack\Bootstrap;
|
||||
Bootstrap::useAutoloader();
|
||||
Bootstrap::useStreamWrappers();
|
||||
|
||||
$ini = parse_ini_file(getenv('HOME') . '/.hpcloud.ini');
|
||||
$ini = parse_ini_file(getenv('HOME') . '/.OpenStack.ini');
|
||||
$settings = array(
|
||||
'account' => $ini['account'],
|
||||
'key' => $ini['secret'],
|
||||
|
||||
@ -1,98 +1,94 @@
|
||||
Tutorial: Using Stream Wrappers {#streams-tutorial}
|
||||
===============================
|
||||
|
||||
This is an introduction to the HPCloud-PHP library. While the library is
|
||||
This is an introduction to the OpenStack PHP-Client library. While the library is
|
||||
large and feature-rich, this tutorial focuses on the Stream Wrapper
|
||||
feature. (There is also a [tutorial about the object-oriented
|
||||
library](@ref 00-tutorial).)
|
||||
|
||||
## TL;DR
|
||||
|
||||
With a few lines of setup code, you can fetch objects from HP Cloud's
|
||||
With a few lines of setup code, you can fetch objects from OpenStack's
|
||||
object storage using built-in PHP functions like this:
|
||||
|
||||
~~~{.php}
|
||||
<?php
|
||||
// Create a new file and write it to the object store.
|
||||
$newfile = fopen('swift://Example/my_file.txt', 'w');
|
||||
fwrite($newfile, "Good Morning!");
|
||||
fclose($newfile);
|
||||
<?php
|
||||
// Create a new file and write it to the object store.
|
||||
$newfile = fopen('swift://Example/my_file.txt', 'w');
|
||||
fwrite($newfile, "Good Morning!");
|
||||
fclose($newfile);
|
||||
|
||||
// Check for an object:
|
||||
if (file_exists('swift://Example/my_file.txt')) {
|
||||
print "Found my_file.txt." . PHP_EOL;
|
||||
}
|
||||
// Check for an object:
|
||||
if (file_exists('swift://Example/my_file.txt')) {
|
||||
print "Found my_file.txt." . PHP_EOL;
|
||||
}
|
||||
|
||||
// Get an entire object at once:
|
||||
$file = file_get_contents('swift://Example/my_file.txt');
|
||||
print 'File: ' . $file . PHP_EOL;
|
||||
?>
|
||||
~~~
|
||||
// Get an entire object at once:
|
||||
$file = file_get_contents('swift://Example/my_file.txt');
|
||||
print 'File: ' . $file . PHP_EOL;
|
||||
?>
|
||||
|
||||
In fact, the vast majority of file and stream functions work with
|
||||
HPCloud's `swift://` URLs.
|
||||
OpenStack's `swift://` URLs.
|
||||
|
||||
The rest of this tutorial explains how they work.
|
||||
|
||||
## The Setup
|
||||
|
||||
The example above does not show the code necessary for initializing the
|
||||
HPCloud stream wrapper. In this section, we will look at the necessary
|
||||
OpenStack PHP-Client stream wrapper. In this section, we will look at the necessary
|
||||
setup code.
|
||||
|
||||
### Loading Classes
|
||||
|
||||
The HPCloud PHP library is structured following SPR-0 recommendations.
|
||||
The OpenStack PHP-Client library is structured following SPR-0 recommendations.
|
||||
Practically speaking, what this means is that applications that use an
|
||||
SPR-0 autoloader may be able to automatically load the HPCloud library.
|
||||
SPR-0 autoloader may be able to automatically load the OpenStack PHP-Client.
|
||||
|
||||
However, we'll assume that that is not the case. We'll assume that the
|
||||
library needs to be initialized manually.
|
||||
|
||||
What we will do is first load the HPCloud Bootstrap.php file, and then
|
||||
What we will do is first load the PHP-Client Bootstrap.php file, and then
|
||||
use the autoloader in that file to load the rest of the library:
|
||||
|
||||
~~~{.php}
|
||||
<?php
|
||||
require_once '/HPCloud/Bootstrap.php';
|
||||
<?php
|
||||
require_once '/OpenStack/Bootstrap.php';
|
||||
|
||||
use \HPCloud\Bootstrap;
|
||||
Bootstrap::useAutoloader();
|
||||
Bootstrap::useStreamWrappers();
|
||||
?>
|
||||
~~~
|
||||
use \OpenStack\Bootstrap;
|
||||
Bootstrap::useAutoloader();
|
||||
Bootstrap::useStreamWrappers();
|
||||
?>
|
||||
|
||||
The first thing the example above does is require the Bootstrap.php
|
||||
file, which contains code necessary for initializing the HPCloud
|
||||
library.
|
||||
file, which contains code necessary for initializing the OpenStack
|
||||
PHP-Client.
|
||||
|
||||
Next, we call two static methods on the HPCloud::Bootstrap object:
|
||||
Next, we call two static methods on the OpenStack::Bootstrap object:
|
||||
|
||||
- Bootstrap::useAutoLoader(): This tells HPCloud to load any other
|
||||
- Bootstrap::useAutoLoader(): This tells the PHP-Client to load any other
|
||||
classes on demand. Since we use this, we don't need any more `require`
|
||||
or `include` statements.
|
||||
- Bootstrap::useStreamWrappers(): This tells HPCloud to register its
|
||||
- Bootstrap::useStreamWrappers(): This tells OpenStack to register its
|
||||
stream wrapper classes.
|
||||
|
||||
In a nutshell, PHP allows libraries to map a particular URL pattern to a
|
||||
stream wrapper. HPCloud registers the `swift://` URL prefix. So any
|
||||
stream wrapper. PHP-Client registers the `swift://` URL prefix. So any
|
||||
request to a URL beginning with `swift://` will be proxied through the
|
||||
HPCloud library.
|
||||
OpenStack PHP-Client library.
|
||||
|
||||
## Setting Up Authentication
|
||||
|
||||
When working with remote HPCloud Object Storage, you must authenticate
|
||||
When working with remote OpenStack Object Storage, you must authenticate
|
||||
to the remote system. Authentication requires the following four pieces
|
||||
of information:
|
||||
|
||||
- account: Your account ID
|
||||
- key: Your account's secret key
|
||||
- tenantid: The tenant ID for the services you wish to use
|
||||
- endpoint: The endpoint URL for HPCloud's Identity Services. It usually
|
||||
- endpoint: The endpoint URL for OpenStack's Identity Service. It usually
|
||||
looks something like this: `https://region-a.geo-1.identity.hpcloudsvc.com:35357`
|
||||
|
||||
All four of these pieces of information can be found in the **API Keys**
|
||||
section of your [console](https://console.hpcloud.com) account.
|
||||
section of your console account.
|
||||
|
||||
(Note: You can use your username and password instead of account and
|
||||
key, but you still must supply the tenant ID. Instead of supplying
|
||||
@ -121,22 +117,16 @@ your needs.
|
||||
|
||||
That said, here's how we set up a global configuration:
|
||||
|
||||
~~~{.php}
|
||||
$settings = array(
|
||||
'account' => YOUR_ACCOUNT_NUMBER,
|
||||
'key' => YOUR_SECRET_KEY,
|
||||
'tenantid' => YOUR_TENANT_ID,
|
||||
'endpoint' => IDENTITY_SERVICES_URL,
|
||||
|
||||
// Instead of account/key you can use this:
|
||||
// 'username' => YOUR_USERNAME,
|
||||
// 'password' => YOUR_PASSWORD,
|
||||
);
|
||||
Bootstrap::setConfiguration($settings);
|
||||
~~~
|
||||
$settings = array(
|
||||
'username' => YOUR_USERNAME,
|
||||
'password' => YOUR_PASSWORD,
|
||||
'tenantid' => YOUR_TENANT_ID,
|
||||
'endpoint' => IDENTITY_SERVICES_URL,
|
||||
);
|
||||
Bootstrap::setConfiguration($settings);
|
||||
|
||||
Basically, what we do above is declare an associative array of
|
||||
configuration parameters and then tell HPCloud::Bootstrap to set these
|
||||
configuration parameters and then tell OpenStack::Bootstrap to set these
|
||||
as the default configuration.
|
||||
|
||||
Once the above is done, all of those PHP stream and file functions will
|
||||
@ -152,7 +142,7 @@ The URL above has three important parts, in the form
|
||||
`swift://CONTAINER/OBJECT_NAME`.
|
||||
|
||||
- *swift://*: This is the schema. This part of the URL tells PHP to pass
|
||||
the request to the HPCloud stream wrapper. (Swift, by the way, is the
|
||||
the request to the OpenStack stream wrapper. (Swift, by the way, is the
|
||||
[OpenStack name for object storage](http://openstack.org/projects/storage/).
|
||||
- *Example*: This is the *container name*. In Object Storage parlance, a
|
||||
container is a place to store documents. One account can have lots of
|
||||
@ -166,7 +156,7 @@ names. So `swift://Example/this/is/my/file.png' checks the container
|
||||
|
||||
(For power users, there are some fancy operations you can do to treat
|
||||
Swift filename parts as if they were directories. Check out
|
||||
HPCloud::Storage::ObjectStorage::Container.)
|
||||
OpenStack::Storage::ObjectStorage::Container.)
|
||||
|
||||
## Using Stream Contexts for Authentication
|
||||
|
||||
@ -190,30 +180,24 @@ tokens in a database and re-using them).
|
||||
|
||||
Here's how a stream context is used:
|
||||
|
||||
~~~{.php}
|
||||
<?php
|
||||
require_once __DIR__ . '/../src/HPCloud/Bootstrap.php';
|
||||
<?php
|
||||
require_once __DIR__ . '/../src/OpenStack/Bootstrap.php';
|
||||
|
||||
use \HPCloud\Bootstrap;
|
||||
Bootstrap::useAutoloader();
|
||||
Bootstrap::useStreamWrappers();
|
||||
use \OpenStack\Bootstrap;
|
||||
Bootstrap::useAutoloader();
|
||||
Bootstrap::useStreamWrappers();
|
||||
|
||||
$cxt = stream_context_create(array(
|
||||
'swift' => array(
|
||||
'account' => YOUR_ACCOUNT_NUMBER,
|
||||
'key' => YOUR_SECRET_KEY,
|
||||
'tenantid' => YOUR_TENANT_ID,
|
||||
'endpoint' => IDENTITY_SERVICES_URL,
|
||||
$cxt = stream_context_create(array(
|
||||
'swift' => array(
|
||||
'username' => YOUR_USERNAME,
|
||||
'password' => YOUR_PASSWORD,
|
||||
'tenantid' => YOUR_TENANT_ID,
|
||||
'endpoint' => IDENTITY_SERVICES_URL,
|
||||
),
|
||||
));
|
||||
|
||||
// Instead of account/key you can use this:
|
||||
// 'username' => YOUR_USERNAME,
|
||||
// 'password' => YOUR_PASSWORD,
|
||||
),
|
||||
));
|
||||
|
||||
print file_get_contents('swift://Example/my_file.txt', FALSE, $cxt);
|
||||
?>
|
||||
~~~
|
||||
print file_get_contents('swift://Example/my_file.txt', FALSE, $cxt);
|
||||
?>
|
||||
|
||||
The main difference is the creation of `$cxt` using PHP's
|
||||
`stream_context_create()`. To fully understand this, you may want to
|
||||
@ -245,15 +229,15 @@ usage of `swift://` with `swiftfs://`.
|
||||
## Summary
|
||||
|
||||
This tutorial is focused on using stream wrappers to interact with your
|
||||
HPCloud Object Storage service. We focused on configuring the
|
||||
OpenStack Object Storage service. We focused on configuring the
|
||||
environment for transparently using PHP functions like `fopen()` and
|
||||
`file_get_contents()` to work with objects in HPCloud's object storage.
|
||||
`file_get_contents()` to work with objects in OpenStack's object storage.
|
||||
|
||||
This is just one way of interoperating with the HPCloud library. For
|
||||
This is just one way of interoperating with the OpenStack PHP-Client library. For
|
||||
more detail-oriented work, you may find the Object Oriented facilities
|
||||
better suited. You can read [the OO tutorial](@ref oo-tutorial) to learn
|
||||
more about that.
|
||||
|
||||
Addidtionally, you may wish to learn more about the internals of the
|
||||
stream wrapper, the main class,
|
||||
HPCloud::Storage::ObjectStorage::StreamWrapper, is well-documented.
|
||||
OpenStack::Storage::ObjectStorage::StreamWrapper, is well-documented.
|
||||
|
||||
@ -21,9 +21,9 @@ SOFTWARE.
|
||||
============================================================================ */
|
||||
/**
|
||||
* @file
|
||||
* HP Cloud configuration.
|
||||
* OpenStacl PHP-Client configuration.
|
||||
*
|
||||
* This file contains the HP Cloud autoloader. It also automatically
|
||||
* This file contains the PHP-Client autoloader. It also automatically
|
||||
* register the OpenStack stream wrappers.
|
||||
*/
|
||||
|
||||
|
||||
@ -102,15 +102,11 @@ class ObjectStorage {
|
||||
* To use the legacy Object Storage authentication mechanism, you will
|
||||
* need the follwing pieces of information:
|
||||
*
|
||||
* - Account ID: Your account username or ID. For HP Cloud customers,
|
||||
* this is typically a long string of numbers and letters.
|
||||
* - Key: Your secret key. For HP Customers, this is a string of
|
||||
* random letters and numbers.
|
||||
* - Account ID: This will typically be a combination of your tenantId and
|
||||
* username.
|
||||
* - Key: Typically this will be your password.
|
||||
* - Endpoint URL: The URL given to you by your service provider.
|
||||
*
|
||||
* HP Cloud users can find all of this information on your Object
|
||||
* Storage account dashboard.
|
||||
*
|
||||
* @param string $account
|
||||
* Your account name.
|
||||
* @param string $key
|
||||
|
||||
@ -31,7 +31,7 @@ namespace OpenStack\Transport;
|
||||
*
|
||||
* When one of the transporters makes a request, it will
|
||||
* return one of these as a response. The response is simplified
|
||||
* to the needs of the HP Cloud services and isn't a
|
||||
* to the needs of the OpenStack services and isn't a
|
||||
* general purpose HTTP response object.
|
||||
*
|
||||
* The transport wraps three pieces of information:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user