README

由Dan Coulter

A PHP wrapper for the Flickr API.

安装

1. 将安装包中的文件复制到服务器上的一个文件夹中。它们需要被您的Web服务器读取。如果您愿意，可以将它们放入在您的php.ini文件中定义的include文件夹中，但这不是必需的。

2. 现在您只需要在PHP脚本中包含该文件并创建一个实例。例如：$f = new phpFlickr();

   构造函数有三个参数

   1. $api_key - 这是flickr.com提供的API密钥。该参数是必需的，您可以在https://www.flickr.com/services/api/keys/获取API密钥。

   2. $secret - "秘密"是可选的，因为即使不进行身份验证调用，也是必需的，但新的身份验证API（见下文身份验证部分）绝对需要。您将获得一个与API密钥一起分配的密钥。

   3. $die_on_error - 该参数接受布尔值，用于确定如果API返回错误语句，类是否将终止操作（即停止操作）。默认为false。如果API返回错误，每个方法都将返回false。您可以使用getErrorCode()和getErrorMsg()方法访问错误消息。

3. 我已经在我的类中实现了所有的API方法。您可以在以下位置查看完整的列表和文档：http://www.flickr.com/services/api/ 调用一个方法时，请删除名称中的"flickr."部分，并用下划线替换任何点。例如，而不是flickr.photos.search，您将调用$f->photos_search()，或者而不是flickr.photos.licenses.getInfo，您将调用$f->photos_licenses_getInfo()（是的，它是区分大小写的）。

   所有函数的参数都在它们文档页面的列表顺序中实现（每个方法中包含对该页面的链接）。唯一的例外是photos_search()，photos_getWithoutGeodata()和photos_getWithoutGeodata()，因为它们有如此多的可选参数，所以如果只是传递一个包含参数的关联数组，对每个人来说都更容易。有关更多信息，请参阅phpFlickr.php中photos_search()定义的注释。

身份验证

截至本版phpFlickr类，API仅有一种身份验证方法可用。这种方法相当复杂，但更安全，并允许您的用户在使用应用程序进行身份验证时感到更安全。您不再需要要求他们的用户名和密码。

Flickr身份验证API

我知道这个API初看起来很复杂，所以我已尽力使其在编码过程中尽可能透明。我将介绍您需要使用的步骤。auth.php和getToken.php文件在使用之前需要输入您的API密钥和秘密。

让最终用户验证其账户

1. 设置回调脚本。我已包括一个相当灵活的回调脚本。您可以在名为"auth.php"的包中找到它。

   您需要转到flickr，并将您的API密钥指向此文件作为回调脚本。完成此操作后，在您希望最终用户验证其flickr账户以使用您的应用程序的任何页面上，只需使用所需的权限调用phpFlickr::auth()函数。

   例如：$f->auth("write");

   有三个权限："read"、"write"和"delete"。如果为空，则函数默认为"read"。

   调用此函数将把用户的浏览器发送到Flickr页面以进行您的应用程序的认证。一旦他们登录，就会将他们弹回到您的回调脚本，然后在设置一个用于保存其认证令牌的会话变量后，将用户重定向回您从auth()函数调用的原始页面。如果该会话变量存在，则调用auth()函数将返回用户在Flickr页面上授予您的应用程序的权限，而不是重定向到外部页面。

2. 为了认证应用程序到您的账户以显示您的私人图片（例如）

   此方法将允许您让应用程序认证到特定账户，无论谁访问您的网站。这对于显示私人照片或照片集（以及其他事项）非常有用。

   注意：以下方法可能难以理解，因此我已设置了一个工具来帮助您完成此操作：http://www.phpflickr.com/tools/auth/。

   首先，您需要与Flickr设置一个回调脚本。完成后，编辑包含的getToken.php文件中的第12行，以反映应用程序所需的权限。然后浏览到该页面。一旦您使用Flickr授权了应用程序，它就会将您送回该页面，该页面将提供一个类似于以下内容的令牌：1234-567890abcdef1234 前往您创建phpFlickr实例的文件（建议使用包含文件），在创建实例后，将令牌设置为使用：$f->setToken(""); 此令牌永不失效，因此您不必担心需要定期登录。

