diff options
Diffstat (limited to 'lib/phpFlickr/README.txt')
| -rw-r--r-- | lib/phpFlickr/README.txt | 215 |
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. + + |