Gold Plated Blog Posts

Whatev.

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

Comment Moderation Through the Picasa Tools Suite

If anyone has ever read about my innovative commenting setup, you can probably guess that it results in one thing: a lot of random spammy comments. It also results in people who wouldn't normally comment on my photos doing so, which is what I built it for so it's a success in that sense. Still, cluttering the image pages with gibberish or inappropriate comments isn't good for the user experience. Unfortunately, the only way to monitor the situation is to periodically view every image in my account...until now!

Introducing Picasa Comment Moderation. With this tool, any Picasa user has the ability to view and delete comments in their Picasa account with the click of a button. The comments are sorted by the date and time they were posted and you have the option of viewing between 5 and 50 comments at a time. The image, image title, and coment author are displayed on the screen for your reference, as well as a link to the image on Picasa's website. You can even hover over the image to see the description if you're not quite sure what you're looking at.

You may notice that when you hit the link to go to the Comment Moderation tool, you're actually taken to the front page of the Picasa Tools Suite. This is for two reasons. The first is that Google requires one single exit point for any site requesting access to a user's Picasa account, so it was impossible to make a page dedicated to Comment Moderation when I already had the Picasa Image Name Updater. Secondly, doesn't two tools constitute a suite?! Well maybe not. If you have an idea for another tool I can create, please let me know so that I can truly make it a legitimate suite.

As always, the Picasa Comment Moderation tool was created with the Lightweight PHP Picasa API. Using the API proved very easy in enabling me to display and delete comments. In fact, the entire project only took around six hours to write. Now go use it! And if you have any comments/suggestions/bugs, send them my way.

Change Your Picasa Image Titles

I've had a problem since I created the Pictures section of my website and that is that my individual image pages are not included in my site's Page Count according to Google (see what I mean). This is a problem since I have a few thousand images and they would greatly increase the number of pages on the site. I figured that since I have unique content on each one (the image description and any comments entered), they should count. I brought this up to an SEO-specialist friend of mine and the first thing he pointed out is that the page titles are virtually identical across a single album. This is because I use the image title according to Picasa, which is the filename when I uploaded it to Picasa, which is whatever my camera named it or whatever generic name I came up with when I imported them from the camera. I couldn't think of anything better to use for the title and unfortunately Picasa does not offer an easy way to change the image titles.

The answer to my problem is the Picasa Image Name Updater by yours truly, Cameron Hinkle. Harnessing the power of my Lightweight PHP Picasa API, I whipped up this handy little app in just about 12 hours. Now I can update images in my Picasa account at my every whim- and you can too! I created it using AuthSub, which means you sign in to your account on Google's site and then just grant access to my app. You then type in the account you want to update, select an album, and start updating image names! I tried to model the interface after Picasa's web interface for entering captions, although I'm not a Javascript programmer so I didn't use any AJAX.

This was a great exercise in eating my own dog food. I was happy to find that things went relatively smoothly and I was able to do all the backend programming in about seven hours, which is pretty solid given the complexity (yes, that means the style took me 5 hours...I'm so bad with CSS it isn't funny). If you want to have nice-looking image titles on your account, try it yourself and feel free to leave any feedback you have here. I'd love to know what people think.

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.

New to the Pictures Section

This is kind of a two-part post. The first is to just let everyone know that I've finally uploaded pictures of the Portland wedding that my Uncle Steve took. If you were at the wedding, there's a good chance you'll find yourself in one and if you weren't, check it out to see what you missed!

If you've ever used the commenting option at the bottom of each picture, you'll also notice a few new features. I'm sure you know how frustrating it is when you don't enter your name and it inserts "Some anonymous shmoe" as a replacement. My first new feature alleviates that problem to a large extent. Now the first time you enter a comment on a computer, it will remember your name and if you forget to enter your name in a future comment, it will insert the name you used in your last comment. It won't follow you around from computer to computer (that would be impossible) but it will work on any computer you use as long as you don't clear your cookies.

