flickr integration

1 files changed, 215 insertions, 0 deletions

diff --git a/lib/phpFlickr/README.txt b/lib/phpFlickr/README.txt
new file mode 100644
index 000000000..df0a56d98
--- /dev/null
+++ b/lib/phpFlickr/README.txt
@@ -0,0 +1,215 @@
+phpFlickr Class 2.3.1
+Written by Dan Coulter (dancoulter@users.sourceforge.net)
+Project Homepage: http://www.phpflickr.com/
+Google Code Project Page: http://code.google.com/p/phpflickr/
+Released under GNU Lesser General Public License (http://www.gnu.org/copyleft/lgpl.html)
+For more information about the class and upcoming tools and applications using it,
+visit http://www.phpflickr.com/ or http://code.google.com/p/phpflickr/
+
+If you are interested in hiring me for a project (involving phpFlickr
+or not), feel free to email me.
+
+Installation instructions:
+1.  Copy the files from the installation package into a folder on your
+    server.  They need to be readible by your web server.  You can put 
+    them into an include folder defined in your php.ini file, if you 
+    like, though it's not required. 
+    
+2.  All you have to do now is include the file in your PHP scripts and 
+    create an instance.  For example:
+    $f = new phpFlickr();
+
+    The constructor has three arguments:
+    A.  $api_key - This is the API key given to you by flickr.com. This 
+        argument is required and you can get an API Key at:
+        http://www.flickr.com/services/api/key.gne
+        
+    B.  $secret - The "secret" is optional because is not required to 
+        make unauthenticated calls, but is absolutely required for the 
+        new authentication API (see Authentication section below).  You 
+        will get one assigned alongside your api key.
+    
+    C.  $die_on_error - This takes a boolean value and determines 
+        whether the class will die (aka cease operation) if the API 
+        returns an error statement.  It defaults to false.  Every method 
+        will return false if the API returns an error.  You can access 
+        error messages using the getErrorCode() and getErrorMsg() 
+        methods.
+        
+3.  All of the API methods have been implemented in my class.  You can 
+    see a full list and documentation here: 
+        http://www.flickr.com/services/api/
+    To call a method, remove the "flickr." part of the name and replace 
+    any periods with underscores. For example, instead of 
+    flickr.photos.search, you would call $f->photos_search() or instead 
+    of flickr.photos.licenses.getInfo, you would call 
+    $f->photos_licenses_getInfo() (yes, it is case sensitive).
+    
+    All functions have their arguments implemented in the list order on 
+    their documentation page (a link to which is included with each 
+    method in the phpFlickr clasS). The only exceptions to this are 
+    photos_search(), photos_getWithoutGeodata() and 
+    photos_getWithoutGeodata() which have so many optional arguments
+    that it's easier for everyone if you just have to pass an 
+    associative array of arguments.  See the comment in the 
+    photos_search() definition in phpFlickr.php for more information.
+    
+
+    
+Authentication:
+    As of this release of the phpFlickr class there is only one authentication method
+    available to the API.  This method is somewhat complex, but is far more secure and
+    allows your users to feel a little safer authenticating to your application.  You'll
+    no longer have to ask for their username and password.
+    
+    Authentication API - http://www.flickr.com/services/api/auth.spec.html
+        
+        I know how complicated this API looks at first glance, so I've tried to
+        make this as transparent to the coding process.  I'll go through the steps
+        you'll need to use this.  Both the auth.php and getToken.php file will
+        need your API Key and Secret entered before you can use them.
+        
+        To have end users authenticate their accounts:
+            First, setup a callback script.  I've included a callback script that 
+            is pretty flexible.  You'll find it in the package entitled "auth.php".  
+            You'll need to go to flickr and point your api key to this file as the 
+            callback script.  Once you've done this, on any page that you want to 
+            require the end user end user to authenticate their flickr account to 
+            your app, just call the phpFlickr::auth() function with whatever 
+            permission you need to use.
+            For example:
+                $f->auth("write");
+            The three permissions are "read", "write" and "delete".  The function
+            defaults to "read", if you leave it blank.  
+            
+            Calling this function will send the user's browser to Flickr's page to 
+            authenticate to your app.  Once they have logged in, it will bounce
+            them back to your callback script which will redirect back to the
+            original page that you called the auth() function from after setting
+            a session variable to save their authentication token.  If that session
+            variable exists, calling the auth() function will return the permissions
+            that the user granted your app on the Flickr page instead of redirecting
+            to an external page.
+        
+        To authenticate the app to your account to show your private pictures (for example)
+            This method will allow you to have the app authenticate to one specific
+            account, no matter who views your website.  This is useful to display
+            private photos or photosets (among other things).
+            
+            *Note*: The method below is a little hard to understand, so I've setup a tool
+            to help you through this: http://www.phpflickr.com/tools/auth/.
+                        
+            First, you'll have to setup a callback script with Flickr.  Once you've
+            done that, edit line 12 of the included getToken.php file to reflect 
+            which permissions you'll need for the app.  Then browse to the page.
+            Once you've authorized the app with Flickr, it'll send you back to that
+            page which will give you a token which will look something like this:
+                1234-567890abcdef1234
+            Go to the file where you are creating an instance of phpFlickr (I suggest
+            an include file) and after you've created it set the token to use:
+                $f->setToken("<token string>");
+            This token never expires, so you don't have to worry about having to
+            login periodically.
+            
+
+Using Caching:
+    Caching can be very important to a project.  Just a few calls to the Flickr API
+    can take long enough to bore your average web user (depending on the calls you
+    are making).  I've built in caching that will access either a database or files
+    in your filesystem.  To enable caching, use the phpFlickr::enableCache() function.
+    This function requires at least two arguments. The first will be the type of
+    cache you're using (either "db" or "fs")
+    
+    1.  If you're using database caching, you'll need to supply a PEAR::DB connection
+        string. For example: 
+        $flickr->enableCache("db", "mysql://user:password@server/database");
+        The third (optional) argument is expiration of the cache in seconds (defaults 
+        to 600).  The fourth (optional) argument is the table where you want to store
+        the cache.  This defaults to flickr_cache and will attempt to create the table
+        if it does not already exist.
+    
+    2.  If you're using filesystem caching, you'll need to supply a folder where the
+        web server has write access. For example: 
+        $flickr->enableCache("fs", "/var/www/phpFlickrCache");
+        The third (optional) argument is, the same as in the Database caching, an
+        expiration in seconds for the cache.
+        Note: filesystem caching will probably be slower than database caching. I
+        haven't done any tests of this, but if you get large amounts of calls, the
+        process of cleaning out old calls may get hard on your server.
+        
+        You may not want to allow the world to view the files that are created during
+        caching.  If you want to hide this information, either make sure that your
+        permissions are set correctly, or disable the webserver from displaying 
+        *.cache files.  In Apache, you can specify this in the configuration files
+        or in a .htaccess file with the following directives:
+        
+        <FilesMatch "\.cache$">
+            Deny from all
+        </FilesMatch>
+        
+        Alternatively, you can specify a directory that is outside of the web server's
+        document root.
+        
+Uploading
+    Uploading is pretty simple. Aside from being authenticated (see Authentication 
+    section) the very minimum that you'll have to pass is a path to an image file on 
+    your php server. You can do either synchronous or asynchronous uploading as follows:
+        synchronous:    sync_upload("photo.jpg");
+        asynchronous:   async_upload("photo.jpg");
+    
+    The basic difference is that synchronous uploading waits around until Flickr
+    processes the photo and returns a PhotoID.  Asynchronous just uploads the
+    picture and gets a "ticketid" that you can use to check on the status of your 
+    upload. Asynchronous is much faster, though the photoid won't be instantly
+    available for you. You can read more about asynchronous uploading here:
+        http://www.flickr.com/services/api/upload.async.html
+        
+    Both of the functions take the same arguments which are:
+        Photo: The path of the file to upload.
+        Title: The title of the photo.
+        Description: A description of the photo. May contain some limited HTML.
+        Tags: A space-separated list of tags to apply to the photo.
+        is_public: Set to 0 for no, 1 for yes.
+        is_friend: Set to 0 for no, 1 for yes.
+        is_family: Set to 0 for no, 1 for yes.
+        
+Replacing Photos
+    Flickr has released API support for uploading a replacement photo.  To use this
+    new method, just use the "replace" function in phpFlickr.  You'll be required
+    to pass the file name and Flickr's photo ID.  You need to authenticate your script
+    with "write" permissions before you can replace a photo.  The arguments are:
+        Photo: The path of the file to upload.
+        Photo ID: The numeric Flickr ID of the photo you want to replace.
+        Async (optional): Set to 0 for a synchronous call, 1 for asynchronous.
+    If you use the asynchronous call, it will return a ticketid instead
+    of photoid.
+
+Other Notes:
+    1.  Many of the methods have optional arguments.  For these, I have implemented 
+        them in the same order that the Flickr API documentation lists them. PHP
+        allows for optional arguments in function calls, but if you want to use the
+        third optional argument, you have to fill in the others to the left first.
+        You can use the "NULL" value (without quotes) in the place of an actual
+        argument.  For example:
+        $f->groups_pools_getPhotos($group_id, NULL, NULL, 10);
+        This will get the first ten photos from a specific group's pool.  If you look
+        at the documentation, you will see that there is another argument, "page". I've
+        left it off because it appears after "per_page".
+    2.  Some people will need to ues phpFlickr from behind a proxy server.  I've
+        implemented a method that will allow you to use an HTTP proxy for all of your
+        traffic.  Let's say that you have a proxy server on your local server running
+        at port 8181.  This is the code you would use:
+            $f = new phpFlickr("[api key]");
+            $f->setProxy("localhost", "8181");
+        After that, all of your calls will be automatically made through your proxy server.
+            
+
+That's it! Enjoy the class.  Check out the project page (listed above) for updates
+and news.  I plan to implement file uploads and functions to aggregate data from
+several different methods for easier use in a web application.  Thanks for your
+interest in this project!
+
+    Please email me if you have any questions or problems. You'll find my email
+	at the top of this file.
+
+