README

由 Dan Coulter 提供

PHP 对 Flickr API 的包装。

安装

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

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

   构造函数有三个参数

   1. $api_key - 这是 flickr.com 给您的 API 密钥。此参数是必需的，您可以在以下网址获取 API 密钥：https://www.flickr.com/services/api/keys/

   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 在第一眼看起来很复杂，所以我尽量让它在编码过程中更透明。我将带您了解使用此 API 所需的步骤。在使用 auth.php 和 getToken.php 文件之前，您需要输入您的 API 密钥和密钥。

让最终用户认证他们的账户

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

   您需要前往 flickr 并将您的 api 密钥指向此文件作为回调脚本。一旦完成此操作，在您希望最终用户将 flickr 账户认证到您的应用程序的任何页面上，只需使用所需的权限调用 phpFlickr::auth() 函数即可。

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

   三种权限是“读取”、“写入”和“删除”。如果您将其留空，则函数默认为“读取”。

   调用此函数会将用户的浏览器发送到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);
   

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

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

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

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