1 | phpFlickr Class 3.0 |
---|
2 | Written by Dan Coulter (dancoulter@users.sourceforge.net) |
---|
3 | Project Homepage: http://www.phpflickr.com/ |
---|
4 | Google Code Project Page: http://code.google.com/p/phpflickr/ |
---|
5 | Released under GNU Lesser General Public License (http://www.gnu.org/copyleft/lgpl.html) |
---|
6 | For more information about the class and upcoming tools and applications using it, |
---|
7 | visit http://www.phpflickr.com/ or http://code.google.com/p/phpflickr/ |
---|
8 | |
---|
9 | If you are interested in hiring me for a project (involving phpFlickr |
---|
10 | or not), feel free to email me. |
---|
11 | |
---|
12 | Installation instructions: |
---|
13 | 1. Copy the files from the installation package into a folder on your |
---|
14 | server. They need to be readible by your web server. You can put |
---|
15 | them into an include folder defined in your php.ini file, if you |
---|
16 | like, though it's not required. |
---|
17 | |
---|
18 | 2. All you have to do now is include the file in your PHP scripts and |
---|
19 | create an instance. For example: |
---|
20 | $f = new phpFlickr(); |
---|
21 | |
---|
22 | The constructor has three arguments: |
---|
23 | A. $api_key - This is the API key given to you by flickr.com. This |
---|
24 | argument is required and you can get an API Key at: |
---|
25 | http://www.flickr.com/services/api/key.gne |
---|
26 | |
---|
27 | B. $secret - The "secret" is optional because is not required to |
---|
28 | make unauthenticated calls, but is absolutely required for the |
---|
29 | new authentication API (see Authentication section below). You |
---|
30 | will get one assigned alongside your api key. |
---|
31 | |
---|
32 | C. $die_on_error - This takes a boolean value and determines |
---|
33 | whether the class will die (aka cease operation) if the API |
---|
34 | returns an error statement. It defaults to false. Every method |
---|
35 | will return false if the API returns an error. You can access |
---|
36 | error messages using the getErrorCode() and getErrorMsg() |
---|
37 | methods. |
---|
38 | |
---|
39 | 3. All of the API methods have been implemented in my class. You can |
---|
40 | see a full list and documentation here: |
---|
41 | http://www.flickr.com/services/api/ |
---|
42 | To call a method, remove the "flickr." part of the name and replace |
---|
43 | any periods with underscores. For example, instead of |
---|
44 | flickr.photos.search, you would call $f->photos_search() or instead |
---|
45 | of flickr.photos.licenses.getInfo, you would call |
---|
46 | $f->photos_licenses_getInfo() (yes, it is case sensitive). |
---|
47 | |
---|
48 | All functions have their arguments implemented in the list order on |
---|
49 | their documentation page (a link to which is included with each |
---|
50 | method in the phpFlickr clasS). The only exceptions to this are |
---|
51 | photos_search(), photos_getWithoutGeodata() and |
---|
52 | photos_getWithoutGeodata() which have so many optional arguments |
---|
53 | that it's easier for everyone if you just have to pass an |
---|
54 | associative array of arguments. See the comment in the |
---|
55 | photos_search() definition in phpFlickr.php for more information. |
---|
56 | |
---|
57 | |
---|
58 | |
---|
59 | Authentication: |
---|
60 | As of this release of the phpFlickr class there is only one authentication method |
---|
61 | available to the API. This method is somewhat complex, but is far more secure and |
---|
62 | allows your users to feel a little safer authenticating to your application. You'll |
---|
63 | no longer have to ask for their username and password. |
---|
64 | |
---|
65 | Authentication API - http://www.flickr.com/services/api/auth.spec.html |
---|
66 | |
---|
67 | I know how complicated this API looks at first glance, so I've tried to |
---|
68 | make this as transparent to the coding process. I'll go through the steps |
---|
69 | you'll need to use this. Both the auth.php and getToken.php file will |
---|
70 | need your API Key and Secret entered before you can use them. |
---|
71 | |
---|
72 | To have end users authenticate their accounts: |
---|
73 | First, setup a callback script. I've included a callback script that |
---|
74 | is pretty flexible. You'll find it in the package entitled "auth.php". |
---|
75 | You'll need to go to flickr and point your api key to this file as the |
---|
76 | callback script. Once you've done this, on any page that you want to |
---|
77 | require the end user end user to authenticate their flickr account to |
---|
78 | your app, just call the phpFlickr::auth() function with whatever |
---|
79 | permission you need to use. |
---|
80 | For example: |
---|
81 | $f->auth("write"); |
---|
82 | The three permissions are "read", "write" and "delete". The function |
---|
83 | defaults to "read", if you leave it blank. |
---|
84 | |
---|
85 | Calling this function will send the user's browser to Flickr's page to |
---|
86 | authenticate to your app. Once they have logged in, it will bounce |
---|
87 | them back to your callback script which will redirect back to the |
---|
88 | original page that you called the auth() function from after setting |
---|
89 | a session variable to save their authentication token. If that session |
---|
90 | variable exists, calling the auth() function will return the permissions |
---|
91 | that the user granted your app on the Flickr page instead of redirecting |
---|
92 | to an external page. |
---|
93 | |
---|
94 | To authenticate the app to your account to show your private pictures (for example) |
---|
95 | This method will allow you to have the app authenticate to one specific |
---|
96 | account, no matter who views your website. This is useful to display |
---|
97 | private photos or photosets (among other things). |
---|
98 | |
---|
99 | *Note*: The method below is a little hard to understand, so I've setup a tool |
---|
100 | to help you through this: http://www.phpflickr.com/tools/auth/. |
---|
101 | |
---|
102 | First, you'll have to setup a callback script with Flickr. Once you've |
---|
103 | done that, edit line 12 of the included getToken.php file to reflect |
---|
104 | which permissions you'll need for the app. Then browse to the page. |
---|
105 | Once you've authorized the app with Flickr, it'll send you back to that |
---|
106 | page which will give you a token which will look something like this: |
---|
107 | 1234-567890abcdef1234 |
---|
108 | Go to the file where you are creating an instance of phpFlickr (I suggest |
---|
109 | an include file) and after you've created it set the token to use: |
---|
110 | $f->setToken("<token string>"); |
---|
111 | This token never expires, so you don't have to worry about having to |
---|
112 | login periodically. |
---|
113 | |
---|
114 | |
---|
115 | Using Caching: |
---|
116 | Caching can be very important to a project. Just a few calls to the Flickr API |
---|
117 | can take long enough to bore your average web user (depending on the calls you |
---|
118 | are making). I've built in caching that will access either a database or files |
---|
119 | in your filesystem. To enable caching, use the phpFlickr::enableCache() function. |
---|
120 | This function requires at least two arguments. The first will be the type of |
---|
121 | cache you're using (either "db" or "fs") |
---|
122 | |
---|
123 | 1. If you're using database caching, you'll need to supply a PEAR::DB connection |
---|
124 | string. For example: |
---|
125 | $flickr->enableCache("db", "mysql://user:password@server/database"); |
---|
126 | The third (optional) argument is expiration of the cache in seconds (defaults |
---|
127 | to 600). The fourth (optional) argument is the table where you want to store |
---|
128 | the cache. This defaults to flickr_cache and will attempt to create the table |
---|
129 | if it does not already exist. |
---|
130 | |
---|
131 | 2. If you're using filesystem caching, you'll need to supply a folder where the |
---|
132 | web server has write access. For example: |
---|
133 | $flickr->enableCache("fs", "/var/www/phpFlickrCache"); |
---|
134 | The third (optional) argument is, the same as in the Database caching, an |
---|
135 | expiration in seconds for the cache. |
---|
136 | Note: filesystem caching will probably be slower than database caching. I |
---|
137 | haven't done any tests of this, but if you get large amounts of calls, the |
---|
138 | process of cleaning out old calls may get hard on your server. |
---|
139 | |
---|
140 | You may not want to allow the world to view the files that are created during |
---|
141 | caching. If you want to hide this information, either make sure that your |
---|
142 | permissions are set correctly, or disable the webserver from displaying |
---|
143 | *.cache files. In Apache, you can specify this in the configuration files |
---|
144 | or in a .htaccess file with the following directives: |
---|
145 | |
---|
146 | <FilesMatch "\.cache$"> |
---|
147 | Deny from all |
---|
148 | </FilesMatch> |
---|
149 | |
---|
150 | Alternatively, you can specify a directory that is outside of the web server's |
---|
151 | document root. |
---|
152 | |
---|
153 | Uploading |
---|
154 | Uploading is pretty simple. Aside from being authenticated (see Authentication |
---|
155 | section) the very minimum that you'll have to pass is a path to an image file on |
---|
156 | your php server. You can do either synchronous or asynchronous uploading as follows: |
---|
157 | synchronous: sync_upload("photo.jpg"); |
---|
158 | asynchronous: async_upload("photo.jpg"); |
---|
159 | |
---|
160 | The basic difference is that synchronous uploading waits around until Flickr |
---|
161 | processes the photo and returns a PhotoID. Asynchronous just uploads the |
---|
162 | picture and gets a "ticketid" that you can use to check on the status of your |
---|
163 | upload. Asynchronous is much faster, though the photoid won't be instantly |
---|
164 | available for you. You can read more about asynchronous uploading here: |
---|
165 | http://www.flickr.com/services/api/upload.async.html |
---|
166 | |
---|
167 | Both of the functions take the same arguments which are: |
---|
168 | Photo: The path of the file to upload. |
---|
169 | Title: The title of the photo. |
---|
170 | Description: A description of the photo. May contain some limited HTML. |
---|
171 | Tags: A space-separated list of tags to apply to the photo. |
---|
172 | is_public: Set to 0 for no, 1 for yes. |
---|
173 | is_friend: Set to 0 for no, 1 for yes. |
---|
174 | is_family: Set to 0 for no, 1 for yes. |
---|
175 | |
---|
176 | Replacing Photos |
---|
177 | Flickr has released API support for uploading a replacement photo. To use this |
---|
178 | new method, just use the "replace" function in phpFlickr. You'll be required |
---|
179 | to pass the file name and Flickr's photo ID. You need to authenticate your script |
---|
180 | with "write" permissions before you can replace a photo. The arguments are: |
---|
181 | Photo: The path of the file to upload. |
---|
182 | Photo ID: The numeric Flickr ID of the photo you want to replace. |
---|
183 | Async (optional): Set to 0 for a synchronous call, 1 for asynchronous. |
---|
184 | If you use the asynchronous call, it will return a ticketid instead |
---|
185 | of photoid. |
---|
186 | |
---|
187 | Other Notes: |
---|
188 | 1. Many of the methods have optional arguments. For these, I have implemented |
---|
189 | them in the same order that the Flickr API documentation lists them. PHP |
---|
190 | allows for optional arguments in function calls, but if you want to use the |
---|
191 | third optional argument, you have to fill in the others to the left first. |
---|
192 | You can use the "NULL" value (without quotes) in the place of an actual |
---|
193 | argument. For example: |
---|
194 | $f->groups_pools_getPhotos($group_id, NULL, NULL, 10); |
---|
195 | This will get the first ten photos from a specific group's pool. If you look |
---|
196 | at the documentation, you will see that there is another argument, "page". I've |
---|
197 | left it off because it appears after "per_page". |
---|
198 | 2. Some people will need to ues phpFlickr from behind a proxy server. I've |
---|
199 | implemented a method that will allow you to use an HTTP proxy for all of your |
---|
200 | traffic. Let's say that you have a proxy server on your local server running |
---|
201 | at port 8181. This is the code you would use: |
---|
202 | $f = new phpFlickr("[api key]"); |
---|
203 | $f->setProxy("localhost", "8181"); |
---|
204 | After that, all of your calls will be automatically made through your proxy server. |
---|
205 | |
---|
206 | |
---|
207 | That's it! Enjoy the class. Check out the project page (listed above) for updates |
---|
208 | and news. I plan to implement file uploads and functions to aggregate data from |
---|
209 | several different methods for easier use in a web application. Thanks for your |
---|
210 | interest in this project! |
---|
211 | |
---|
212 | Please email me if you have any questions or problems. You'll find my email |
---|
213 | at the top of this file. |
---|
214 | |
---|
215 | |
---|