If you like to comment on photos you probably know the feeling you get when you accidentally hit the Enter button after leaving half a comment, or the feeling you get when you leave comments after heavily drinking the night before and wake up to find yourself the laughing stock of the community (the cameronhinkle.com community, that is. ....so basically, me). At your rescue is the new "delete" button. It's in the form of a red X and it will appear at the end of all your future comments. Again, it only works per-computer and will be there as long as you don't clear your cookies. If you don't know what "clear your cookies" means, you'll have some catching up to do. I would start here.

For those of you who care, I'll get a little into the specifics of how I made these possible. The first is easy, I just set a cookie in your browser that contains the name you enter for each comment, then I check for it if you don't enter a name in the future. The delete button is a little tougher. Cameronhinkle.com now keeps a cookie in your browser that holds a pipe-delimited list of comments that you've made. Every time you enter a new comment, it adds the comment id to the cookie. Then whenever you view a picture on CameronHinkle.com, it explodes the list of comment ids into an array and iterates through each comment id to see if it exists in the array of comments that have been submitted for that photo. If a comment is found in the array, it puts the red X inside a form at the end of that comment with the comment id as a hidden field. When the X is clicked, the form posts the comment id to the server and the comment is deleted using my versatile and robust Picasa API. The way that it is deleted is similar to the way it's posted, which you can read about in my article Comments: Enabled. I haven't worked out all the kinks (in fact it just blew up on me a second ago) but it's coming along nicely and I think it will be a really useful addition.

This deleting mechanism obviously opens up a bit of a security risk. All someone would have to do is post a comment id to the page to delete any comment they want. I'm not too concerned about this because I don't know who would care about deleting comments. Also, it would be a little bit of a hassle to find the comment id for a particular comment, especially if you don't know anything about the Picasa API. If I put the X next to every single comment I could definitely see someone clicking all the X's just to be annoying, but it's probably inconvenient enough as it is that no one will bother. If I'm wrong and there is an incident, I'll just encrypt the ids before I store them in the cookie. I would do that now but I wanted to make the page load as fast as possible.

Hopefully this and the Comments: Enabled post has given some people a few creative ideas of what is possible with the API. I've gotten a lot of good feedback on the Pictures section in general and am always trying to come up with ways to improve it. Of course if you don't use it then all my work is in vain, so go comment find your favorite picture and make some comments!

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...

Comments: Enabled

Some of you may have noticed a few weeks ago that a text area for submitting comments appeared in the Pictures section of the site. Unfortunately, entering comments into the comment box would never actually produce any results. Good news! Commenting is now enabled. Feel free to browse through pictures and leave a comment if the mood strikes.

As you're posting your comments, you may find it peculiar that you don't have to sign in to anything to leave a comment and you may wonder why that is, given that Picasa does not allow anonymous comments. Well my philosophy has always been that if you have a feature that you want people to use, you should make it as easy and accessible to the user as possible. I saw having to login to your Google account as obtrusive and a barrier that would probably stop a lot of people from leaving comments. And having to leave this site for Google's login page sort of ruins the continuity of the site. I've had anonymous commenting enabled on my blog for several months now and moderating hasn't been overly time consuming, so I thought up a solution.

The solution is a big workaround and one that a lot of people probably won't be comfortable for themselves. If you'll notice when you view an image on my site (for instance), the comment author is not always the same as when you view an image directly from the PicasaWeb site (for instance). Essentially what I've done is allowed any user to post a comment on any of my photos through my own username. Once a comment is submitted, it logs the person into my Picasa account and posts the comment as though I had said it. Then to keep track of who the poster says they are, the name they entered is appended to the end of the comment, surrounded by a sequence of characters. You can see in PicasaWeb that the sequence of characters is "-={". Any time that sequence is found in a post, the text inside is stripped and set as the author. Anything after the author is discarded.

