Gold Plated Blog Posts

Whatev.

• Topics:
• Picasa
• India
• Bumper Stickers
• Travel

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!

Now Available, Picasa API Version 3.2

It's been a while since the last update to my Lightweight PHP Picasa API but the project is alive and well. It's been a busy year, what with getting married and all, but I've finally got enough additions and fixes to the previous version that it deserves a new version number. Click here to download the latest version and read below to find out what's new and exciting about it.

Thanks to everyone who has contributed to the bug fix and feature request list. I've managed to address every issue on the list except one enhancement, issue 6. Here's a rundown of the important updates:

• Improved thumbnail access with the Picasa_Thumbnail class
• Added Previous and Next link to Picasa_Image class
• Added logging with Picasa_Logger class
• Added Copy Album and Copy Image utility
  

For a full list of what has changed, take a look at the bug fix and feature list. The Documentation is all up to date but I'll go into further detail on the ones I mentioned.

Updated Thumbnail Access

Up until this point, there have been two ways to access thumbnails of your images, either through getSmallThumb(), getMediumThumb() and getLargeThumb(), or through getThumbUrlMap() and getThumbHeightMap(). The first only allowed access to three thumbnail sizes at a time and the other was just plain clunky and awkward. I originally thought giving thumbnails their own class was overkill because there's really only three fields, but after working with the two current methods I decided a Thumbnail class is necessary. The original methods will still always be supported.

Whatever thumbnails you request of an image will be attached to the Picasa_Image object in the form of an array of Picasa_Thumbnail classes. Get the array by calling Picasa_Image.getThumbnails(). Once you have the array, you can access the height, width, and URL of any of the thumbnails through the getter methods. Keep in mind that even if you only request one thumbnail, you'll still get an array back from getThumbnails() and if you don't request any thumbnails, the default is to get three thumbnails.

Added Previous and Next Links

There wasn't a pretty way to do this because no information about the current query that the image came from is included in the image's XML. However, to make client code cleaner, I've added a $next and $previous var to the Image class. When getNext() or getPrevious() is called on an Image and the image doesn't already have a previous or next link, it will load both the previous and next image by loading all images in the album and cycling through them. Your code will be cleaner at least.

Added A Logging Mechanism

When someone emails me with a problem or question, I often ask them to go into the API to find out what URL is being used or what XML is being returned, etc. This can be intimidating. Hopefully from now on it will be less intimidating with the addition of the Picasa_Logger class. It's a very rudimentary logging mechanism but it will suffice for most everyone's needs.

To enable logging, just call Picasa_Logger.setEnabled(true) anywhere in your client code. By default, there is a lot of information in the API that is logged, so you can also call Picasa_Logger.setEnabled(false) if you want to disable logging later on in your script. I've implemented a Singleton pattern to make logging as simple as possible. If you'd like to log something in your client code, just write this line:

Picasa_Logger::getLogger()->logIfEnabled("This is my statement.");

This will print "This is my statement." to the screen. Unfortunately there are not different levels of logging, it's just On or Off, so as soon as you turn it on you get everything printed. Also unfortunately, you can't log to a file, only to the screen, so logging should only be turned on while you're debugging. In the future I hope to update the class to improve both of these aspects, but I didn't have the energy to do it in this version.

Copy Image and Copy Album Helper Methods

Not sure who will find this useful but you can now easily copy an image or an entire album from one account to another. You just have to have write access for the account you're copying to. The functionality comes in the Picasa class itself with the methods copyImage() and copyAlbum(). When you copy an image, all aspects of the image are copied except the comments. When you copy an album, all aspects of the album are copied, including the images! One thing to keep in mind if you do copy an album is that you have to pass in exactly the album you want to copy. You can get this by calling Picasa.getAlbumById(), but when you get the Album object from Picasa.getAlbumsByUsername(), the individual images are not included in the album objects for performance reasons. If you use this method, you'll need to call getImages() on any album you plan to copy because the images are added to the object when the getter is called.

I hope everyone finds this newest version useful, I think there are some welcomed additions. If you find any problems please feel free to add an issue. If you just want to comment on it, leave a comment here or email me. I've definitely lost some enthusiasm after spending so much time on Version 3.0 but I will post an update to this version when I find bugs with 3.2. I will also have a larger update that will include things like the upgrades I mentioned above and support for newer Picasa features like bounding box, but an update like that is a ways off. In the meantime, download the newest version here.

Picasa API Update

I've been pretty lax in getting an update to the Picasa API available for download. I've got a bit more going on than usual, and everyone can probably expect this level of commitment through the NBA Playoffs :) However I did finally manage to get back in and write some code. The outcome is Version 3.1 of the Picasa API, which you can download here. All the other download links on the site are up to date as well. This update fixes the following problem:

• No thumbnail size option in Picasa::getImageById() (Issue 2)
• Updated documentation for the Picasa_Author class (Undocumented)
• Fixed Picasa::getContactsByUsername(), which did not previously support authenticated feeds (Undocumented)
  

