Announcing: phpSmug - A PHP Wrapper to the SmugMug API

lildude · October 7, 2007

Ladies and gentlemen, may I introduce you to a new project of mine…

phpSmug is a PHP wrapper class for the SmugMug PHP API. Whilst there esentially isn't a need for the wrapper, the intention of this class is to allow PHP application developers to quickly and easily interact with the SmugMug API in their applications, without having to worry about the finer details of the API.

phpSmug is written for PHP 4 and PHP 5, however PHP 4 support will be withdrawn at the end of the year when PHP 4 officially reaches the end of life, announced here, and then I’ll work on optimising this to take full advantage of PHP 5’s great features. Don’t worry, I will still keep the PHP 4 supporting version available for those who can’t move to PHP 5 immediately.

phpSmug is based on the great work of Dan Coulter in phpFlickr.

I intend on having two concurrently running versions of phpSmug - one for each version of the API versions SmugMug is currently supporting.

phpSmug at the moment only supports the 1.2.0 API calls, but I’m in the process of creating a branch for the 1.2.1 API calls. <del>I'll update this thread when it's available.</del>

Now I’ll let you in on a little secret - the reason I’ve created this class is I’m in the process of creating a gallery plugin for Wordpress (to be called SmugGal) that draws photos from SmugMug, very much like FAlbum draws photos from Flickr. When this is released (hopefully by 31 Oct ;-) ), it will use the 1.2.1 API.

I've contributed a huge amount of my time and code to FAlbum (I'm the second largest contributor behind the main developer), and after numerous requests, am finally working on the an equivalent for SmugMug.

To try and keep things simple, I’ve separated the API interaction code (phpSmug) from the gallery code (SmugGal).

So, if you’re a PHP application developer, and need to interact with SmugMug, please feel free to use phpSmug and drop me line to let me know what you’re up to with this class.

I'd really appreciate it is somone could add a link to phpSmug, just below Riyad Kalla's Java API link, on the wiki too.

13 Oct '07 - UPDATE: phpSmug 1.1.1, which supports rev 1.2.1 of the API ,is now available. At the moment, it only officially implements those methods detailed at http://dgrin.com/showthread.php?t=71887.

The code is in place for ALL of the functions listed on the wiki, however some of the methods haven't been implemented in the API itself, so I've not tested these, so can't be sure they'll return the correct data. At the moment, these methods are commented out and will return "Not implemented in API yet".

I'll update phpSmug 1.1.x as these methods become available.

28 Jan '08 - UPDATE: I've been a bit slack in updating this thread as I've released new revs of phpSmug. Here's a summary of recent updates:

1.0.5 / 1.1.3 - 27 Jan ‘08
- All login.with* methods now use HTTPS to ensure login information is encrypted (Ticket #14)
1.0.4 / 1.1.2 - 4 Jan ‘08
- Changing caching to ensure more consistent caching (Ticket #11)
- Changed “response” database table field type to LONGTEXT to cater for larger amounts of data. (Ticket #12)
- Fixed issue where apostrophes in cached data are not escaped correctly (Ticket #13)

9 Feb '08 - UPDATE phpSmug 1.0.6 / 1.1.4 now support the new security functionality.

10 Feb '08 - UPDATE Forgot to take into account the ImageKey returned by image_upload() and image_uploadFromURL(), and AlbumKey returned by album_create(). These functions now return an array holding the ID and key. Thanks to devbobo for pointing this out so quickly.

23 Feb '08 - UPDATE Made changes to the caching code to fix caching issue brought up by rolandk98 on this thread and to take into account 6 hour SessionID inactivity timeout.

26 Feb '08 - UPDATE Removed extra "}" from phpSmug 1.0.8. phpSmug 1.0.9 now available.

4 Mar '08 - UPDATE I've had a busy couple of afternoons quashing bugs and enhancing phpSmug further. This release sees the re-introduction of anonymous method call caching (Ticket #18), enableCache() now checks cache directory is writeable (Ticket #19), die_on_error is now acknowledged consistently. If die_on_error is NOT set, it's up to the application developer to check getErrorCode and getErrorMessage after each method call. (Ticket #20), I've added clearCache() function to easily empty the cache. (Ticket #22) and I've Stopped caching the results of failed method calls when die_on_error is set. (Ticket #23).

phpSmug 1.0.10 and phpSmug 1.1.7 now available

Enjoy.
_____________________________________
Colin Seymour
Personal Blog | Tech Blog

Nimai · October 7, 2007

Sounds cool!

onethumb · October 8, 2007

Awesome!

Blogged, posted to the mailing lists, and linked on the wiki. Make sure you enter this in the contest, too, once it's got 1.2.1 support.

Thanks!

lildude · October 8, 2007

Will do, thanks.

lildude · October 13, 2007

Support for 1.2.1 of API now available.
phpSmug 1.1.1, which supports rev 1.2.1 of the API ,is now available. At the moment, it only officially implements those methods detailed at http://dgrin.com/showthread.php?t=71887.

The code is in place for ALL of the functions listed on the wiki, however some of the methods haven't been implemented in the API itself, so I've not tested these, so can't be sure they'll return the correct data. At the moment, these methods are commented out and will return "Not implemented in API yet".

I'll update phpSmug 1.1.x as these methods become available.

encosion · November 15, 2007

I'm liking where this is going... And am pretty excited at the thought of SmugGal since I'm fast becoming a WordPress convert... Thanks for your time and effort, I'll be watching this!

lildude · November 16, 2007

Bit of a delay on SmugGal

encosion wrote:

I'm liking where this is going... And am pretty excited at the thought of SmugGal since I'm fast becoming a WordPress convert... Thanks for your time and effort, I'll be watching this!

Good to hear it. There's been a bit of a delay on the first release of SmugGal due to work commitments, and also due to a change in strategy for it's implementation.

I won't get into the details just yet, but watch this space.

plympton · November 19, 2007

Awesome!
I've been procrastinating about finishing SmugSync (rsync for SmugMug), and now this and the h.264 support is going to push me over the top. Cool!

-Dan

lildude · January 28, 2008

Revs 1.0.5 and 1.1.3 now available.
Bumped for new revs. Revs 1.0.5 and 1.1.3 now available.

Brett Mickelson · February 8, 2008

lildude wrote:

Now I’ll let you in on a little secret - the reason I’ve created this class is I’m in the process of creating a gallery plugin for Wordpress (to be called SmugGal) that draws photos from SmugMug, very much like FAlbum draws photos from Flickr. When this is released (hopefully by 31 Oct ;-) ), it will use the 1.2.1 API.

Does this exist yet?

lildude · February 8, 2008

Brett Mickelson wrote:

Does this exist yet?

Yes, and I was very close to releasing it (just tidying up the code and documenting everything), but there has been a change to the security features in the API. I intend on updating my code to support the new security changes before I release it (it'll save work and people updating at a later stage).

I envisage it'll be ready within the next month or so (provided work doesn't get too crazy).

lildude · February 9, 2008

Bump for new rev

devbobo · February 9, 2008

lildude wrote:

Bump for new rev

Hey Colin,

Thanks for being so proactive with implementing the new security features

Just had a quick look through the code and I have two suggestions, I think you need to return...

- the AlbumKey with the albums_create function
- the ImageKey with the images_upload and images_uploadFromURL functions

Cheers,

David

lildude · February 10, 2008

devbobo wrote:

Hey Colin,

Thanks for being so proactive with implementing the new security features

Just had a quick look through the code and I have two suggestions, I think you need to return...

- the AlbumKey with the albums_create function
- the ImageKey with the images_upload and images_uploadFromURL functions

Cheers,

David

Doh!! I forgot that these function calls were returning just the image ID. I've changed this now in rev 1.0.7/1.1.5. The functions now return an array containing the ID and Key.

Thanks for spotting this so quickly.

Cheers,
Colin

rolandk98 · February 20, 2008

caching issues
phpsmug is great, we were able to port an application writen for flickr with relative ease. But.

but is the bellow described a bug??

If caching is enabled, and you login anonymously the first time, then, within the same session you login withpassword, the cache value of the anonymouse login is returned.

why would you login anonymously and then with password???

I wrote a web application that uses smugmug api and gives the user the ability to retrieve the list of their public albums by loging in with just their nickname [to get public album] or username and password to get all albums. (most people will try out just nickname login before just pluging in their username and password on a new website right!!!) but if they like it and feel comfortable, they would like to retrieve all their albums, public or unlisted. so if within the same session they had loged in with just nickname (i.e. anonymouse) the second login using withpassword will not work or will just return the cache value of the anonymouse login.
is it a bug? or my error?
if i dissable cashing everything works just fine
thx
roland

lildude · February 21, 2008

rolandk98 wrote:

phpsmug is great, we were able to port an application writen for flickr with relative ease. But.

but is the bellow described a bug??

If caching is enabled, and you login anonymously the first time, then, within the same session you login withpassword, the cache value of the anonymouse login is returned.

why would you login anonymously and then with password???

I wrote a web application that uses smugmug api and gives the user the ability to retrieve the list of their public albums by loging in with just their nickname [to get public album] or username and password to get all albums. (most people will try out just nickname login before just pluging in their username and password on a new website right!!!) but if they like it and feel comfortable, they would like to retrieve all their albums, public or unlisted. so if within the same session they had loged in with just nickname (i.e. anonymouse) the second login using withpassword will not work or will just return the cache value of the anonymouse login.
is it a bug? or my error?
if i dissable cashing everything works just fine
thx
roland

Hi Roland

Glad to hear you've found it useful. I'd love to see what you've done with phpSmug - I can even add a link to my project page if you want.

I can shamefully say this is a bug, and without even looking at the code I know why. I made a change to the caching a while back to try make caching simpler (also because of something I couldn't determine from the session ID at the time, see below), however I have to admit I didn't think of the scenario you've detailed, and by the fact it's taken so long to come to light, I don't think anyone else did either

I'll reverse my change in the next rev (I'll try get this out today).

In the mean time you can reverse the change I made by commenting out the:

$request['SessionID'] = ''; // Unset SessionID

... line at the beginning of the getCached() and cache() functions in phpSmug.php.

This has two catches:

1. You MUST enable caching BEFORE calling any of the login_* functions, else you'll end up generating a new session with every login_* call, and subsequently every single API call, which kind of defeats the point of caching.

2. I still don't know (I've just posted my query here), how long each session is valid for. I've found that if a session isn't used for a while (somewhere between 8 and 24 hours), it's ID is no longer valid, however if it's regularly used, eg every 2 hours, it seems to last indefinitely.

Once I know the answer to this last catch, I'll update the code. It's essential I know this as this has an effect on the maximum cache value someone can use with phpSmug. For example, if the session inactivity timeout is 8 hours, and a developer sets the cache expire to 24 hours, we hit a problem if a user logs in, lists their albums and then doesn't come back for 20 hours. Their session ID would be invalid, but the cache would still be valid, and thus will still be used.

My previous change removed the need to know this as the session ID was never stored.

I'll update this thread when I know the sessionID inactivity timeout and when I've updated my code.

Thanks for pointing this out.

Cheers,
Colin

lildude · February 21, 2008

lildude wrote:

2. I still don't know (I've just posted my query here), how long each session is valid for. I've found that if a session isn't used for a while (somewhere between 8 and 24 hours), it's ID is no longer valid, however if it's regularly used, eg every 2 hours, it seems to last indefinitely.

Ok, I now know the timeout - 6 hours of inactivity. It's going to take a little longer for me to get back to you with the complete fix as I'd ideally like people to be able to set a cache timeout of more than 6 hours and have it actually used.

I'm going to have to do a bit of testing with the current caching methods to see if I can come up with a more efficient method. If possible, I don't want to pummel the SmugMug API servers every 6 hours if possible - it puts unnecessary load on the servers and potentially slows the apparent performance of applications using phpSmug.

Watch this space.

lildude · February 21, 2008

Hi Roland

I've been thinking about this some more, and if you don't make the changes I specified in an earlier post, thus leaving the code as it is, you can get the correct behaviour, with caching enabled, by NOT using the nickname in the albums_get() call after logging in with a password.

The nickname isn't needed once you've logged in as it defaults to the user anyway. It's only really needed when viewing other people's albums, which you can only do anonymously anyway.

So if we put this into code, you should find the $anon_albums will show only the public albums and the $all_albums will show the unlisted and public albums:

<?php 
require_once("phpSmug.php");
$f = new phpSmug($APIKEY, "Testing phpSmug");
$f->enableCache("db", "mysql://$USER:$PASSWD@$HOST/$DB");

$f->login_anonymously();
$anon_albums = $f->albums_get("$NICKNAME");

$f->login_withPassword("$EMAIL", "$PASSWORD");
$all_albums = $f->albums_get();

echo "<pre>";
print_r($anon_albums);
echo "============================";
print_r($all_albums);
echo "</pre>";
?>

Is this a usable solution for you?

I'm reluctant to start caching the SessionID as part of the request (it's still cached in the response) due to the 6 hour inactivity timeout.

lildude · February 21, 2008

Ignore my previous post. I've just thought of a problem with this strategy. If you left things inactive for 6 hours between calling the login_with*() and the first time you called albums_get(), you'd hit the 6 hour SessionID inactivity timeout and your albums_get() will fail.

I'll re-architect the caching algorithm to take this SessionID inactivity timeout into account, and still allow for a custom cache timeout of greater than 6 hours.

I should have something for you tomorrow.

rolandk98 · February 21, 2008

lildude wrote:

Hi Roland

Glad to hear you've found it useful. I'd love to see what you've done with phpSmug - I can even add a link to my project page if you want.

Cheers,
Colin

Collin, many thanks for your very active and fast response. I am using it as is for now and it works fine, so take your time no rush. I just dissabled caching.

My site that is using phpSmug is http://www.terasnaps.com/ and how I am using phpSmug can be viewed in the flv video here http://www.terasnaps.com/howtovideos/smugmughowto.php . I will post a more complete description in the appropriate section of this forum later. But basicaly is retreives your smugmug photos, does face detection, recognition and provides you with the ability to organize your family photos by the people who are in the photos.
It is calibrated to detect faces that are the subject of the picture as opposed to background people. So its ideal for family photo organization as opposed to artistic photos.

Terasnaps also creates an anonymouse browsing envirment where tags and nicknames are not displayed at all and the bowsing is based in familiarity with the individuals in the photos.
Terasnaps is also an image combining network that can combine images of particular individual accross multiple terasnaps accounts and combine same events accross multiple terasnaps account. So check it out and let me know, I just released the smugmug integration and wanted to let you know first with many thanks. testers are welcomed.
Feel free to add my websites link to your project pages if you wish.
Again Many Thanks
Roland

lildude · February 23, 2008

phpSmug 1.0.8 and 1.1.6 now available
Bumping for new versions following discussions about caching.

I've fixed the caching issue by not caching the anonymous method calls. I've also added a way to ensure the 6 hour SessionID inactivity timeout doesn't cause problems.

voytek · February 24, 2008

Thanks for the nice library. I've started screwing around with it as described here: http://voytek.jarnot.org/blog/2008/02/24/testing-a-smugmug-plugin/

One idea about caching. If one is using phpSmug within an application (such as wordpress, for example) where one already has access to DB connections it would be useful to be able to point phpSmug at those rather than have it create its own - a third caching option in other words.

lildude · February 25, 2008

voytek wrote:

Thanks for the nice library. I've started screwing around with it as described here: http://voytek.jarnot.org/blog/2008/02/24/testing-a-smugmug-plugin/

One idea about caching. If one is using phpSmug within an application (such as wordpress, for example) where one already has access to DB connections it would be useful to be able to point phpSmug at those rather than have it create its own - a third caching option in other words.

Hmmm, nice idea. In theory you could probably do this already now as the only unique identifier, the SessionID, isn't actually cached other than in the results from the login_*() method calls, and the cache is checked before any API call is made. So in theory, if they're both sharing the same cache, they should both query the same results.

The only problem I can think that may happen is one application may trample all over the entries cached by the other application. I'm actually in the process of finishing off an app that uses phpSmug (the SmugGal I referred to right at the beginning) which can run standalone and under Wordpress.

I'll let you know how I get on (probably later this week).

Oh, and nice work with the what you're doing with phpSmug.

anderiv · February 26, 2008

Hey Colin - I believe you have an extra curly bracket in the 1.o.8 tarball. Here's the diff to a version I corrected:

--- phpSmug.php 2008-02-25 23:46:20.000000000 -0600
+++ phpSmug-EA.php      2008-02-25 23:47:04.000000000 -0600
@@ -199,7 +199,6 @@
                                        }
                    }
                }
