stackforge/openstack-sdk-php
Code Issues Proposed changes

Updated oo-tutorial to use Doxygen MD processing.

Browse Source
This commit is contained in:
Matt Butcher 2012-03-15 11:07:54 -05:00
parent 83cc91295a
commit 926d2f18d4
1 changed files with 55 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
doc/oo-tutorial.md
View File

@ -1,4 +1,4 @@
Using HPCloud-PHP {#oo-tutorial} Tutorial: Using HPCloud-PHP {#oo-tutorial}
================= =================
HPCloud-PHP provides PHP language bindings for the HPCloud APIs. HPCloud HPCloud-PHP provides PHP language bindings for the HPCloud APIs. HPCloud
@ -38,9 +38,9 @@ The HPCloud library is composed of two parts:
The object-oriented library makes ample use of PHP namespaces. If you've The object-oriented library makes ample use of PHP namespaces. If you've
never seen these before, they look like this: never seen these before, they look like this:
```php ~~~{.php}
\HPCloud\Storage\ObjectStorage\RemoteObject \HPCloud\Storage\ObjectStorage\RemoteObject
``` ~~~
The namespace above is read like this: "The RemoteObject class is part 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 HPCloud
@ -51,9 +51,9 @@ symbol choice).
For our library, we followed the recommendation of SPR-0, which means For our library, we followed the recommendation of SPR-0, which means
that the class above can be found in the file at: that the class above can be found in the file at:
``` ~~~
src/HPCloud/Storage/ObjectStorage/RemoteObject.php src/HPCloud/Storage/ObjectStorage/RemoteObject.php
``` ~~~
The pattern of matching namespace to file name should (we hope) make it The pattern of matching namespace to file name should (we hope) make it
easier for you to navigate our code. easier for you to navigate our code.
@ -63,6 +63,9 @@ look at [the PHP documentation](http://us3.php.net/manual/en/language.namespaces
or you may just prefer to keep on reading and learn by example. We don't or you may just prefer to keep on reading and learn by example. We don't
do anything really fancy with namespaces. do anything really fancy with namespaces.
**In this document, we sometimes replace the backslash (\) with double
colons (`::`) so that links are automatically generated.**
## Step 1: Getting the Library ## Step 1: Getting the Library
You can get the HPCloud-PHP library at the [HPCloud GitHub You can get the HPCloud-PHP library at the [HPCloud GitHub
@ -76,9 +79,9 @@ For our example, we will assume that the library is accessible in the
default include path, so the following line will include the default include path, so the following line will include the
`Bootstrap.php` file: `Bootstrap.php` file:
```php ~~~{.php}
include 'HPCloud/Bootstrap.php'; include 'HPCloud/Bootstrap.php';
``` ~~~
## Step 2: Bootstrap the Library ## Step 2: Bootstrap the Library
@ -93,23 +96,32 @@ 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 HPCloud in your own code,
and this is done as follows: and this is done as follows:
```php ~~~{.php}
<?php <?php
require_once 'HPCloud/Bootstrap.php'; require_once 'HPCloud/Bootstrap.php';
use \HPCloud\Bootstrap;
use \HPCloud\Services\IdentityServices;
use \HPCloud\Storage\ObjectStorage;
use \HPCloud\Storage\ObjectStorage\Object;
\HPCloud\Bootstrap::useAutoloader(); \HPCloud\Bootstrap::useAutoloader();
?> ?>
``` ~~~
The first line should be self-explanatory: We require the main The first line should be self-explanatory: We require the main
`Bootstrap.php` file (which contains the `Bootstrap` class). `Bootstrap.php` file (which contains the `Bootstrap` class).
The second line initializes the built-in HPCloud autoloader. What does 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 `require` or `include` 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 statement you need in your code. The library does the rest of the
including for you, on demand, in a performance-sensitive way. 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 HPCloud::Bootstrap can do for
you. Most notably, you can pass configuration parameters into it. But you. Most notably, you can pass configuration parameters into it. But
for the time being, we are good to go. for the time being, we are good to go.
@ -170,7 +182,7 @@ account can access.
With that little bit of theory behind us, we can now go about With that little bit of theory behind us, we can now go about
authenticating. authenticating.
```php ~~~{.php}
<?php <?php
$account = 'ADD ACCOUNT HERE'; $account = 'ADD ACCOUNT HERE';
$key = 'ADD KEY HERE'; $key = 'ADD KEY HERE';
@ -180,18 +192,18 @@ $endpoint = 'ADD ENDPOINT URL HERE';
$idService = new \HPCloud\Services\IdentityServices($endpoint); $idService = new \HPCloud\Services\IdentityServices($endpoint);
$token = $idService->authenticateAsAccount($account, $key, $tenantId); $token = $idService->authenticateAsAccount($account, $key, $tenantId);
?> ?>
``` ~~~
Assuming the variables above have been set to include valid data, this Assuming the variables above have been set to include valid data, this
script can connect to HPCloud and authenticate. script can connect to HPCloud and authenticate.
When we construct a new `IdentityServices` object, we must pass it the When we construct a new HPCloud::Services::IdentityServices object, we must pass it the
endpoint URL for HPCloud Identity Services. Typically, that URL will endpoint URL for HPCloud Identity Services. Typically, that URL will
look something like this: look something like this:
``` ~~~
https://region-a.geo-1.identity.hpcloudsvc.com:35357 https://region-a.geo-1.identity.hpcloudsvc.com:35357
``` ~~~
The `authenticateAsAccount()` method will authenticate to the The `authenticateAsAccount()` method will authenticate to the
Identity Services endpoint. For convenience, it returns the Identity Services endpoint. For convenience, it returns the
@ -199,9 +211,9 @@ authorization token (`$token`), though we can also get the token from
`$idService->token()`. `$idService->token()`.
Note that the `IdentityServices` object may throw various exceptions Note that the `IdentityServices` object may throw various exceptions
(all subclasses of `\HPCloud\Exception`) during authentication. Failed (all subclasses of HPCloud::Exception) during authentication. Failed
authentication results in an `\HPCloud\AuthorizationException`, while authentication results in an HPCloud::Transport::AuthorizationException, while
a network failure may result in an `\HPCloud\ServerException`. a network failure may result in an HPCloud::Transport::ServerException.
Earlier, we talked about the service catalog. Once we've authenticated, Earlier, we talked about the service catalog. Once we've authenticated,
we can get the service catalog from `$idService->serviceCatalog()`. It we can get the service catalog from `$idService->serviceCatalog()`. It
@ -213,7 +225,7 @@ look at Object Storage.
### IdentityServices in a Nushell ### IdentityServices in a Nushell
Instances of `IdentityServices` are responsible for: Instances of HPCloud::Services::IdentityServices are responsible for:
- Authentication - Authentication
- Accessing the service catalog - Accessing the service catalog
@ -232,7 +244,7 @@ Your object storage can have any number of containers, and each
container can have any number of objects. container can have any number of objects.
In the object model for the HPCloud PHP library, a top-level object In the object model for the HPCloud PHP library, a top-level object
called `HPCloud\Storage\ObjectStorage` provides access to the Object called HPCloud::Storage::ObjectStorage provides access to the Object
Storage service. In this step, we will be working with that object. Storage service. In this step, we will be working with that object.
### Getting an ObjectStorage Instance ### Getting an ObjectStorage Instance
@ -246,15 +258,15 @@ shows the Object Storage endpoint that we have already authenticated to
Identity Services. Earlier, we captured that value in the `$token` Identity Services. Earlier, we captured that value in the `$token`
variable. variable.
Now we can get a new `\HPCloud\Storage\ObjectStorage` instance: Now we can get a new HPCloud::Storage::ObjectStorage instance:
```php ~~~{.php}
<?php <?php
$catalog = $idService->serviceCatalog(); $catalog = $idService->serviceCatalog();
$store = ObjectStorage::newFromServiceCatalog($catalog, $token); $store = ObjectStorage::newFromServiceCatalog($catalog, $token);
?> ?>
``` ~~~
First we get the service catalog (`$catalog`), and then we use the First we get the service catalog (`$catalog`), and then we use the
`ObjectStorage::newFromServiceCatalog()` static method to create the new `ObjectStorage::newFromServiceCatalog()` static method to create the new
@ -276,12 +288,12 @@ container.
### ObjectStorage in a Nutshell ### ObjectStorage in a Nutshell
Instances of `ObjectStorage` are responsbile for: Instances of HPCloud::Storage::ObjectStorage are responsbile for:
- Providing high-level information about the Object Storage service - Providing high-level information about the Object Storage service
- Creating, deleting, loading, and listing Containers - Creating, deleting, loading, and listing Containers
- Modifying Container ACLs - Modifying Container ACLs
- Attaching a CDN service object to a Container (advanced) - Attaching a HPCloud::Storage::CDN service object to a Container (advanced)
## Step 5: Adding a Container ## Step 5: Adding a Container
@ -291,16 +303,16 @@ numerous containers (and each container can have different access
controls -- a topic we won't get into here). controls -- a topic we won't get into here).
Containers are represented in the library by the Containers are represented in the library by the
`\HPCloud\Storage\ObjectStorage\Container` class. And creating a HPCloud::Storage::ObjectStorage::Container class. And creating a
container is done by a method on the `ObjectStorage` object that we container is done by a method on the `ObjectStorage` object that we
created above: created above:
```php ~~~{.php}
<?php <?php
$store->createContainer('Example'); $store->createContainer('Example');
$container = $store->container('Example'); $container = $store->container('Example');
?> ?>
``` ~~~
Recall that `$store` is the name of our `ObjectStorage` instance. In the Recall that `$store` is the name of our `ObjectStorage` instance. In the
first of the two lines above, we create a new containe named `Example`. first of the two lines above, we create a new containe named `Example`.
@ -320,7 +332,7 @@ container. All of this information will be available on the `$container`
instance. instance.
Our `$container` instance is an instance of Our `$container` instance is an instance of
`\HPCloud\Storage\ObjectStorage\Container`. This object can be used not HPCloud::Storage::ObjectStorage::Container. This object can be used not
only to find out about a container, but also to get information about only to find out about a container, but also to get information about
the objects in that container. the objects in that container.
@ -330,7 +342,7 @@ Now that we have a `Container`, we can add an object.
(Yes, we realize the irony of that title.) (Yes, we realize the irony of that title.)
A Container instance is responsible for the following: A HPCloud::Storage::ObjectStorage::Container instance is responsible for the following:
- Accessing information about the container - Accessing information about the container
- Creating, saving, deleting, and listing objects in the container - Creating, saving, deleting, and listing objects in the container
@ -360,7 +372,7 @@ featched 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 opposite: We will create a local object, and then save it to the remote
storage. Later, we will fetch the remote object. storage. Later, we will fetch the remote object.
```php ~~~{.php}
<?php <?php
$name = 'hello.txt'; $name = 'hello.txt';
$content = 'Hello World'; $content = 'Hello World';
@ -369,13 +381,13 @@ $mime = 'text/plain';
$localObject = new Object($name, $content, $mime); $localObject = new Object($name, $content, $mime);
$container->save($localObject); $container->save($localObject);
?> ?>
``` ~~~
In the code above, we create `$localObject` with a `$name`, some In the code above, we create `$localObject` with a `$name`, some
`$content`, and a `$mime` type. Strictly speaking, only `$name` is `$content`, and a `$mime` type. Strictly speaking, only `$name` is
required. required.
The `\HPCloud\Storage\ObjectStorage\Object` class is used primarily to The HPCloud::Storage::ObjectStorage::Object class is used primarily to
describe a locally created object. Once we have our new `Object`, we can describe a locally created object. Once we have our new `Object`, we can
save it remotely using the `save()` method on our `$container` object. save it remotely using the `save()` method on our `$container` object.
This will push the object to the remote object storage service. This will push the object to the remote object storage service.
@ -397,7 +409,7 @@ Next let's turn to loading objects from the remote object storage.
### The Object in a Nutshell ### The Object in a Nutshell
The `\HPCloud\Storage\ObjectStorage\Object` instances are used for: The HPCloud::Storage::ObjectStorage::Object instances are used for:
- Creating a local object to be stored remotely - Creating a local object to be stored remotely
@ -414,7 +426,7 @@ the edgiest of edge cases, you would only create an instance of
Containers not only provide the methods for saving objects, but also for Containers not only provide the methods for saving objects, but also for
loading objects. Thus, we can fetch the object that we just created: loading objects. Thus, we can fetch the object that we just created:
```php ~~~{.php}
<?php <?php
$object = $container->object('hello.txt'); $object = $container->object('hello.txt');
@ -423,10 +435,10 @@ printf("Size: %d \n", $object->contentLength());
printf("Type: %s \n", $object->contentType()); printf("Type: %s \n", $object->contentType());
print $object->content() . PHP_EOL; print $object->content() . PHP_EOL;
?> ?>
``` ~~~
The `$object` variable now references an instance of a The `$object` variable now references an instance of a
`\HPCloud\Storage\ObjectStorage\RemoteObject` that contains the entire HPCloud::Storage::ObjectStorage::RemoteObject that contains the entire
object. `RemoteObject` represents an object that was loaded from the object. `RemoteObject` represents an object that was loaded from the
remote server. Along with providing the features of the `Object` class remote server. Along with providing the features of the `Object` class
we saw earlier, it also provides numerous optimizations for working over we saw earlier, it also provides numerous optimizations for working over
@ -457,7 +469,7 @@ 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 To fetch an object this way, we can just swap out one line in the
example above: example above:
```php ~~~{.php}
<?php <?php
$object = $container->proxyObject('hello.txt'); $object = $container->proxyObject('hello.txt');
@ -466,7 +478,7 @@ printf("Size: %d \n", $object->contentLength());
printf("Type: %s \n", $object->contentType()); printf("Type: %s \n", $object->contentType());
print $object->content() . PHP_EOL; print $object->content() . PHP_EOL;
?> ?>
``` ~~~
Instead of using `object()`, we now use `proxyObject()`. This method Instead of using `object()`, we now use `proxyObject()`. This method
immediately loads the core data about the remote object, but defers immediately loads the core data about the remote object, but defers
@ -478,7 +490,7 @@ called.
### The RemoteObject in a Nutshell ### The RemoteObject in a Nutshell
Instances of a `RemoteObject` offer the following features: Instances of a HPCloud::Storage::ObjectStorage::RemoteObject offer the following features:
- Access to an object stored on the remote object storage - Access to an object stored on the remote object storage
- A proxying mechanism for lazily loading objects - A proxying mechanism for lazily loading objects
@ -503,3 +515,5 @@ 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 (if you haven't already) and running `make docs` in the root of the
HPCloud PHP project. This will place the generated documents in HPCloud PHP project. This will place the generated documents in
`docs/api/html`. `docs/api/html`.
\see oo-tutorial-code.php