Amazon Web Services SDK for PHP 2 Documentation

As I mentioned in an earlier post, the new SDK for PHP 2 for Amazon Web Services (AWS) is kind of lacking in documentation. Since the PHP SDK 2 for AWS is pretty new (November, 2012), hopefully this lack of documentation will be addressed. However, here are some notes which will help me and hopefully others.

At least for now, I'll focus on EC2 examples and code as that's what I need at the moment.

The PHP SDK 2 code base seems to be commented fairly well. So the "generated" API documentation seems to be fairly complete. What I call the "generated, pretty" API documenation is available here :

Again, when looking at generated API documentation for the "AWS PHP SDK", make sure you're looking at the newer "SDK 2" rather than "SDK 1".

Although the generated API docs look nice and have useful things like coloring, bolding and the like, I found it easier to delve into the raw source to try to figure out how to use the SDK.

However, many of the class methods (ex. describeKeyPairs()) seem to be implemented as "magic methods". This is all well and good, but as someone more familiar with "rigid" API documentation standards of earlier versions of Java, the in-code documentation of the AWS PHP SDK 2 looks a bit odd.

For example, take a look at the file Ec2Client.php. I was expecting to see a number of EC2-class-specific methods implemented in that class file. However, what I saw is a large number (100+) of "method-comments" like the following and only about one line of real code.

* @method Model describeKeyPairs(array $args = array()) {@command Ec2 DescribeKeyPairs}

I guess this is the "new and improved" way to do things in a modern dynamic language like PHP, but it is a bit different for me.

Anyway, I think I found the "raw" implementation / documentation in a "src/AWS/EC2/Resources" directory in the Git repository. In there is a large file named "ec2-2012-12-01.php".

This is a very large (15,000-line) file that does one thing - return an array. The array returned has five primary components :

- regions
- ex. 'us-east-1'
- operations
- ex. 'DescribeKeyPairs'
- models
- ex. 'DescribeKeyPairsResult'
- iterators
- ex. 'DescribeKeyPairs'
- waiters
- ex. 'InstanceRunning'

In practice, the "pretty" API documentation is easier to use than the raw "Resource" file, but it's useful to know how the source of the API documentation.