This method has a few obvious problems. First of all, PicasaWeb is going to fill up with comments posted by me and I can't really control what is posted for a time. It's not like my site gets a lot of traffic from people I don't know, though, so I think that will be fine, and I'm emailed the comments every day so that I can easily moderate them. Just to be safe, a disclaimer is tagged to the bottom of each comment, which you'll only see on the PicasaWeb site. The second problem is that this method is certainly not supported by Google. I doubt they really want me doing this, as it sort of damages the integrity of their comments and accounts. I think they likely have bigger things to worry about, but we'll see. The interesting thing is that the current version of the Google's Picasa API has a bug that will not allow a comment to be posted to an image by anyone except the owner of the Picasa account, so this is actually the only way that anyone except myself could comment on my photos through this site.

So begins the great comment experiment. It was a lot of work, but if it doesn't prove to be successful, I can always switch over to standard, authenticated commenting without too much trouble once the bug is fixed. I'm excited about this new feature and hope that it will be a way to make the site more interactive and get people more interested in seeing what new photos have been posted. Keep in mind that I finished this feature a few hours ago and I do expect some bugs (particularly if you're using Internet Explorer, but you should switch to Firefox anyway) so if it doesn't work for you, let me know and keep trying! I've done several tests and they've been successful thus far. Like I said, it was a lot of work to get comments up and running so I'll post the PHP code for how I got it working soon. I'll also be adding it to version 3.0 of my Picasa API, so look for that in the next month or two.

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.

Arcadia Beach Roadie 2007

Over Labor Day Weekend, me and the old high school gang got together for a camping trip. While it was without a doubt the worst planned camping trip ever (especially for Labor Day Weekend), it actually turned out pretty well. We had no idea where we were going to stay but we headed out Friday night at about 8:00 for the coast. Without a place to lay our head, we drove up and down the 101 for 45 minutes in the dark of night, stopping wherever we thought we saw a possible campsite. Finally, around 11:00, we found our final destination.

"Camping Prohibited!" said the sign at the front of the beach, but we didn't care. We didn't really have much choice, really. We saw some cars in the parking lot and investigated a little further; indeed, at least 3 other groups had pitched tents on the beach. So we found a place that wasn't too intrusive and started hauling our stuff down the steps to the sand.

Saturday was a gorgeous day. Bright and sunny, but with a little breeze as well. It was one of the nicest days I've spent at the beach. I didn't leave the beach the entire time, except to go back to the car. I did a lot of reading, took a lot of pictures, and watched Heim almost kill himself. Oh yeah, Heim almost killed himself. He climbed up some pretty steep rocks and after he'd gotten about 30 feet off the ground, realized his footing was largely unstable. We realized it too, when we saw large rocks falling from the cliff and making a loud THUD! as they hit the wet sand below. Anyway, he eventually found a way back down, but it was a little tense for a while. He even drew quite a crowd, as you can see in the picture.

The next morning, we awoke to a loud voice, "You are in violation of Oregon State law. It is a $97 fine for camping on the beach. I'm giving you 30 minutes to pack up and leave, at which point I will start handing out citations. You are all banned from the beach for 48 hours." The ranger was pretty cool; he took all of our id information and then pretty much left us along while we packed up. It worked out for the best, really; I wanted to leave early and this gave everyone a reason to pack up as quickly as possible. We're all just glad he somehow missed us on Saturday morning.

In related news, if you'd like to see pictures of our trip, you can now do so here. Some of you may have noticed that the Pictures section is sort of working now. It's not pretty, but you can see all the pictures in my Picasa account, which is a pretty big accomplishment. There aren't any PHP tools available for the Picasa integration like there was for the Blogger integration, so it's ended up being an entirely different experience trying to make the pictures show up. While the style is nowhere near where it needs to be, the pictures are all there. I did a little home-brew API in PHP to handle all the XML parsing from Google's Atom feed. I'll go through what I did to set that up at a later time and post my code for download in case anyone wants it. I'm not taking the time to make it really robust, but if someone wants to add data that I leave out, they can easily add to it. Look for that in the next few weeks and look for the pictures section to be finished later this week.