-               }
         return false;
     }

Prior to removing that bracket, I was getting a php error on line 203 of phpSmug.php. After removing it, everything worked great.

-Erik

lildude · February 26, 2008

anderiv wrote:
Hey Colin - I believe you have an extra curly bracket in the 1.o.8 tarball. Here's the diff to a version I corrected:
--- phpSmug.php 2008-02-25 23:46:20.000000000 -0600
+++ phpSmug-EA.php      2008-02-25 23:47:04.000000000 -0600
@@ -199,7 +199,6 @@
                                        }
                    }
                }
-               }
         return false;
     }
Prior to removing that bracket, I was getting a php error on line 203 of phpSmug.php. After removing it, everything worked great.

-Erik

Oh bollocks!!! I think you may be right. I'll try update it this evening when I get home. Until then, I've logged ticket #17 to track the issue.

Thanks for pointing it out.

lildude · February 26, 2008

phpSmug 1.0.9 now available.
As promised. phpSmug 1.0.9 is now available and removes the extra "}" that Erik pointed out. Thanks Erik.

anderiv · February 26, 2008

lildude wrote:

As promised. phpSmug 1.0.9 is now available and removes the extra "}" that Erik pointed out. Thanks Erik.

Thanks Colin.

espaan · March 3, 2008

First of all, thanks for the great lib. And the active development.
I'm working on a gallery module for the PostNuke CMS. Inspiration from CMS made simple Gallery and e.g. Wordpress Plugin. Both based upon phpFlickr.

