The paws library has been designed to provide a natural PHP interface to Amazon Web Services (AWS), including SimpleDB and S3. One may ask, "Why yet another AWS PHP Library?" There are several reasons paws is being developed:
So, paws has a couple of major goals:
I've done my best to make this reference guide for pawsSDB and pawsS3 as self-contained and complete as possible. Even so, it does not provide much tutuorial information about the organization of SimpleDB or S3. You will need to have a basic understanding of the concepts and structure of AWS. So, for example, this documentation assumes you know what is meant by Simple DB domain names, items, and attributes, and the tree/spreadsheet cross of its data representation. We tried to be consistent with the terminology used by AWS.
For the most part, the paws classes rely on underlying classes already released for AWS SimpleDB and S3. The underlying SimpleDB class is the one provided directly from AWS: Amazon_SimpleDB. The underlying S3 class was built by and is listed on AWS as a Standalone S3 PHP class. It is always possible that the paws classes may be evenutally implemented directly, or switch to another underlying library. However, the paws API will remain the same.
Currently, paws only supports SimpleDB and S3. In the future, support for other AWS packages such as EC2 may be added.
While AWS SimpleDB is a database, it is significantly different than traditional relational databases. Specifically, specific operations are provided for accessing data, while there is a special query expression language for searching an AWS database. Even so, mySQL served somewhat as a model for designing the pawsSDB class - we hope the good parts.
We hope this class is easy to use. It seems difficult to imagine making it much easier to use. The entire class consists of just a dozen or so functions. Data from SimpleDB is handled using PHP associative arrays. This just seemed the most natrual way to handle the data - associative arrays are at the core of PHP. Each item in the database has an itemName and a set of attributes. Each attribute has a name and one more values for each name. Thus, it just seems logical to use the attribute name as the index to an associative array, and to store the value or values as the value of the array element. Because PHP is so typeless, it is easy to store either a single value or an array of values as the "value" of the attribute name. All this is explained in the page forputAttributes.
The paws access to AWS SimpleDB is built into a single class: pawsSDB. This class, in turn, uses the
Amazon_SimpleDB
library. This is good in that it is a reasonable assumption that Amazon will keep that library up to date. This is bad in that there is not total agreement that the Amazon_SimpleDB library uses the fastest protocol to talk to AWS. Whatever. If that is really an issue, it should be possible to rewrite the low level interface to SimpleDB and keep the pawsSDB class interface to the programmer unchanged. For now, it seemed best to make the initial implementation based on Amazon_SimpleDB.
To use pawsSDB, you edit the configuration file with your AWS id and secret password, perhaps editing some path stuff. You then include the pawsSDB php class file. You instantiate an instance of the class (or more instances if you need them), and use the functions to access SimpleDB.
There are a few interesting extras included with the class file. First, there is this complete documentation. Second, there is a demo web application that lets you test the pawsSDB class, and actually play with SimpleDB by creating domains, items, etc. There is a PHP terminal based utility that will download and dump your entire SimpleDB database, and one to restore it.
The pawsSDB.php file is designed to be installed in a directory called /paws that is at the same level as the /Amazon directory of the Amazon_SimpleDB library distribution. For example, on my development platform, I have a directory off my root called /libs. Under /libs is the ./libs/Amazon directory with Amazon_SimpleDB, and the ./libs/paws directory with the pawsSDB class.
I've moved the configuration file for Amazon_SimpleDB to the /paws directory - pawsConfig.php. This file has the defines for your AWS id and password. It also has an include path definition, and the definition for the magic __autoload function. These were pretty much copied/dictated by the needs of
Amazon_SimpleDB. As always, you should be able to trivially move around where things are found, especially since pawsSDB is all in one file.
The pawsS3 class is somewhat simpler than the pawsSDB class. In addition to the basic access provided to S3 servers, pawsS3 provides some utility functions helpful for accessing images and other web data directly from generated HTML, and for POST uploading data to S3.
The installation basics and details for the pawsS3 class is essentially the same as for pawsSDB. All classes are included in the distribution, including updated versions of the underlying classes required. Follow the instructions for pawsSDB, and pawsS3 will be available by including pawsS3.php in your source files.
This library was developed by Bruce Wampler. I'm a digital pioneer, and been in this business for over 30 years. I've had a couple of successful software companies, taught computer science at the University of New Mexico, wrote a book about Java programming, and even been on the local school board. Now I'm working a new web project.
I thought it might be interesting to hear about the motivation behing pawsSDB (and evenutally pawsEC2 and pawsS3). First, the development platform. I prefer Ubuntu Linux running in a virtual machine on a Mac Pro box. I use VMWare Fusion to run Ubuntu. This lets me test everything on one machine - Linux, Mac OS X, and all the Windows platforms (XP, XP Pro, Vista Home, Vista Ultimate, etc.). I have versions of every modern browser available. And I use Komodo to do the actual development. I find using a Mac browser connected to the Apache server on the Ubuntu VM works really well to simulate the real world. I've been programming for over 30 years, and I've never found a development platform that come close to this. The Mac is really the ultimate programmer's productivity tool. Your editor/IDE is a personal choice. I played around with some, and found for me that Komodo works best, especialy across platforms.
I'm working on a new project that I need to design to handle thousands or millions of users. And do it for little up front capital costs. Thus, AWS. What an option.
So, the first thing I needed was SimpleDB. And I found the PHP interface very hard to think about, yet alone use. So I dediced to do what I always do - write a great library to work the way I think. So, pawsSDB. My next step will be data storage, so pawsS3 shouldn't be too far behind. And finally, I suppose I'll need EC2, and pawsEC2.
I'm also doing some blogging about this as I go, so you might want to read along at brucewampler.wordpress.com.
Thanks for trying paws!
Bruce Wampler, June 2, 2008