Skip to content

Commit 7a0ce19

Browse files
dan-coulterdan-coulter
committed
Initial import of old code.
1 parent 38ebc14 commit 7a0ce19

File tree

5 files changed

+2116
-2
lines changed

5 files changed

+2116
-2
lines changed

‎README.md

+225-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,227 @@
1-
phpflickr
1+
[phpFlickr](https://github.com/dan-coulter/phpflickr)
2+
=====================================================
3+
by [Dan Coulter](http://twitter.com/danco)
4+
5+
A PHP wrapper for the Flickr API.
6+
7+
Installation
8+
============
9+
10+
1. Copy the files from the installation package into a folder on your
11+
server. They need to be readible by your web server. You can put
12+
them into an include folder defined in your php.ini file, if you
13+
like, though it's not required.
14+
15+
2. All you have to do now is include the file in your PHP scripts and
16+
create an instance. For example:
17+
$f = new phpFlickr();
18+
19+
The constructor has three arguments:
20+
1. $api_key - This is the API key given to you by flickr.com. This
21+
argument is required and you can get an API Key at:
22+
http://www.flickr.com/services/api/key.gne
23+
24+
2. $secret - The "secret" is optional because is not required to
25+
make unauthenticated calls, but is absolutely required for the
26+
new authentication API (see Authentication section below). You
27+
will get one assigned alongside your api key.
28+
29+
3. $die_on_error - This takes a boolean value and determines
30+
whether the class will die (aka cease operation) if the API
31+
returns an error statement. It defaults to false. Every method
32+
will return false if the API returns an error. You can access
33+
error messages using the getErrorCode() and getErrorMsg()
34+
methods.
35+
36+
3. All of the API methods have been implemented in my class. You can
37+
see a full list and documentation here:
38+
http://www.flickr.com/services/api/
39+
To call a method, remove the "flickr." part of the name and replace
40+
any periods with underscores. For example, instead of
41+
flickr.photos.search, you would call $f->photos_search() or instead
42+
of flickr.photos.licenses.getInfo, you would call
43+
$f->photos_licenses_getInfo() (yes, it is case sensitive).
44+
45+
All functions have their arguments implemented in the list order on
46+
their documentation page (a link to which is included with each
47+
method in the phpFlickr clasS). The only exceptions to this are
48+
photos_search(), photos_getWithoutGeodata() and
49+
photos_getWithoutGeodata() which have so many optional arguments
50+
that it's easier for everyone if you just have to pass an
51+
associative array of arguments. See the comment in the
52+
photos_search() definition in phpFlickr.php for more information.
53+
54+
55+
Authentication
56+
==============
57+
As of this release of the phpFlickr class there is only one authentication method
58+
available to the API. This method is somewhat complex, but is far more secure and
59+
allows your users to feel a little safer authenticating to your application. You'll
60+
no longer have to ask for their username and password.
61+
62+
[Flickr Authentication API](http://www.flickr.com/services/api/auth.spec.html)
63+
64+
I know how complicated this API looks at first glance, so I've tried to
65+
make this as transparent to the coding process. I'll go through the steps
66+
you'll need to use this. Both the auth.php and getToken.php file will
67+
need your API Key and Secret entered before you can use them.
68+
69+
To have end users authenticate their accounts:
70+
1. setup a callback script. I've included a callback script that
71+
is pretty flexible. You'll find it in the package entitled "auth.php".
72+
73+
You'll need to go to flickr and point your api key to this file as the
74+
callback script. Once you've done this, on any page that you want to
75+
require the end user end user to authenticate their flickr account to
76+
your app, just call the phpFlickr::auth() function with whatever
77+
permission you need to use.
78+
79+
For example:
80+
$f->auth("write");
81+
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+
2. To authenticate the app to your account to show your private pictures (for example)
95+
96+
This method will allow you to have the app authenticate to one specific
97+
account, no matter who views your website. This is useful to display
98+
private photos or photosets (among other things).
99+
100+
*Note*: The method below is a little hard to understand, so I've setup a tool
101+
to help you through this: http://www.phpflickr.com/tools/auth/.
102+
103+
First, you'll have to setup a callback script with Flickr. Once you've
104+
done that, edit line 12 of the included getToken.php file to reflect
105+
which permissions you'll need for the app. Then browse to the page.
106+
Once you've authorized the app with Flickr, it'll send you back to that
107+
page which will give you a token which will look something like this:
108+
1234-567890abcdef1234
109+
Go to the file where you are creating an instance of phpFlickr (I suggest
110+
an include file) and after you've created it set the token to use:
111+
$f->setToken("<token string>");
112+
This token never expires, so you don't have to worry about having to
113+
login periodically.
114+
115+
116+
Caching
117+
=======
118+
119+
Caching can be very important to a project. Just a few calls to the Flickr API
120+
can take long enough to bore your average web user (depending on the calls you
121+
are making). I've built in caching that will access either a database or files
122+
in your filesystem. To enable caching, use the phpFlickr::enableCache() function.
123+
This function requires at least two arguments. The first will be the type of
124+
cache you're using (either "db" or "fs")
125+
126+
1. If you're using database caching, you'll need to supply a PEAR::DB style connection
127+
string. For example:
128+
129+
$flickr->enableCache("db", "mysql://user:password@server/database");
130+
131+
The third (optional) argument is expiration of the cache in seconds (defaults
132+
to 600). The fourth (optional) argument is the table where you want to store
133+
the cache. This defaults to flickr_cache and will attempt to create the table
134+
if it does not already exist.
135+
136+
2. If you're using filesystem caching, you'll need to supply a folder where the
137+
web server has write access. For example:
138+
139+
$flickr->enableCache("fs", "/var/www/phpFlickrCache");
140+
141+
The third (optional) argument is, the same as in the Database caching, an
142+
expiration in seconds for the cache.
143+
144+
Note: filesystem caching will probably be slower than database caching. I
145+
haven't done any tests of this, but if you get large amounts of calls, the
146+
process of cleaning out old calls may get hard on your server.
147+
148+
You may not want to allow the world to view the files that are created during
149+
caching. If you want to hide this information, either make sure that your
150+
permissions are set correctly, or disable the webserver from displaying
151+
*.cache files. In Apache, you can specify this in the configuration files
152+
or in a .htaccess file with the following directives:
153+
154+
<FilesMatch "\.cache$">
155+
Deny from all
156+
</FilesMatch>
157+
158+
Alternatively, you can specify a directory that is outside of the web server's
159+
document root.
160+
161+
Uploading
2162
=========
3163

4-
PHP Wrapper for the Flickr API
164+
Uploading is pretty simple. Aside from being authenticated (see Authentication
165+
section) the very minimum that you'll have to pass is a path to an image file on
166+
your php server. You can do either synchronous or asynchronous uploading as follows:
167+
168+
synchronous: sync_upload("photo.jpg");
169+
asynchronous: async_upload("photo.jpg");
170+
171+
The basic difference is that synchronous uploading waits around until Flickr
172+
processes the photo and returns a PhotoID. Asynchronous just uploads the
173+
picture and gets a "ticketid" that you can use to check on the status of your
174+
upload. Asynchronous is much faster, though the photoid won't be instantly
175+
available for you. You can read more about asynchronous uploading here:
176+
177+
http://www.flickr.com/services/api/upload.async.html
178+
179+
Both of the functions take the same arguments which are:
180+
181+
> Photo: The path of the file to upload.
182+
> Title: The title of the photo.
183+
> Description: A description of the photo. May contain some limited HTML.
184+
> Tags: A space-separated list of tags to apply to the photo.
185+
> is_public: Set to 0 for no, 1 for yes.
186+
> is_friend: Set to 0 for no, 1 for yes.
187+
> is_family: Set to 0 for no, 1 for yes.
188+
189+
Replacing Photos
190+
================
191+
192+
Flickr has released API support for uploading a replacement photo. To use this
193+
new method, just use the "replace" function in phpFlickr. You'll be required
194+
to pass the file name and Flickr's photo ID. You need to authenticate your script
195+
with "write" permissions before you can replace a photo. The arguments are:
196+
197+
> Photo: The path of the file to upload.
198+
> Photo ID: The numeric Flickr ID of the photo you want to replace.
199+
> Async (optional): Set to 0 for a synchronous call, 1 for asynchronous.
200+
201+
If you use the asynchronous call, it will return a ticketid instead
202+
of photoid.
203+
204+
Other Notes:
205+
1. Many of the methods have optional arguments. For these, I have implemented
206+
them in the same order that the Flickr API documentation lists them. PHP
207+
allows for optional arguments in function calls, but if you want to use the
208+
third optional argument, you have to fill in the others to the left first.
209+
You can use the "NULL" value (without quotes) in the place of an actual
210+
argument. For example:
211+
212+
$f->groups_pools_getPhotos($group_id, NULL, NULL, 10);
213+
214+
This will get the first ten photos from a specific group's pool. If you look
215+
at the documentation, you will see that there is another argument, "page". I've
216+
left it off because it appears after "per_page".
217+
218+
2. Some people will need to ues phpFlickr from behind a proxy server. I've
219+
implemented a method that will allow you to use an HTTP proxy for all of your
220+
traffic. Let's say that you have a proxy server on your local server running
221+
at port 8181. This is the code you would use:
222+
223+
$f = new phpFlickr("[api key]");
224+
$f->setProxy("localhost", "8181");
225+
226+
After that, all of your calls will be automatically made through your proxy server.
227+

‎auth.php

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<?php
2+
/* Last updated with phpFlickr 2.3.2
3+
*
4+
* Edit these variables to reflect the values you need. $default_redirect
5+
* and $permissions are only important if you are linking here instead of
6+
* using phpFlickr::auth() from another page or if you set the remember_uri
7+
* argument to false.
8+
*/
9+
$api_key = "[your api key]";
10+
$api_secret = "[your api secret]";
11+
$default_redirect = "/";
12+
$permissions = "read";
13+
$path_to_phpFlickr_class = "./";
14+
15+
ob_start();
16+
require_once($path_to_phpFlickr_class . "phpFlickr.php");
17+
@unset($_SESSION['phpFlickr_auth_token']);
18+
19+
if ( isset($_SESSION['phpFlickr_auth_redirect']) && !empty($_SESSION['phpFlickr_auth_redirect']) ) {
20+
$redirect = $_SESSION['phpFlickr_auth_redirect'];
21+
unset($_SESSION['phpFlickr_auth_redirect']);
22+
}
23+
24+
$f = new phpFlickr($api_key, $api_secret);
25+
26+
if (empty($_GET['frob'])) {
27+
$f->auth($permissions, false);
28+
} else {
29+
$f->auth_getToken($_GET['frob']);
30+
}
31+
32+
if (empty($redirect)) {
33+
header("Location: " . $default_redirect);
34+
} else {
35+
header("Location: " . $redirect);
36+
}
37+
38+
?>

‎example.php

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<?php
2+
/* Last updated with phpFlickr 1.3.2
3+
*
4+
* This example file shows you how to call the 100 most recent public
5+
* photos. It parses through them and prints out a link to each of them
6+
* along with the owner's name.
7+
*
8+
* Most of the processing time in this file comes from the 100 calls to
9+
* flickr.people.getInfo. Enabling caching will help a whole lot with
10+
* this as there are many people who post multiple photos at once.
11+
*
12+
* Obviously, you'll want to replace the "<api key>" with one provided
13+
* by Flickr: http://www.flickr.com/services/api/key.gne
14+
*/
15+
16+
require_once("phpFlickr.php");
17+
$f = new phpFlickr("<api key>");
18+
19+
$recent = $f->photos_getRecent();
20+
21+
foreach ($recent['photo'] as $photo) {
22+
$owner = $f->people_getInfo($photo['owner']);
23+
echo "<a href='http://www.flickr.com/photos/" . $photo['owner'] . "/" . $photo['id'] . "/'>";
24+
echo $photo['title'];
25+
echo "</a> Owner: ";
26+
echo "<a href='http://www.flickr.com/people/" . $photo['owner'] . "/'>";
27+
echo $owner['username'];
28+
echo "</a><br>";
29+
}
30+
?>

‎getToken.php

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<?php
2+
/* Last updated with phpFlickr 1.4
3+
*
4+
* If you need your app to always login with the same user (to see your private
5+
* photos or photosets, for example), you can use this file to login and get a
6+
* token assigned so that you can hard code the token to be used. To use this
7+
* use the phpFlickr::setToken() function whenever you create an instance of
8+
* the class.
9+
*/
10+
11+
require_once("phpFlickr.php");
12+
$f = new phpFlickr("<api key>", "<secret>");
13+
14+
//change this to the permissions you will need
15+
$f->auth("read");
16+
17+
echo "Copy this token into your code: " . $_SESSION['phpFlickr_auth_token'];
18+
19+
?>

0 commit comments

Comments
 (0)