Jaap's Amazon PHP Scripts

Explanation about the scripts

20100331: This text is very outdated!

You don't need to read this before implementing and using the scripts.

Introduction

  1. The scripts send a request to the Amazon Web Service (AWS) system in the form of an URL with arguments specifying which products to look for. The first time this is a default search, which is books by or about Machiavelli.
  2. AWS returns a search result in the form of an XML file.
  3. This XML file is either interpreted using simple regular expressions (amazonli.php.txt), my own build-in XML interpreter (amazonh3.php.txt) or the SimpleXML functions (amazonsi.php.txt), by default build-in into PHP5, returning an array (in $A) with all the data.
  4. The next phase is printing the array with links to the next and the previous page.
  5. In the non-light scripts, the user also gets a form with which he can change the search parameters and the language to show the result page in.
  6. When the user submits the form it will call the same script again with new parameters in the argument part which will make the script send a new request to Amazon and so on.

The XML interpreter

The light script uses regular expressions and tricks to interpret the XML code. It can't interpret the heavy AWS feed and it may break should Amazon change the lay-out of it's XML output. The script is however extremely small (about 225 lines of which 50% comment lines), so it's a nice way to study how AWS works. I wouldn't use this for a production environment, unless you want to add the rest of the code yourself.
The standard heavy script uses my own recursive XML interpreter which seems to work very well. The code is very densely written, but is very hard to understand (even for myself after a while), but you don't need to understand it. The interpreter returns a tree of (associative) arrays with all of the data in the XML file in it.
The new experimental version of the script uses the SimpleXML interpreter which is by default build into the PHP5 interpreter. Most providers will still offer PHP4 for a while (it's now 2004-09) and this interpreter returns all of the data in the XML file in a tree of objects, which I find difficult to understand.

Search form

Since 2003-06-25 the heavy script shows search boxes to the user and will handle that search request itself. You can disable this option by setting the flag $f_user_search to false or you can remove the two parts of code that enable this feature.

Get rich flag

The $f_rich flag is now only used when there was a search for books. In earlier days you had to rewrite the link to Amazon to get a commission of 15% instead of 5% on discounted books. This is not very important anymore because the 15% has become 7.5%.

ref=nosim

The $f_rich flag also causes the link to be rewritten such that your visitors land on the actual page of the product instead of a book mainly offering similar products (in an attempt by Amazon to lower your commissions). Please check out the Amazon documentation when you're interested in these matters.

Multi server support

The script tries to support all AWS servers, see the file data.php.txt. Please note that in order to earn commission from all of these servers you need to apply as an associate to all of them separately and that the emails you'll get will be in the local language. I found this be a waste of time.

Multi language support

After thinking about the issue for a while I came to the conclusion (unlike Amazon) that not only there are servers in different countries, but that people using data from these servers not automatically prefer the language of that server. That is why since 2003-07 the page can be shown in several languages, of which only support in Dutch, English, Esperanto and German is quite complete. (Volunteers are wanted to provide translations into other languages!). Please note that in order to change the page language your user has to file another request first, which may be confusing. Some of the local server terms that Amazon uses are also in the local language complicating the matter even further. I'll probably split the form in a language change form and an Amazon search form, which should solve most of the problems. For the time being this solution should work well enough. The whole language translation mechanism is located in the file language.php.txt.

Caching

The pages as returned by AWS are being cached using a simple caching mechanism. This will only be useful when exactly the same request would be send to Amazon again (within an hour) so when people go to the next and previous result pages and back. Please not that you have to enable this caching mechanism by creating a subdirectory called cache and making sure the script can access, read and write it (RWX in Unix). Please note that Amazon doesn't allow you to keep some of the data in cache longer than an hour.

Search types

Not all of the search types work correctly yet. A lot of them need different ways of handling them. I have added the handling of the blended and ASIN searches lately however. Let me know when you want me to handle other searches too, or want to help.

AWS error messages

It turns out that the error messages are often in a different branch of the XML tree for different search types, which makes it hard to detect if there was an error and which error it was, using a general XML interpreter. I have asked Amazon to put the error message (also) on constant branch in each case. In the mean time my own XML interpreter uses a global variable to gather error messages wherever in the tree they are.
I have set up a simple database of error messages and the new script will offer users the chance to enter the errors they encounter in the database.

AWS data in separate file

I have tried to isolate most of the AWS specific data in the file data.php.txt. Of course this can't be done completely because the print function also has to know what kind of fields AWS returns.

Comments in the script

I have tried to put a lot of comments in the script to explain not only what the functions do, but also the AWS background why it's done the way it's done and often also alternatives. You may also find commented-out statements that I used to debug the script and may be useful to you too.

Additional tips and remarks

If you want the script to print the XML code that it got from AWS add '&show_xml=1' to the URL of the script (after there is already argument data at the end of it, otherwise add '?show_xml=1'). If you want the script to print out the complete array or object that it has transformed the XML into, add '&show_array=1' in a similar way. If you want to see the URL that the script has send to Amazon to get the XML file, add '&show_url=1'.

PHP versions etc.

The standard script should work under PHP4, but probably also under PHP5. It only needs local directory and file access and it must be able to access files elsewhere on the WWW, so it must be able to open sockets to other sites. The script was written for register_globals off, which is the default. But my host has it enabled which is very friendly, but it means that the script isn't tested as strictly as it should have been. I have this setting on 'off' on my local PC's, but I generally don't test these scripts locally.

AWS 4

This script uses version 3 of AWS and not (yet) version 4 which is now (2004-09-22) in the beta testing stage. I have tried to write the script in a very orthogonal way, so it shouldn't be very hard to adapt it to AWS 4 someday, but Amazon has no plans to stop supporting AWS 3 soon yet.
Jaap van Ganswijk <ganswijk@chipdir.nl>