Wanted to post 2 tickets, but the service is down. Temporarily?

The following 2 items I wanted to post.
1) The enableCache fs option does not check for a webserver writable cache dir. There is no feedback if the directory is not writable and caching does not work then. Something like below could help here. I've used the simple die method, see remark 2.
if (!is_writable($this->cache_dir)) {
die("Cache Directory \"$this->cache_dir\" does not have webserver write permission.");
}

2) The option die_on_error you set with the constructor is not being used throughout all methods.
The methods request, enableCache and images_upload do a die without checking the die_on_error parameter. Within a CMS the die method is rather crude. You want to list a nice error message within the framework of the CMS instead of a white screen with a Die message.
Especially for the enableCache I would like to present a good message to the user to set the right directory and permissions and so on.

Maybe even a error code return with numbers would also be a nice idea. Than people can put a Multi-Language error message on the screen dependent on the error code, instead of a hard coded english die.

A question on the caching changes. If I use anonymous login will all methods not be cached (for example albums.get) ? Can't checkout ticket 16 on the issue, since the service is down.

Edit: I see the ticket system is up again. And you filed the tickets already. Great. The new idea on caching anonymous calls (ticket 18) would be great. Most methods I will be using don't need a login.

lildude · March 3, 2008

Hi there

Thanks for your comments.

