aboutsummaryrefslogtreecommitdiff
path: root/lib/phpFlickr/README.txt
diff options
context:
space:
mode:
authorGreg Froese <greg.froese@gmail.com>2009-10-08 04:38:19 +0000
committerGreg Froese <greg.froese@gmail.com>2009-10-08 04:38:19 +0000
commit24f3f2f0d304254451c46a3b28a8e1f4678bc02f (patch)
treec95dc02130267e6c2d7053faf7546089c1c744b1 /lib/phpFlickr/README.txt
parent6b00bdba17af611726eb950fb51758556694e80f (diff)
downloadelgg-24f3f2f0d304254451c46a3b28a8e1f4678bc02f.tar.gz
elgg-24f3f2f0d304254451c46a3b28a8e1f4678bc02f.tar.bz2
flickr integration
Diffstat (limited to 'lib/phpFlickr/README.txt')
-rw-r--r--lib/phpFlickr/README.txt215
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.
+
+