缓存

缓存对于项目来说可能非常重要。仅仅几次调用Flickr API就可能花费足够长的时间，足以让普通网络用户感到无聊（取决于您所做的调用）。我内置了缓存，它将访问您的文件系统中的数据库或文件。要启用缓存，请使用phpFlickr::enableCache()函数。此函数至少需要两个参数。第一个将是您正在使用的缓存类型（“db”或“fs”）

1. 如果您正在使用数据库缓存，则需要提供一个PEAR::DB风格的连接字符串。例如

   $flickr->enableCache("db", "mysql://user:password@server/database");
   

   第三个（可选）参数是缓存的过期时间（以秒为单位，默认为600）。第四个（可选）参数是您想要存储缓存的数据表。默认为flickr_cache，如果它不存在，将尝试创建该表。

2. 如果您正在使用文件系统缓存，则需要提供一个文件夹，该文件夹允许Web服务器进行写入。例如

   $flickr->enableCache("fs", "/var/www/phpFlickrCache");
   

   第三个（可选）参数与数据库缓存中的相同，即缓存的过期时间（以秒为单位）。

   注意：与数据库缓存相比，文件系统缓存可能会慢一些。我尚未对此进行过测试，但如果您有大量的调用，清除旧调用的过程可能会对您的服务器造成压力。

   您可能不希望让全世界都能查看缓存过程中创建的文件。如果您想隐藏这些信息，请确保您的权限设置正确，或者禁用Web服务器显示*.cache文件。在Apache中，您可以在配置文件或通过以下指令在 .htaccess 文件中指定

   <FilesMatch "\.cache$">
       Deny from all
   </FilesMatch>
   

   或者，您可以指定一个位于Web服务器文档根之外的目录。

上传

上传非常简单。除了需要认证（见认证部分）之外，您至少需要传递的是您PHP服务器上图像文件的路径。您可以选择同步或异步上传，如下所示

synchronous:    sync_upload("photo.jpg");
asynchronous:   async_upload("photo.jpg");

基本区别在于，同步上传会等待Flickr处理照片并返回PhotoID。异步上传则直接上传图片，并获取一个“ticketid”，你可以使用它来检查上传状态。虽然照片ID不会立即可用，但异步上传要快得多。你可以在这里了解更多关于异步上传的信息。

http://www.flickr.com/services/api/upload.async.html

这两个函数接受相同的参数，包括

照片：要上传的文件的路径。
标题：照片的标题。
描述：照片的描述。可以包含一些有限的HTML。
标签：应用于照片的标签列表，以空格分隔。
is_public：设置为0表示否，设置为1表示是。
is_friend：设置为0表示否，设置为1表示是。
is_family：设置为0表示否，设置为1表示是。

替换照片

Flickr已发布API支持上传替换照片。要使用此新方法，只需在phpFlickr中使用“replace”函数。你需要使用“write”权限认证你的脚本，才能替换照片。参数包括

照片：要上传的文件的路径。
照片ID：你想替换的照片的Flickr数字ID。
Async（可选）：设置为0表示同步调用，设置为1表示异步。

如果你使用异步调用，它将返回ticketid而不是photoid。

其他注意事项

1. 许多方法都有可选参数。对于这些，我按照Flickr API文档中的顺序实现了它们。PHP允许在函数调用中使用可选参数，但如果你要使用第三个可选参数，你必须先填写左侧的其他参数。你可以在实际参数的位置使用“NULL”值（不带引号）。例如

   $f->groups_pools_getPhotos($group_id, NULL, NULL, 10);
   

   这将获取特定组池中的前十张照片。如果你查看文档，你会看到还有一个参数“page”。我将其省略，因为它在“per_page”之后。

2. 有些人需要从代理服务器后面使用phpFlickr。我实现了一个方法，允许你使用HTTP代理来处理所有流量。假设你的本地服务器上运行着一个端口号为8181的代理服务器。这是你将使用的代码

   $f = new phpFlickr("[api key]");
   $f->setProxy("localhost", "8181");
   

   之后，你所有的调用都将自动通过你的代理服务器进行。