My comments are inline.

First of all, thanks for the great lib. And the active development.
I'm working on a gallery module for the PostNuke CMS. Inspiration from CMS made simple Gallery and e.g. Wordpress Plugin. Both based upon phpFlickr.

Wanted to post 2 tickets, but the service is down. Temporarily?

I've fixed trac (I really need to find an alternative as trac is about as reliable as... well, I'm sure you get the idea

).

The following 2 items I wanted to post.
1) The enableCache fs option does not check for a webserver writable cache dir. There is no feedback if the directory is not writable and caching does not work then. Something like below could help here. I've used the simple die method, see remark 2.
if (!is_writable($this->cache_dir)) {
die("Cache Directory \"$this->cache_dir\" does not have webserver write permission.");
}

Oh pooh!!! I encountered this exact issue whilst I was working on another project using my code and completely forgot to go back and add this in. Ticket #19 logged.

2) The option die_on_error you set with the constructor is not being used throughout all methods.
The methods request, enableCache and images_upload do a die without checking the die_on_error parameter. Within a CMS the die method is rather crude. You want to list a nice error message within the framework of the CMS instead of a white screen with a Die message.
Especially for the enableCache I would like to present a good message to the user to set the right directory and permissions and so on.

The die_on_error was originally only really there for the development stages (I believe the same thing was intended with phpFlickr). If you want to give prettier errors, you should find using the getErrorCode() and getErrorMsg() will give you a much nicer way of reporting errors when things go wrong.

