The CloudFusion functions that I have told you about thus far all
return simple data structures—arrays of strings. However, the functions
that I will use later in this article return a more complex data structure
called a ResponseCore. S3 returns its results in
the form of an XML document; CloudFusion parses the XML using PHP’s
SimpleXML package and includes the parsed objects in the response where
they can be referenced by name.^[1]

The following code calls S3 to list the first 1,000 objects in the
bucket BOOK_BUCKET, and then calls PHP’s handy
print_r function to display the resulting object
tree:

#!/usr/bin/php
<?php
error_reporting(E_ALL);
require_once('cloudfusion.class.php');
require_once('include/book.inc.php');
$s3 = new AmazonS3();
$res = $s3->list_objects(BOOK_BUCKET);
print_r($res);
exit(0);
?>

The resulting output is far too long to display in its entirety (465
lines for my buckets). Let’s look at some excerpts instead. Here’s the
first part:

$php list_bucket_objects_raw.php
ResponseCore Object
[header] => Array
(
  [x-amz-id-2] => Ya7yAuUClv7HgR6+JJpz0sYDM1m4/Zy+d0Rmk5cSAu+qV+v+6
➥9gLSHlytlD77wAn
  [x-amz-request-id] => 14AA13F3F0B76032
  [date] => Thu, 28 May 2009 06:51:26 GMT
  [content-type] => application/xml
  [transfer-encoding] => chunked
  [connection] => close
  [server] => AmazonS3
  [_info] => Array
  (
    [url] => https://sitepoint-aws-cloud-book.s3.amazonaws.com/
    [content_type] => application/xml
    ⋮

The first line indicates that the data is of type
ResponseCore. Further on, we find some standard PHP
arrays. If we need to, we can access the data like this:

$res->header['transfer-encoding']
$res->header['_info']['url']

$res is an object and header
is one of the object’s instance variables, so it’s accessed using the
-> operator. The header instance
variable is a PHP array, so its members are accessed using the array
syntax.

In the second line the _info member of
header is itself an array, so a second set of brackets
are used to access the url value inside.

A little bit further down in the output, we find the
following:

[body] => SimpleXMLElement Object
(
  [Name] => sitepoint-aws-cloud-book
  ⋮

The body instance variable is of type
SimpleXMLElement. It starts out with a
Name instance variable, which can be accessed as
$res->body->Name.

Even further down we finally find what we came here for—the list of
objects in the bucket:

[Contents] => Array
(
  [0] => SimpleXMLElement Object
  (
    [Key] => images/2008_shiller_housing_projection.jpg
    [LastModified] => 2009-05-22T23:44:58.000Z
    [ETag] => "e2d335683226059e7cd6e450795f3485"
    [Size] => 236535
    [Owner] => SimpleXMLElement Object
    (
      [ID] => 7769a42be4e57a034eeb322aa8450b3536b6ca56037c06ef19b1e1
➥eabfeaab9c
      [DisplayName] => jeffbarr
    )
    [StorageClass] => STANDARD
  )
  ⋮

You can see that body contains an instance
variable called Contents, which is another array
containing all the files in the bucket. Each file in the bucket is
represented by a SimpleXMLElement object; each has
Key, ETag, Size,
Owner, and StorageClass members,
accessed like this:

$res->body->Contents[0]->Key
$res->body->Contents[0]->ETag
$res->body->Contents[0]->Size
$res->body->Contents[0]->Owner->ID
$res->body->Contents[0]->Owner->DisplayName
$res->body->Contents[0]->StorageClass

Of course, you’re free to use intermediate variables to make this
code shorter or more efficient.

You may be wondering where the object names
(Contents, Key,
Size, and so forth) come from. The
list_objects method makes an HTTP
GET request to S3 to fetch a list of the first 1,000
objects in the bucket. The request returns an XML document, and
CloudFusion parses and returns it as the body object.
The object names are taken directly from the XML tags in the
document.

If we were to modify the previous script to print out some of these
values, it may look like this example:

#!/usr/bin/php
<?php
error_reporting(E_ALL);
require_once('cloudfusion.class.php');
require_once('include/book.inc.php');
$s3 = new AmazonS3();
$res = $s3->list_objects(BOOK_BUCKET);
print("Bucket Url: " . $res->header['_info']['url'] . "\n");
print("Bucket Name: " . $res->body->Name   . "\n");
print("First Key:  " . $res->body->Contents[0]->Key . "\n");
print("Second Key: " . $res->body->Contents[1]->Key . "\n");
exit(0);
?>

In the above example we output the bucket’s URL and name, followed
by the keys of the first two items in the bucket.

We have now come to the end of the detour. I hope that the ride was
scenic, yet educational. Next, we will use this newfound knowledge to
create a very handy utility function.

Before we can write a script that outputs a list of all the
objects in a bucket within a web page, we first have to write a rather
complex function. We’ll add this function to our
book.inc.php file and call it
getBucketObjects:

function getBucketObjects($s3, $bucket, $prefix = '')
{
  $objects = array();
  $next = '';
  do
  {
    $res = $s3->list_objects($bucket,
        array('marker' => urlencode($next),
            'prefix' => $prefix)
      );
    if (!$res->isOK())
    {
      return null;
    }
    $contents = $res->body->Contents;
    foreach ($contents as $object)
    {
      $objects[] = $object;
    }
    $isTruncated = $res->body->IsTruncated == 'true';
    if ($isTruncated)
    {
      $next = $objects[count($objects) - 1]->Key;
    }
  }
  while ($isTruncated);
  return $objects;
}

This function is more complex than anything you’ve seen so far, but
there’s no need to worry. Earlier on I told you that one “list bucket”
request to S3 will return at most 1,000 keys, regardless of how many keys
are in the bucket. Our getBucketObjects function
simply calls list_objects again and again until
S3 says that there are no more objects to return:

Put it together and this function fetches all the objects in the
bucket, puts them all into one array, and returns the array.

With this function in hand, creating a list of the objects in the
bucket becomes easy. Here’s all we have to do:

<?php
error_reporting(E_ALL);
require_once('cloudfusion.class.php');
require_once('include/book.inc.php');
$bucket = IsSet($_GET['bucket']) ? $_GET['bucket'] : BOOK_BUCKET;
$s3 = new AmazonS3();
$objects = getBucketObjects($s3, $bucket);
$fileList = array();
foreach ($objects as $object)
{
  $key = $object->Key;
  $url = $s3->get_object_url($bucket, $key);
  $fileList[] = array('url' => $url, 'name' => $key,
                    'size' => number_format((int)$object->Size));
}
$output_title = "Chapter 3 Sample - List of S3 Objects in Bucket' .
    '${bucket}'";
$output_message = "A simple HTML table displaying of all the' .
    ' objects in the '${bucket}' bucket.";
include 'include/list_bucket_objects.html.php';
exit(0);
?>

This code generates a web page and can accept an optional
bucket argument in the URL query string. Let’s rip this
one apart and see how it works:

Here’s what the list_bucket_objects.html.php
HTML template looks like:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title><?php echo $output_title ?></title>
</head>
<body>
  <h1><?php echo $output_title ?></h1>
  <p><?php echo $output_message ?></p>
  <table>
    <thead>
      <tr><th>File</th><th>Size</th></tr>
    </thead>
    <tbody>
    <?php foreach($fileList as $file): ?>
      <tr>
          <td><a href="<?php echo $file['url'] ?>">
              <?php echo $file['name'] ?></a>
          </td>
          <td><?php echo $file['size'] ?></td>
      </tr>
    <?php endforeach ?>
    </tbody>
  </table>
</body>
</html>

The template iterates over the $fileList array
and creates a table row for each file, placing a link to the file in the
first column and the file size in the second column.

Figure 1, “Listing objects in an S3 bucket” shows what it looks like (I
had already uploaded some files to my bucket).

Figure 1. Listing objects in an S3 bucket

You may have spotted the fact that we now have all the parts needed
to make a simple S3 file browser. I’ll leave that as a challenge to you.
With just a little bit of work you should be able to connect
list_buckets_page.php and
list_bucket_objects_page.php.