Picasa Version 3.3, Now With Server-Side Caching

The Lightweight PHP Picasa API bug list is finally empty and that can only mean one thing, a shiny new version! Four months have passed since the last version and it's time for another iteration. Aside from one big new feature, this version largely fixes a series of small bugs. Here are the high points:

• Implemented Server-Side Caching (Issue 6)
• Fixed bug in Picasa.getImages() where keywords couldn't be searched when ordering the feed (Issue 15)
  
• Added "weblink" field to Accounts, Albums, and Images (Issue 17)
• Added Bounding Box search for images (Issue 18)
• Modified Exception classes to print a stack trace when thrown (Issue 19)

If these sound like additions you'd like to see in your code, download it now. In fact, you'll probably find a few extra goodies too insignificant to mention (or that were never documented). As always, it's all backwards-compatible with previous versions of the API. The Documentation has also been updated, so take a look. Here I'll go into the specifics of each addition.

Implemented Server-Side Caching

This had been a feature request for a long time and I always thought it would be too difficult to implement but I finally realized it could actually be very simple. The Picasa Data API that the PHP API is powered by just uses XML documents to transport information about a Picasa account. My API simply parses those documents and puts the information into PHP objects. The solution to implement caching was very obvious, I just store those XML documents on the server and check to see if they exist before asking Google for them. This was all very easy, in fact, and the difficult part was making sure it worked securley (ie; you probably don't want to cache Private feeds) and was user-friendly.

Before I dive in to the nitty-gritty, here's the good news about caching: it's all implemented for you in Picasa.php. As long as you're not creating other objects on your own, you shouldn't need to think about it. In case you do, I'll go a bit more into detail.

The cached documents are stored, by default, in your include path, in a directory called "picasa-api-cache". I store them in the include path to make sure PHP has access to them. If the directory doesn't exist, the API attempts to create it. If it succeeds, caching is enabled immediately. If it fails, Caching is turned off and you'll never hear about it again. To see if Caching is working, visit some of your pages that access an Account, Album, or Image, then go to the root of your include path and check for the directory "picasa-api-cache". If it's there, look inside and see if there are any files there. The files look like a URL with all the slashes and question marks replaced by dots. If the directory doesn't exist or its emtpy, caching is probably not working. The easiest way to troubleshoot it is to turn Logging on somewhere in your code, which is done with he following statement (you'll remember this from Version 3.2):

Picasa_Logger:getLogger()->setEnabled(true);

You should then see logging statements telling you what is wrong with Caching. The most likely causes are:

• PHP doesn't have access to create the "picasa-api-cache" directory. In this case you should create it yourself.
• PHP doesn't have write access inside the picasa-api-cache" directory. In this case you should change the permissions on the directory.

If one of these is not the problem and you can't figure it out yourself, feel free to email me. Again, if Caching is not working correctly, the worst thing that will happen is that your XML files will be requested from Picasa every time, which is not such a bad thing (in fact, it's exactly how the API has worked up until this release).

Just like the Logging class introduced in Version 3.2, the Cache class is created as a Singleton. So whenever you want to access the cache (which you may never need to do in your client code), you just call Picasa_Cache::getCache() and you'll have the Cache object. You can then call any of the public methods inside the Picasa_Cache class. For instance, you can disable caching, set the path that cached files are stored at, and set the amount of time before cached files expire in your client code (set to two hours by default). At the top of any PHP page that uses the API, you would call the setter for the field you want to modify. If you don't want to remember to do that in your code, you can go into the API and modify it directly. To do this, go to Picasa/Cache.php and update the static private members defined at the top of the class. The cache path is always created inside the include path so if you want to change that behavior, you'll need to update the constructor method inside Picasa_Cache, which is very easy to do.

The last thing to know about the Cache is the way it's implemented in Picasa.php. Basically all the methods that get Accounts, Albums, Images, ImageCollections, Tags, Comments, or Authors all implement caching. For methods retrieving a list based on a set of criteria, the feed is always cached when the visibility is set to "public" (which is the default). This so you don't go in as an authorized user, cache a bunch of private albums and then when an unauthorized user requests the albums, they get the private ones as well as public ones. For the Picasa methods where visibility is not a search criteria, the feed is always cached when the Picasa::$auth member is null. If you don't authenticate the instance of Picasa you're using, it will always be null. If you have authenticated it and you want to utilize the cache in such a call you can either call Picasa::clearAuthentication() or if you'd rather not throw away your auth, just instantiate a new Picasa instance, don't authenticate it, and use that to fetch the album.

Fixed Bug in Keyword Search

Due to a bug in the Picasa data api itself that doesn't allow ordering of images in an image search by upload date, I was forced to introduce a work-around in version 3.2. When I implemented this, I did it a little sloppily and killed keyword searching (thanks to Google Code user Gaitan for finding this and reporting it). This was an oversight and a quick fix. Search away!

Added Weblink Field

Special thanks to Picasa API user Ruben Woudsma who noticed the usefulness of having a link back to the Picasaweb page for an image. In fact, he wrote the code to add it himself and sent it to me. Open Source programming at it's best. Anyway, you can now call getWeblink() on a Picasa_Account, Picasa_Album, or Picasa_Image object and it will give you the URL to that object on the Picasaweb site.

Added Bounding-Box Search

This was relatively straight-forward, Google introduced searching by Geo-coordinates and I just added it to the API. You can pass 4 bounding-box coordinates to Picasa->getImages() in the $boundingBox parameter and you will get back images within those coordinates. It should be a single string with four coordinates seperated by commas.

Modified Exception Class

I have to plead ignorance on this one, I had no idea PHP was so self-aware! Now when an exception is thrown, a stack trace is printed. This was simple to do using PHP's built-in getTrace() method.

That about sums up the bulk of the changes for this round. If you find something not working, kindly enter a bug and it will get addressed. If you have a question, first take a look at the documentation and if you're still stumped, email me. And if you don't yet have the latest version, go get it!