However, they only take into account problems with interacting with the API.

Ticket #20 logged to add this functionality.

Maybe even a error code return with numbers would also be a nice idea. Than people can put a Multi-Language error message on the screen dependent on the error code, instead of a hard coded english die.

Nice idea about the internationalization too. At the moment I just rely on what the API returns (Ticket #21 logged)

A question on the caching changes. If I use anonymous login will all methods not be cached (for example albums.get) ? Can't checkout ticket 16 on the issue, since the service is down.

Yup: all methods run anonymously (ie from an anonymous login) are not cached.

Originally, I cached the SessionID as part of the request identifier in the cache (md5 hash), as phpFlickr does. But SmugMug limits the validity of this SessionID to 6 hours of inactivity. If SmugMug is not queried using this SessionID in 6 hours, it timesout the SessionID and a new one needs to be obtained. This effectively enforces a cache limit of 6 hours on all requests.

To try and avoid this limitation as much as possible, I don't include the SessionID in the cache hash. This unfortunately, has the side effect that methods run anonymously and when logged in will hash to the same value.

To get around this, I've just disabled caching of the anonymous calls.

I also now check that a login_with* has been run in the last 6 hours (as the SessionID from this is cached in the results and used for subsequent method calls) and if it hasn't, I "re-login" to renew the SessionID so the other cached entries continue to work.

As I type this, I've just thought of a way to solve this issue and allow caching of anonymous and logged in requests. I've logged ticket #18 so I don't forget.

Please feel free to add yourself to the CC list for these bugs to keep informed of their progress.

Cheers,
Colin

lildude · March 4, 2008

phpSmug 1.0.10 and 1.17 now available.
Bumping for new rev. See initial post for changes.

espaan · March 4, 2008

Oh man, you're quick

. Thanks very much.

I'm steadily progressing with my postnuke smugmug gallery.
If you're interested in a pre-release demo: check it out here.

Announcing: phpSmug - A PHP Wrapper to the SmugMug API

Comments