Getting back into the API code, I've had a few good ideas for enhancements, now I just have to force myself to implement them. I'm still getting good feedback and please continue to send in your comments. Unfortunately I haven't been able to post any more code samples but I've been answering specific questions by email as they come in so if you have questions, let me know.

Building Your Own Picasa Gallery

Since the release of version 3 of my Picasa API I've received some feedback from users that it would be helpful to have some sample code for those who want to do the basics: host their own gallery. I can relate with this, since it's the reason I built the API in the first place. Sure, you can do a lot of other cool stuff with the API, like uploading and managing photos, but certainly the typical adopter is just going to want their own Picasa pictures viewable from their personal homepage. So here is a quick rundown of how to do a basic gallery using the Lightweight PHP Picasa API, version 3.0.

As you might already know, my gallery consists of three types of pages, which I will refer to as an account page (seen here), an album page (for instance, here), and an image page (for instance, over here). It's pretty self explanatory, the account page lists all the albums, the album page lists all the photos in an album, the image page shows a larger version of the selected image. For each page type, you'll need some kind of information that you can store in a constant or get from GET/POST data. I'll go over each page type and list source code along with what information is required.

Account Page
For the account page, the only thing you'll need is the username. I recommend storing the username in a constant variable somewhere where all your code can access. This is so that if your username changes, or you want to give your code to someone else, you only have to change the username in one place. I store mine in a variable called "Cam_Util_PictureUtil::$USERNAME". However, for the sake of readability, I'll just refer to it in the following code as "$username". Here's the code for the account page, which just outputs each album's icon with a link to the album page. I use a URL structure similar to what my site uses, but modified to be closer to the typical setup. And obviously you can change the HTML to suit your needs:

$pic = new Picasa();
$account = $pic->getAlbumsByUsername($username);
$albums = $account->getAlbums();
foreach ($albums as $album) {
  print('<a   href="http://www.your_web_site.com/album.php?
  albumid='.$album->getIdnum().'">
  <img src="'.$album->getIcon().'" />');
  print('<div>'.$album->getTitle().'</div>');
}

Album Page
For the album page, you'll not only need the username, but you'll also need the album id. If you use the URL structure used in the previous example, you should be able to get the album id from the $_GET superglobal. I'll include how to do that in the code sample. So the album page just prints each image in the album with a link to the Image Page and the album title displayed below:

$albumid = $_GET["albumid"];
$pic = new Picasa();
$album = $pic->getAlbumById($username, $albumid);
$images = $album->getImages();
foreach ($images as $image) {
 print('<a href="http://www.your_web_site.com/image.php?
     albumid='.$albumid.'&imageid='.$image->getIdnum().'">
     <img src="'.$image->getMediumThumb().'"/>');
 print('<div>'.$image->getTitle().'</div>');
}

Image Page
Lastly for the image page, as you might have guessed, you'll need the username, album id, and image id. Again, using the above example, you get the image id from the $_GET superglobal. The image page prints the image, the image title, and the description of the image:

$albumid = $_GET["albumid"];
$imageid = $_GET["imageid"];
$pic = new Picasa();
$image = $pic->getImageById($username,$albumid, $imageid);
print ('<img src="$image->getLargeThumb().'" />');
print('<div>'.$image->getTitle());
print('<div>'.$image->getDescription().'</div></div>');

Unfortunately the current implementation of Picasa::getImageById() doesn't support any image sizes other than the defaults (which are pretty small). This was an oversight on my part because there was a workaround that made it not necessary. Unfortunately, due to a change in Google's API, the workaround no longer actually works. I've emailed the Picasa development mailing list to find out if there is another workaround that will work now, but I've also entered an enhancement request in my project's Google Code page. As soon as I fulfill that request, I'll post a quick tutorial on how to get larger sized images. It should be less than a week for that to happen.

Hopefully this tutorial has been helpful. Thanks to everyone who has given me feedback on the API, so far I've only heard good things. If something's not quite working right or it seems there's something wrong with the tutorial here, please let me know. And check back in the next week, I should have the fix for getting larger image sizes available for download, and I'll include a bit of code on displaying and posting comments for your images.

Lightweight PHP Picasa API Version 3.0

After weeks and weeks of toiling away at my desk in my free time, I've finally put the finishing touches on Version 3.0 of my Lightweight PHP Picasa API. I think the extra time has not been wasted, as this version is about a thousand times more robust and feature-rich than versions 1 and 2, as well as being a lot easier to use. For easy access, here are the important links:

Download the API source code

View the Documentation

View the bug and feature request list

Here I'll list the major features, and then go into greater detail on each one. Features include:

• Automatic query building through the Picasa class
• Pass in the parameters for your request and the member functions will build and send the query for you.
  
• Robust error handling through the Picasa_Exception class
• 8 different Exception classes that can be caught individually, all of which extend Picasa_Exception to allow any level of granularity your situation requires.
  
• Easy-to-use implementation of authorizations through the Picasa class
  
• Supports Client Login or AuthSub
• Supports persistent authorizations using browser cookies
• Added previously unsupported operations
• Suports not only fetching feeds, but also posting and deleting images, albums, comments, and tags, as well as updating images and albums.
  
• Include access to public and private albums.
• Added several fields to existing classes
• Added support for Exif data, GML coordinates, among others
  
• Comprehensive documentation using PHPDoc
• View the Javadoc style manual here.
  
• 100% backwards compatible with versions 1 and 2
• It's still "lightweight"
• No special requirements, just PHP 5
  
• Less than a third the size of the Zend framework

Automatic query building through the Picasa class
The Picasa class is certainly the biggest addition to the new version. It's really the only object that your client code will ever have to instantiate. It handles both authorization as well as data requests and manipulations (posting and updating images, etc). The nice part about how it handles data requests is that you'll literally never have to formulate a query string again. Pretty much any type of feed that can be requested from Picasa is supported through just a few different methods in this class. Just instantiate a Picasa object and then call the method you're looking for. For instance, to get all albums for user "goldplateddiapers" (that's me), use the following code:

$pic = new Picasa();
$albums = $pic->getAlbumsByUsername("goldplateddiapers");

Now $albums will hold a Picasa_Account object that has an array of all my albums. To see exactly what is in a Picasa_Album, you can look at the manual, or you can just print the object. I've added very handy __toString() methods for all the objects. So add this line and see what you get:

print $albums;

If you're viewing this in Firefox (which you should be!), view the page source to get a prettier display. The output should be a nicely formatted printout of every field in the object. Each one of those fields has a getter method so that you can access the data you see.

Of course, oftentimes your request will not be as simple as getting all images from one user. So each of the "get" functions in the Picasa class take a plethora of parameters to suit your needs. For instance, take a look at the definition for Picasa::getImages():

public function getImages($username=null, $maxResults=null,
      $startIndex=null, $keywords=null, $tags=null, 
      $visibility="public", $thumbsize=null, $imgmax=null);

As you can see, none of these parameters are required. Which ones you should supply depend on what you're looking for. To find the first 250 images in Picasa tagged "lolcats", do the following:

$pic = new Picasa();
$images = $pic->getImages(null, 250, null, null, "lolcats");

Now $images will be a Picasa_ImageCollection object with an array of up to 250 of your favorite lols. The same format follows for any methods in the API starting with "get". And of course, all of the parameters for each method are fully described in the documentation.

One thing to be careful of is that all combinations are not supported by Picasa. For instance, calling just Picasa::getImages() with no parameters, Picasa itself will probably yield an error, which will be thrown as a Picasa_Exception with the error message retrieveable through Picasa_Exception::getMessage(). See the next section for more information on exception handling. I've left it up to the client code to send acceptable requests; the API will only throw an exception if Picasa itself responds with an error, the API doesn't catch invalid combinations of parameters and thus they're not documented here. You'll have to play around with different parameter combinations or check Picasa's Developer Guide.

Robust error handling through the Picasa_Exception class
The previous versions of the API didn't do much in the way of error handling, and this aspect is probably the second biggest improvement since then. There is one main exception class, called Picasa_Exception, that all exceptions thrown from the API will be at least subclassed from. It's not an abstract class, so oftentimes an instance of Picasa_Exception itself will be thrown, but a more specific subclass will be thrown when appropriate. Take a look at the subclasses in the documentation or the source code, they're all listed in the Picasa_Exception class.

The Picasa_Exception class extends PHP's Exception class and adds a few nice fields to have. The first is Picasa_Exception::$url, which will contain the offending URL if the exception resulted in a bad request to Picasa. If the exception wasn't thrown as a result of a bad request, this field will be null. The other field that can be useful is Picasa_Exception::$response, which holds the complete response that the exception was thrown as a result of, again only if the exception is thrown because of a bad request.

To give you some background on how the API knows it should throw an exception when it's given a bad request (skip this paragraph if you don't care), basically the method that is used for executing requests (Picasa::do_request()) checks for a response of 200 or 201. If that's not found, it passes the response header to a method (Picasa::getExceptionFromInvalidPost()) that determines which kind of exception to throw. It saves the error message given by Picasa as the result of Exception->getMessage(). However, sometimes the body of the response, even if it was not a 200 or 201 response code, can be useful. For example, if a client is trying to authenticate using Client Login and Picasa requests a CAPTCHA challenge, the response code is 403, but fields are set in the body identifying the URL to the CAPTCHA challenge and the CAPTCHA's token value. The API uses the Picasa_Exception::getResponse() method to get the returned response, determine that it is a CAPTCHA challenge, and parse out the required fields.

The only other exception class in the API that adds any fields to the base Exception class is Picasa_Exception_CaptchaRequiredException. This (as you might have guessed) is thrown when a CAPTCHA challenge is requested by Picasa upon attempting to gain authorization. If you're unfamiliar with this operation, Picasa will ocassionally require a user attempting to login using Client Login to type in letters that appear in a supplied image in order to guarantee that the user is a real person. To login after a CAPTCHA is requested, you do exactly what you did to log in the first time, this time passing in the user's CAPTCHA answer and a token supplied by Picasa (see the next section for how the API deals with logins and CAPTCHAs). The Picasa_Exception_CaptchaRequiredException contains the method Picasa_Exception_CaptchaRequiredException::getCaptchaUrl() for getting the URL to the image to display, the method Picasa_Exception_CaptchaRequiredException::getCaptchaToken() for getting the token to pass along with the re-attempt at authorization, and the methods Picasa_Exception_CaptchaRequiredException::getUsername() and Picasa_Exception_CaptchaRequiredException::getPassword() for getting the user's username and password that they originally used when attempting to sign in.

As an example of how to use the Picasa_Exception classes effectively, here is an example of client code attempting to log in (see the next section for details about how to use the authorization functionality, but I think you can infer what the code is generally doing). Let's assume I've just requested the user's username and password in a form, using the POST method:

// Get the username and password from the POST superglobal
$user = $_POST['username'];
$password = $_POST['password'];

$pic = new Picasa();
try{
    $pic->authorizeWithClientLogin($user, $password);
} catch (Picasa_Exception_CaptchaRequiredException $ce) {
    print "Please enter the letters you see in the image: ";
    print '<img src="'.$ce->getCaptchaUrl().'" />';

   /* Put code for generating a form with an input field, setting $ce->getCaptchaToken(),
    * $ce->getUsername(), and $cd->getPassword() as hidden fields here
    */
} catch (Picasa_Exception_InvalidUsernameOrPasswordException $ie) {
    print "The username or password you have entered is invalid.";

    /* Put code for handling re-logins here
    */
} catch (Picasa_Exception $e) {
    print "Your attempt to login has failed: ".$e->getMessage();

    /* Put code for handling relogins here
    */
}

Easy-to-use implementation of authorizations through the Picasa class
Previous implementations of the Lightweight PHP Picasa API did not support authorizations in any way. This suited my needs personally, but left a lot of people out of luck or on their own to throw something together. With the addition of the Picasa class, though, comes a suite of methods and fields for gaining and keeping authorizations. The first thing you need to know about is the difference between Client Login and AuthSub. Client Login allows you to enter a user's username and password, while AuthSub requires your client to redirect the user to a Google-hosted secure page to enter their username and password. The Picasa class supports both.

To authorize a user using Client Login:

1. Get their username and password
2. Call Picasa::authorizeWithClientLogin(), passing in their username and password.

At this point, if the authorization was successful, you have an "authenticated" Picasa object. Now, using this Picasa object, you can do operations that the current user is authorized to do, such as accessing their private albums, posting photos and albums to their account, etc. If the authorization was unsuccessful, a Picasa_Exception is thrown. See the previous section for instructions on how to handle such exceptions.

To authorize a user using AuthSub:

1. Redirect the user to the Google login page using Picasa::redirectToLoginPage()
2. On the page supplied in the $next parameter or Picasa::redirectToLoginPage(), call Picasa::authorizeWithAuthSub().

These steps automate a few things that you could also do manually, depending on what your intentions are and what your server configuration gives the API access to. First, if you want to redirect the user manually, you can call Picasa::getUrlToLoginPage() just to get the URL that you should send the user to, and then redirect them using your client code however you want. Second, if the API doesn't have access to the $_GET superglobal (which the token required for Picasa::authorizeWithAuthSub() is in), you can get the "token" parameter out of the URL however you normally would and manually pass it as the first parameter in Picasa::authorizeWithAuthSub(). If it's not passed in, or null is passed instead, the method will look in the $_GET array for the token and if it's not there, throw a Picasa_Exception_FailedAuthorizationException.

A neat feature that is built into the API is persistent login through the use of cookies. Cookies are used because there's no server-side caching mechanism supplied with the API. So by default, if you authorize a Picasa object, it will store the authorization token and the type of authorization used (AuthSub or Client Login) in the users browser cookies. Tokens don't expire for quite a while, so this allows the user to login once and remain logged in as long as you like. You can use the method Picasa::authorizeFromCookie() and it will automatically look in the user's cookies for an authorization token and authorize the object if it finds one. If it doesn't, false is returned and your client code can prompt the user to login again. So here is a snippet for logging in using AuthSub:

$pic = new Picasa();
if ($pic->authorizeFromCookie() === false) {
    Picasa::redirectToLoginPage("http://yourdomain.com/samplePage.php");
}
//Perform authorized requests here

On the other hand, if you don't want the API to automatically save the token to the user's cookie and you want to save it yourself in a more secure way, you can pass false as the $saveAuthorizationToCookie parameter of either Picasa::authorizeWithAuthSub() or Picasa::authorizeWithClientLogin(). The token is returned from both methods when a successful authorization is established. To then authenticate a Picasa instance, you can either pass the token along with the type of authorization (represented by the public static members Picasa::$AUTH_TYPE_AUTH_SUB and Picasa::$AUTH_TYPE_CLIENT_LOGIN) into Picasa's constructor when you instantiate it, or call Picasa::setAuthorizationInfo(), also passing in the token and type.

It should also be noted here that Picasa actually returns a "single use token", which is only good for one request, when a user attempts to login through AuthSub. However, the API automatically converts the single use token into a session token and saves that value. There is no parameter to turn that feature off because there is no downside to doing it and a single use token is too worthless to warrant another parameter.

Added previously unsupported operations
Now that authorizations are possible, so are authorized operations. I've done my best to provide pretty much any operation available through Picasa's core Data API in this PHP version. So you can post, update, or delete albums and images from an account that you have permission to do so in once you have have an authorized Picasa instance. You can also post or delete comments and tags, and retrieve private feeds.

The methods for posting, updating, and deleting are extremely similar to the methods for retrieving feeds. There are several "posting" methods, just like there are several "getter" methods described in the first section. So let's say you want to post an album titled "Dwight Schrute's One Night Stand" to the account "goldplateddiapers":

$pic = new Picasa($token, Picasa::$AUTH_TYPE_AUTH_SUB);

if ($pic->isAuthenticated()) {
  try {
      $album = $pic->postAlbum("goldplateddiapers",      //Username
             "Dwight Schrute's One Night Stand",         //Title
             "Dwight and Angela exchange cat pictures.", //Summary
             "private",                                  //Access rights
             "false"                                     //Commenting enabled
                               );
  } catch (Picasa_Exception_UnauthorizedException $ue) {
      print ("You are not authorized to add this album.");
  } catch (Picasa_Exception $e) {
      print ("An error occured while posting the album: ".$e->getMessage());
  }
} else {
  Picasa::redirectToLoginPage("http://yourdomain.com/samplePage.php");
}

Yeah, I know, the parameter list gets a little ridiculous. However, I've tried to order them in such a way that they will be as short as possible. For instance, had I wanted that album to be public and allow commenting, I could have left off the last two parameters.

Now that you know how to post an album, posting images, comments, and tags are all done the exact same way, though the parameter list varies. You can also update albums and images, although Picasa doesn't allow comments or tags to be updated. Deleting is allowed for all four types of objects. Read the documentation to see exactly which parameters are accepted for each type.

Added several fields to existing classes
The most noticeable difference here is going to be in the Picasa_Image class. The amount of information that is available for each image has just about doubled. You can see that Exif data and GML information are two things that were not supported in previous versions. One thing you will have to look out for, though, is that some of the fields will be null at times. It just depends on what the Atom feed from Picasa applies. To see what fields are null while testing your client code, just print the result of Picasa::getImages() and play around with the parameter values. The __toString() method will be automatically invoked and you can get a nice view of exactly what the instantiation looks like.

There is a cool new feature for some of the getter fields, too, that alleviates some of the problem associated with the null fields. You'll notice in the past that if you request all albums for a single username, the result would have come in the form of a Picasa_Account, which would have an array of Picasa_Album objects. However, those albums would not contain any images, presumably because it would take a lot of extra time to fetch and transfer the information about each image. Now, however, the method Picasa_Album::getImages() will check to see if the $images array is null and fetch a new instance of the current image, pull out the $images array from that instance, and return it. This way, if you want the value, it will always be there. The same logic follows for Picasa_Image::getComments() and Picasa_Image::getTags().

Comprehensive documentation using PHPDoc
I've gone to great lengths to document the entire API, and I finally went through the trouble of generating the docs and hosting them. I think the documentation will be really helpful in using this API, I have literally spent hours preparing it. One thing to note is that it's split up into two packages: Picasa and Picasa_Exception; the latter can be difficult to spot from the documentation's front page, there's a link to it at the very top. You can find all the documentation here.

I did not generate documentation for the Cam folder because it is not really part of the API and shouldn't be used. I attempted to change the code inside those files to utilize the new Picasa class, but the method names and intentions didn't really make sense in the context of the new version. They're still there, for backwards compatibility sake, and they work. However, if you're a newcomer, I would certainly ignore them.

100% backwards compatible with versions 1 and 2
As with the previous versions, drop the code in where your previous code was and you should have no problem. The one caveat is that you have to have had the classes inside the Picasa folder that was provided with the old versions. That folder is no longer the topmost level, the php folder is, so be careful when doing this. And as I stated earlier, the Cam folder is included for backwards compatibility.

It's still "lightweight"
It really depends on what you call "lightweight", but I think I've held true. The main thing is that there are no special packages needed with PHP in order for it to work. It was tempting to use the cUrl library or the Http classes, but I just implemented all the HTTP responses and requests myself.

Also, it's still a very easy install. You should be able to drop the files into your include path and pretty much be ready to go right away. A lengthier explanation is given in the README, but there's not a whole lot to it other than that.

The future
Obviously I've spent a lot of time trying to make this a product that people can actually use. I didn't expect to, but it remains to be by far the most popular topic on my blog, so I decided to expand on it. To that extent, I've also opened up a Google Code page for it, which I'll mainly use for tracking issues. You can visit that here. While I can't currently see a reason to make a version 4 of the API, I will certainly have future releases. With the added functionality, there will positively come added bugs, and there are enhancements that I have thought up that I did not get time to implement. So if you find a bug, let me know or add it to the bug list, and I'll probably release an update every month or two. It also really depends on the response, whether or not people seem to like the product. Whatever happens, I'll keep all the download links pointing to the latest release, so you can be sure you're getting the most up to date code.

I made this with the intent of making it easy for PHP developers to harness the Picasa service and create really cool new products, so please do so. As always, if you have any commentary, please leave a comment here or send me an email to tell me what you think. I would love to hear that someone really likes or really dislikes anything about the API. If you have features you'd like to see, feel free to let me know or add it to the issue list. And just in case you missed it at the top:

Click here to download the API

Thanks to everyone who has helped with this and everyone who is using it. Now while the bug list is still at zero and my eyes are still open, I'm going to play my Wii...

Lightweight PHP Picasa API Version 2.0

I haven't had a chance to post in a while, I've been busy preparing an update to the Picasa API I built for the Pictures section of this site. I didn't put a whole lot of effort into making the previous implementation much better than what I needed because I didn't think it would be worthwhile. However, it's been by far the most popular part of my site and I've received some good feedback on it. So now it's time to unveil version 2.0 of the Lightweight PHP Picasa API:

Download the API here.

In the new version I've focused heavily on documentation, because one of the gripes I heard from people was that it was tough to get something started. So I've added Javadoc style commenting to all the files included and will host the Javadocs here in a few days. Also to help things out, I've added several helper functions for doing things like retrieving an album or a photo, etc. So I think it will be much easier to get started if you're downloading it for the first time.

The two new classes I've added to the API itself are the Picasa_Author and Picasa_Comment classes. You probably haven't noticed, but I've started displaying comments on each photo (see this one, for example). I haven't got comment posting to work through the API yet, but at least now I can retrieve them. So the Picasa_Comments class holds comments and the Picasa_Author class holds authors. An author could be the author of an album or a comment, depending on the situation.

If you're already using version 1.0 of the software, don't worry, I've made this one fully backwards compatible. You should be able to replace version 1.0 with version 2.0 and your interacting code should need no update.

As always, if you have any questions or comments, let me know!

Update 04/09/2008: This post is for Version 2.0 of my Lightweight PHP Picasa API. Version 3.0 has since been released, which includes a great deal of expanded functionality. Go get it here for more Picasa PHP fun!

Yesterday's News

Is was brought to my attention about a week ago that the new version of Zend, released on November 30th, now supports Picasa. This was the support that I was looking for but could not find back in July when I wanted to add pictures to my site and was also the reason that I created my PHP interface for Picasa. So while this is good news for the community, it sort of leaves my work in the dust. I think once the holidays over I'll start moving my current implementation to the new Zend framework, the Pictures section included. I've already had some feedback that it might be a better idea to try to use my work with Zend so who knows, my code may have some life left. If anyone has any feedback on the new Zend framework that they want to share, please email me or leave a comment.

Help With the Picasa API in PHP

I gave some examples for my Picasa API in PHP in an earlier post (here) but I thought it deserved an entire post. The thing that can get confusing is that the API builds its objects using the queries described in Google's documentation. For instance, the code I posted earlier:

public function getAlbumsForDefaultAccount() {
     return new Picasa_Account(Cam_Util_PictureUtil::
         $BASE_QUERY_URL.'?kind=album');
}

However, this can also be a little tricky. So here's a quick method that will let get you all the public albums for any account. All you need to know is the User ID of the album's owner:

public function getAlbumsByUser($userid) {
     return new Picasa_Account('http://picasaweb.google.com/data/feed/
         api/user/'.$userid.'?kind=album');
}

Keep in mind that I haven't tested that code, so there could be a typo that I overlooked, but that's the idea. And as I said in the previous post, I would take most of that query string and put it into a constant so that if Google ever changes the format for the URL, it's easy to update all of your queries at once.

In case the idea still isn't clear, how about some code to get all the pictures from an album? All you need is the User ID and the album name:

public function getPicturesByAlbumAndUser($userid,$album) {
     return new Picasa_Album('http://picasaweb.google.com/data/feed/
         api/user/'.$userid.'/album/'.$album.'?kind=photo');
}

Now you should have an Album object with Picture objects for all the pictures in the album. It will also contain information about the albums such as location, date, etc. The information is all stored in the private members of the Album class and they are accessible through public getter and setter methods.

I hope this helps everyone. If it's still not clear, feel free to let me know. Again, feel free to download my API by clicking here.

Update 04/09/2008: This post is for Version 1.0 of my Lightweight PHP Picasa API. Version 3.0 has since been released, which includes a great deal of expanded functionality. Go get it here for more Picasa PHP fun!

Lightweight PHP Picasa API

As I've mentioned before, the Pictures section of this site is run through Picasa, Google's picture service. So I upload all my pictures to Picasa through a local application that they provide, I group them into albums, name them, give them a location, etc, and then they appear on CameronHinkle.com. This works out really well because their interface is nice for uploading photos and I don't have to pay for storage (I'm only using 13% of my total space and I can buy more if I need it). I also like that it's hosted in a central place with a lot of other photos because that means it's not sectioned off in its own little corner of the world. I don't usually get hung up on privacy concerns so the fact that I don't have control over the physical location of the photos does not bother me in the least.

Anyway, all of this magic is brought to you by Picasa's API. When I started this project, I was under the impression that Picasa, like Blogger, had a really slick API written in PHP that I could easily integrate with my site. It was going to be a piece of cake. Well, that turned out to not be the case. There was no existing PHP API, only one in XML, which meant I had to start the task of parsing lots of XML (which fortunately is really easy in PHP). To make things easier, I made my own PHP API that can really be used by anyone. So if you have a Picasa account and you know PHP, this makes it relatively simple to display your Picasa pictures on your website. And now for the first time, I'm publishing it on the web.

Click here to download my lightweight Picasa API in PHP.

The API is not great, it does exactly what I need it to do and not a whole lot more. However, it's extraordinarily easy to add on to. Basically it is set up with 4 types of objects that are simple to understand: Accounts, Albums, Images, and ImageCollections. Accounts have Albums, Albums have Images, and ImageCollections also have Images. Everything is pretty self explanatory except possibly ImageCollection, which is just a way to contain several images that are not from the same Album because there are different rules (like ImageCollections aren't given a title). The easiest way to understand how each class works is to look at it's constructor because that will tell you what to pass in to make a given object. Be aware that if you only need one photo, creating an entire Account object will take forever, so there's an easy way to create just a single Image object.

If you want to publish your uploaded photos on the web, this is perfect! If you want to upload your own photos, it's not so good, but it may be a good start. Hopefully someone needs to do more than I did and runs with the idea. However, I assume that there will be a Zend package available for Picasa within the next 6 or 12 months, at which point my API will be completely obsolete. Until then, enjoy!

Update 04/09/2008: This post is for Version 1.0 of my Lightweight PHP Picasa API. Version 3.0 has since been released, which includes a great deal of expanded functionality. Go get it here for more Picasa PHP fun!

UPDATE 12/2/2007: I eventually took the time to post some help with using this download and that article is posted here. I will probably offer additional help later.

We have liftoff

With the help of my co-worker Alec (whose finger is visible at right), I've managed to get the development of Popratings.com started. Every development project has a first step, and most of them involve the words "Hello, World!".

I'm really terrible at IT-related work so I feared setting up an environment would be painful but it was actually not so bad. I decided to go with Ubuntu Server Version 7 as a development environment. As a user, I'm more comfortable operating in Windows (which I'm not necessarily proud of, but it is a fact) but for programming, I've been working in Linux for the last 5 years so I prefer that.

Since I don't have a spare computer lying around, or space for one, I found a VMWare image at thoughtpolice.co.uk and have set up the environment there. To start working, I installed PHP 5.0, Subversion, and Vim using Aptitude, which was all very easy. I decided to go with Subversion mainly because I don't really know anything about it and I've heard good things. As for Vim, I haven't decided what I'm going to do for an IDE but Vim will suffice in the interim.

For a few different reasons, I want to have a lot of control over the way the URLs look in Popratings. Because of this, I'm using Mod_rewrite inside Apache to map all URLs that aren't images to a front controller, which I call TrafficController.php (although I certainly could have come up with a more useful name, this is my first PHP project in a couple years so I'll learn from my mistakes). In addition to providing his finger for the photo, Alec also gave me the idea to use .htaccess files to route traffic to a front controller class, although I believe you could also do it for an entire site as opposed to a single directory using 000-default in /etc/apache2/sites-enabled/. Alec used .htaccess files for a site he worked on a few months ago and said it worked out well.

I also decided to add a sub-directory for Popratings in the default directory that Apache serves files from (/var/www/) so that I can easily support more sites in the future from the same server. I can add directories to this folder as my list of sites grows. To accomplish this as well as the URL rewriting, I followed these steps:

• enable Mod_rewrite by adding a symlink from etc/apache2/mods-available/rewrite.load to /etc/apache2/mods-enabled/rewrite.load. The command for that is ln -s /etc/apache2/mods-available/rewrite.load /etc/apache2/mods-enabled/rewrite.load
  


• in /etc/apache2/sites-enabled/000-default, set the DocumentRoot to /var/www/popratings/ so that Apache knows where to get the files specific to Popratings


• in /etc/apache2/sites-enabled/000-default, change /var/www/ to /var/www/popratings/ so that the settings in 000-default are applied to the files specific to Popratings


• in /etc/apache2/sites-enabled/000-default change "AllowOverride None" to "AllowOverride all" to allow rewrites


• create a file at /var/www/popratings/.htaccess so that I can control traffic sent to the document root

Then, my .htaccess file looks like this:

Options +FollowSymLinks
RewriteEngine on
RewriteRule ^$ /home/
RewriteCond %{REQUEST_FILENAME} !^.*css
RewriteCond %{REQUEST_FILENAME} !^.*js
RewriteCond %{REQUEST_FILENAME} !^.*jpg
RewriteCond %{REQUEST_FILENAME} !^.*gif
RewriteCond %{REQUEST_FILENAME} !^.*png
RewriteRule ^(.*)$ TrafficController.php?uri=$1

There are a couple notes to mention here. One is to make sure that when you add "FollowSymLinks" to Options, if you leave the plus sign out, you'll override the other settings for Options that are defined in 000-default. This is a problem if you're writing PHP (and other non-HTML languages) because you'll get a "Forbidden" error. From what I've read of the documentation, I think it's because the "MultiViews" Option gets overridden, although I may be mistaken. At any rate, using the plus sign in front of FollowSymLinks adds it to the other options rather than overwriting them.

To explain a bit about the rewrite rules and conditions, the first rule states that if there is nothing after "popratings.com" in the request, direct the traffic to /home/. The next conditions take all images and include files out of the scenario and tells everything after "popratings.com" to be added as a parameter to TrafficController.php with the name "uri". Note that this includes cases where a user was just accessing the home page, in which case "/home/" is added as the uri parameter. In other words, the URL continues through the redirect rules even after being altered by one of them. Also note that the list of files to exclude from the rules is probably incomplete; you may want to add .exe, .pdf, and/or .xml, among others. As the list gets longer, you may want to change the regular expression so that it only requires one RewriteCond for all necessary file types.

This information was all available on the web but it was not usually specific to my operating system and was not all in one place, so it took a little work. I'm now ready to get some real work done. Unfortunately after setting up this environment, I sat down to actually do that work last night and realized that while I know a lot of design theory, I've forgotten almost all the PHP practice :-( While the progress may take a little bit of effort to get going, I'm sure it will be like riding a bicycle.

Heavy reading

Since leaving Portland for India, I've had more time to sit and read than I normally would. I saw this coming and in the weeks before I left, stocked up on some interesting reading. As a pet project, I'm going to start building a website for a domain name I registered over a year ago, Popratings.com. Right now it's just a lot of ads from my registrar but when it's finished it will be a site for users to submit reviews on various things. I'll get more into the details of the functionality in a later post, but rest assured that it will include social networking, Web 2.0, and Ajax, as well as any other buzz words that happen to be popular at the time. It's really just a way for me to get back into programming and, more specifically, into PHP.

Since this project is aimed at getting more familiar with some of the technologies I've used in the past and using some skills I've picked up while working at my current job, I want to do everything myself. Given that this covers several different areas, I chose four books to read based on what I'll need to know and what I'm not already comfortable with. The four books are The Principles of Beautiful Web Design by Jason Beaird, User Interface Design for Programmers, by Joel Spolsky, PHP 5 Objects, Patterns, and Practice, by Matt Zandstra, and Beginning JavaScript with DOM Scripting and Ajax: From Novice to Professional, by Christian Heilmann.

I've only had a chance to read the first three selections but so far they're all worth reading. Joel Spolsky is someone who I have a lot of respect for as a developer and an entrepreneur. I've been reading his blog over the past year, which is what prompted me to get his book. Although it's a bit brief, he really has some very simple but effective things to say. His book has stood out the most as being a valuable asset for anyone designing user interfaces- it should definitely not be limited to programmers.

The second two books have certainly been useful. Beaird had a lot of good techniques to share. Towards the end of the book, he walks us through the process of designing an actual website for a client he had, which was helpful. Some of the material throughout was covered in my high school art class but I'm sure it's helpful for many people.

PHP 5 Objects, Patterns and Practice has been a great source of information. The first third covers new features to PHP 5, which you can really skim through if you know Java (yes, Java). The last third covers several PHP tools, including package managers and automated build tools, and will be a great reference. The heart of the book focuses on implementing several design patterns in PHP. There's actually not very much PHP-specific information in this portion. In fact, you might be better off reading the beginning and end of Zandstra's book and Design Patterns: Elements of Reusable Object-Oriented Software by the "Gang of Four", which is referenced throughout PHP 5 Objects, Patterns and Practice.

I'm looking forward to putting these to use; I plan to start writing Pop Ratings in the next week and hope to get a lot done while I'm in India. As I go along, I'll be logging anything particularly difficult or interesting that happens so that hopefully it will be useful for others working on similar projects.