README

此库实现了 Pinboard API 的客户端。所有的 XML 操作都被抽象化，以便您可以使用原生的 PHP 数组和对象进行操作。目前，所有 API v1 的功能都得到了支持。

此库需要 PHP 5 及 cURL 扩展。必须启用 SSL 支持。此库还要求 SimpleXML，这在大多数 PHP 5 安装中默认启用。

此库采用 MIT 许可证发布。作者和贡献者与 Pinboard 没有任何关联，除了作为客户。

入门指南

安装（不使用 composer）

include 'pinboard-api.php';

安装（使用 composer）

"require": {
    "kijin/pinboard-api": "dev-master"
}

引导

$pinboard = new PinboardAPI('username', 'password_or_token');

创建一个新的书签

$bookmark = new PinboardBookmark;
$bookmark->url = 'https://pinboard.in/';
$bookmark->title = 'Pinboard';
$bookmark->description = 'An awesome bookmarking service';
$bookmark->tags = array('awesome', 'bookmarking');
$bookmark->save();

查找并编辑现有的书签

$bookmarks = $pinboard->search_by_url('https://delicious.com/');
if (count($bookmarks)) {
    $bookmark = $bookmark[0];
    $bookmark->description = 'Not so tasty anymore';
    $bookmark->tags[] = 'not-awesome'
    $bookmark->save();
}

删除书签

$bookmark->delete();

获取您的标签列表

$tags = $pinboard->get_tags();
foreach ($tags as $tag) {
    echo "Tag '{$tag}' has {$tag->count} bookmarks.\n";
}

类和方法

Pinboard API 客户端在接收内容方面很宽松，但在生成内容方面很保守。时间戳和标签可以接受多种格式，通常可以用一个 URL 来代替完整的 PinboardBookmark 对象。然而，API 客户端返回的时间戳始终是 Unix 时间戳（除了在 get_dates() 的情况下，您将得到 YYYY-MM-DD 格式的日期），并且标签始终是数组中的字符串。

PinboardAPI->__construct()

参数

必需 $user : 您的 Pinboard 用户名。
必需 $pass : 您的 Pinboard 密码或 API 令牌。
可选 $connection_timeout : 连接超时时间（秒）。默认为 10。
可选 $request_timeout : 请求超时时间（秒）。默认为 30。

如果您想使用您的 API 令牌而不是账户密码，您必须使用“设置”页面中出现的完整字符串。这包括您的用户名、一个冒号字符和 20 个大写十六进制数字。

例如

$pinboard = new PinboardAPI('user', 'user:0123456789ABCDEFABCD');

您也可以传递 null 来代替您的用户名，因为令牌已经包含了您的用户名。但是，使用任何除您自己的用户名或 null 之外的值会导致认证失败。

密码认证将继续正常工作，直到 Pinboard 停止支持它。

PinboardAPI->enable_logging()

如果希望在每次 API 客户端向 Pinboard 发送远程请求时都收到通知，请使用此方法。这有助于调试。

参数

必需 $func : 一个接受一个参数的可调用函数。

可调用函数可以是函数名、方法名或闭包。每次 API 客户端向 Pinboard 发送请求时，它都会传递远程 URL。

以下示例将 https://api.pinboard.in/v1/posts/update 打印到控制台。

$pinboard = new PinboardAPI('username', 'password');
$pinboard->enable_logging(function($str) { echo "$str\n"; });
$updated_time = $pinboard->get_updated_time();

PinboardAPI->get_updated_time()

使用此方法可查找您上次更改书签的时间。这有助于减少对昂贵方法（如 get_all()）的不必要调用。

API 方法调用: posts/update

参数: 无。

返回: 整数（Unix 时间戳）。

PinboardAPI->get_recent()

使用此方法获取您最新的书签，可选地通过最多三个标签进行过滤。请注意，Pinboard 可能会对此方法实施速率限制。

API 方法调用: posts/recent

参数

可选 $count : 整数，返回的收藏夹数量。默认为15，最大为100。
可选 $tags : 1-3个标签的数组，或用空格分隔的标签字符串。

返回值：一个包含 PinboardBookmark 对象的数组。

PinboardAPI->get_all()

使用此方法获取所有收藏夹，可选地按最多三个标签或时间间隔进行过滤。注意，Pinboard可能会对此方法实施速率限制。

如果您想跳过任何参数，请用 null 代替缺少的参数。

API方法调用：posts/all

参数

可选 $count : 整数，返回的收藏夹数量。默认为全部。
可选 $offset : 整数，与$count一起使用时，跳过的收藏夹数量。
可选 $tags : 1-3个标签的数组，或用空格分隔的标签字符串。
可选 $from : Unix时间戳，或PHP可以解析成时间戳的任何字符串。
可选 $to : Unix时间戳，或PHP可以解析成时间戳的任何字符串。

返回值：一个包含 PinboardBookmark 对象的数组。

PinboardAPI->get()

使用此方法获取一些收藏夹，可选地按最多三个标签进行过滤。请阅读Pinboard的文档以了解此方法在日期参数不存在时的行为详情。

如果您想跳过任何参数，请用 null 代替缺少的参数。

API方法调用：posts/get

参数

可选 $url : 要查找的收藏夹的确切URL。
可选 $tags : 1-3个标签的数组，或用空格分隔的标签字符串。
可选 $date : Unix时间戳，PHP可以解析成时间戳的任何字符串，或格式为YYYY-MM-DD的日期。

返回值：一个包含 PinboardBookmark 对象的数组。

PinboardAPI->search_by_url()

get()的快捷方式。注意，即使只有一个收藏夹，此方法也会返回一个数组。

参数

必需 $url : 要查找的收藏夹的确切URL。

返回值：一个包含 PinboardBookmark 对象的数组。

PinboardAPI->search_by_tag()

get_all()的快捷方式。

参数

必需 $tags : 1-3个标签的数组，或用空格分隔的标签字符串。

返回值：一个包含 PinboardBookmark 对象的数组。

PinboardAPI->search_by_date()

get()的快捷方式。

参数

必需 $date : Unix时间戳，PHP可以解析成时间戳的任何字符串，或格式为YYYY-MM-DD的日期。

返回值：一个包含 PinboardBookmark 对象的数组。

PinboardAPI->search_by_interval()

get_all()的快捷方式。

参数

必需 $from : Unix时间戳，或PHP可以解析成时间戳的任何字符串。
必需 $to : Unix时间戳，或PHP可以解析成时间戳的任何字符串。

返回值：一个包含 PinboardBookmark 对象的数组。

PinboardAPI->save()

使用此方法添加新的收藏夹或编辑现有的收藏夹。

API方法调用：posts/add

参数

必需 $bookmark : 要保存的PinboardBookmark对象。
可选 $replace : 如果您不想用相同的URL覆盖现有的收藏夹，请将其设置为false。默认为true。

返回值：成功时返回true，失败时返回false。在失败的情况下，调用get_last_status()以读取错误信息。

在不使用$replace的情况下，可能更直观地使用PinboardBookmark->save()。以下将提供更多关于使用此替代语法的详细信息。

PinboardAPI->delete()

使用此方法删除收藏夹。

API方法调用：posts/delete

参数

必需 $bookmark : PinboardBookmark对象，或URL。

返回值：成功时返回true，失败时返回false。在失败的情况下，调用get_last_status()以读取错误信息。

请注意，使用PinboardBookmark->delete()可能更直观。以下将提供更多关于使用此替代语法的详细信息。

PinboardAPI->get_dates()

使用此方法获取您添加收藏夹的日期列表，以及每天添加的收藏夹数量。可选地按最多三个标签进行过滤。

API方法调用：posts/dates

参数

可选 $tags : 1-3个标签的数组，或用空格分隔的标签字符串。

返回值：一个包含PinboardDate对象的数组。（这些对象的行为类似于字符串。）

PinboardAPI->get_suggested_tags()

使用此方法获取书签或URL的标签建议。

API 方法调用: posts/suggest

参数

必需 $bookmark : PinboardBookmark对象，或URL。

返回: 包含两个键的关联数组，分别是 popular 和 recommended，每个键都包含一个字符串数组。

PinboardAPI->get_tags()

使用此方法获取所有标签的列表，以及每个标签的书签数量。

API 方法调用: tags/get

参数: 无。

返回: PinboardTag 对象的数组。（这些对象的行为像字符串。）

PinboardAPI->rename_tag()

使用此方法将一个标签重命名为另一个。

API 方法调用: tags/rename

参数

必需 $old : 作为字符串的旧名称。
必需 $new : 作为字符串的新名称。

返回值：成功时返回true，失败时返回false。在失败的情况下，调用get_last_status()以读取错误信息。

PinboardAPI->delete_tag()

使用此方法删除一个标签。书签不会被删除。

API 方法调用: tags/delete

参数

必需 $tag : 要删除的标签，作为字符串。

返回值：成功时返回true，失败时返回false。在失败的情况下，调用get_last_status()以读取错误信息。

PinbiardAPI->list_notes()

使用此方法列出您的笔记。

API 方法调用: notes/list

参数: 无。

返回: PinboardNote 对象的数组。

截至2014年8月，此API调用仅返回元数据。为了获取每条笔记的内容，请使用 get_note()。

PinboardAPI->get_note()

使用此方法获取单个笔记的内容。

API 方法调用: notes/ID

参数

必需 $id : 您想获取的笔记的ID。

返回: PinboardNote 对象，或如果笔记不存在，返回 false。

截至2014年8月，此API调用返回标题、内容和最小元数据。为了获取其余的元数据，请使用 list_notes()。

PinboardAPI->get_rss_token()

使用此方法获取您的秘密RSS令牌。

API 方法调用: user/secret

参数: 无。

返回: 包含您的RSS令牌的字符串。

PinboardAPI->get_api_token()

使用此方法获取您的API令牌。

API 方法调用: user/api_token

参数: 无。

返回: 包含您的API令牌的字符串。

请注意，此方法仅返回API令牌的十六进制部分。为了使用令牌进行身份验证，您必须将其与用户名结合使用。有关如何使用令牌进行身份验证的更多信息，请参阅 __construct() 文档。

PinboardAPI->get_last_status()

使用此方法检索以下方法之一的任何错误消息：save()、delete()、rename_tag() 和 delete_tag()。如果最后操作没有失败，此方法将返回 "done"。如果没有执行任何适用操作，此方法将返回 null。

参数: 无。

返回: 包含最后错误消息的字符串，或 null。

PinboardAPI->dump()

使用此方法备份所有您的书签。备份将以XML格式生成，可以轻松导入到Pinboard、Delicious或其他支持导入Delicious格式的在线书签服务。请注意，Pinboard可能对此方法施加速率限制。

API方法调用：posts/all

参数: 无。

返回: 包含XML备份的字符串。

PinboardBookmark类

此类与 save() 以及其他接受书签作为参数的几个方法一起使用。在调用 save() 时，必须使用此类，但在大多数其他情况下，可以使用URL替代。API客户端在从Pinboard获取书签时也会返回此类实例。

以下属性可以自由调整

必需 url : 书签的URL。
必需 title : 书签的标题。
可选 description : 任何附加描述。
可选 timestamp : Unix时间戳，或PHP可以解析成时间戳的任何字符串。
可选标签：1-3个标签的数组，或用空格分隔的标签字符串。
可选 is_public：值为true或false。默认值由您的Pinboard账户设置决定。
可选 is_unread：值为true或false。默认值是false。

以下属性也是公开的，但在您调用save()时不会保存。

hash：URL的MD5哈希值，Pinboard用它来唯一标识书签。
meta：另一个哈希值，可以用来检测书签是否被更改。
others：其他有多少Pinboard用户保存了相同的URL。

以下方法可用

save()：保存此书签。
delete()：删除此书签。

您可以使用这些方法代替PinboardAPI->save($bookmark)和PinboardAPI->delete($bookmark)来保存或删除单个书签。这可能对习惯于通用ORM语法的开发者来说更直观，该库试图模仿这种语法。

例如，而不是

$pinboard->save($bookmark);

您可以简单地做

$bookmark->save();

如果当前脚本中只存在一个PinboardAPI实例（通常情况下是这样的），API客户端会自动使用它来保存或删除所有书签，甚至新创建的书签。因此，无需显式地使PinboardBookmark实例与PinboardAPI实例交互。

但是，如果您使用不同的登录凭证创建了多个PinboardAPI实例（可能是因为您想从一个Pinboard账户复制或移动书签到另一个账户），这些方法将抛出PinboardException，因为它们不知道使用哪个实例。在这种情况下，您应该使用PinboardAPI实例上的等效方法，或者将适当的PinboardAPI实例作为参数传递给save()和delete()。这两个方法都接受一个可选参数，该参数应该是PinboardAPI实例。

以下示例展示了如何从一个Pinboard账户复制书签到另一个账户

$pinboard1 = new PinboardAPI('user1', 'pass1');
$pinboard2 = new PinboardAPI('user2', 'pass2');
$bookmarks = $pinboard1->search_by_tag('tag');
foreach ($bookmarks as $bookmark) {
    $bookmark->save($pinboard2);  // Equivalent to $pinboard2->save($bookmark);
    sleep(3);  // Comply with Pinboard's rate limiting policy
}

即使使用多个实例，使用get_*或search_*方法检索到的书签也会记住它们来自哪个实例，因此save()和delete()将正常工作，如下例所示

$pinboard1 = new PinboardAPI('user1', 'pass1');
$pinboard2 = new PinboardAPI('user2', 'pass2');
$bookmarks = $pinboard1->search_by_url('http://awesome-website.com/');
$bookmark = $bookmarks[0];
$bookmark->description = 'New description';
$bookmark->save();  // Automatically saved to $pinboard1

PinboardDate类

此类的实例由get_dates()返回。它们包含格式为YYYY-MM-DD的日期。在所有目的上，这些对象可以像字符串一样使用。唯一的区别是，它有一个count属性，包含对应日期添加的书签数量。

示例

echo $date;         // prints '2012-03-20'
echo $date->date;   // prints '2012-03-20'
echo $date->count;  // prints '16'

PinboardTag类

此类的实例由get_tags()返回。在所有目的上，这些对象可以像字符串一样使用。唯一的区别是，它有一个count属性，包含对应日期添加的书签数量。

为了节省资源，此类不用于其他上下文，例如PinboardBookmark对象的tags属性、get_suggested_tags()的输出或其他任何计数不相关的场合。

示例

echo $tag;         // prints 'awesome'
echo $tag->tag;    // prints 'awesome'
echo $tag->count;  // prints '42'

PinboardNote类

此类的实例由list_notes()和get_note()返回。目前，无法通过API将笔记保存到Pinboard。

由于不同的API调用返回不同子集的内容和元数据，以下所有属性可能不一定都填充。唯一保证填充的属性是id。未填充的属性将具有null的值。有关上述方法的更多详细信息，请参阅文档。

以下属性可用

id
title
hash
created_at
更新时间
长度
文本

错误处理

Pinboard API 客户端定义了以下异常

PinboardException（继承自Exception）在所有其他异常未覆盖的错误情况下抛出，例如尝试保存一个无效URL或空标题的书签。
PinboardException_ConnectionError（继承自PinboardException）如果在连接到Pinboard的服务器时库遇到问题，则会抛出。这很可能是由于某种形式的故障。
PinboardException_AuthenticationFailure（继承自PinboardException）在认证失败的情况下抛出。这可能是由于用户名和密码/令牌不匹配，或者您以错误的格式提供了API令牌。（API令牌必须包括用户名，而不仅仅是十六进制部分。）
PinboardException_TooManyRequests（继承自PinboardException）如果服务器响应HTTP代码429，“请求过多”，则会抛出。这意味着您应该放慢速度，等待几分钟，然后再进行额外的get()或get_all()调用。有关速率限制的更多信息，请参阅此处和此处。
PinboardException_InvalidResponse（继承自PinboardException）如果服务器响应除200和429之外的任何HTTP代码，或者如果它返回无效的XML，则会抛出。

请注意，某些方法在失败时将返回false而不是抛出异常。这是因为作者认为这些情况下的错误不是“异常”。（例如，尝试删除已经删除的书签是无害的。）所有这些情况都在上面有明确的文档说明。

kijin / pinboard-api

维护者

详细信息

README

入门指南

类和方法

PinboardAPI->__construct()

PinboardAPI->enable_logging()

PinboardAPI->get_updated_time()

PinboardAPI->get_recent()

PinboardAPI->get_all()

PinboardAPI->get()

PinboardAPI->search_by_url()

PinboardAPI->search_by_tag()

PinboardAPI->search_by_date()

PinboardAPI->search_by_interval()

PinboardAPI->save()

PinboardAPI->delete()

PinboardAPI->get_dates()

PinboardAPI->get_suggested_tags()

PinboardAPI->get_tags()

PinboardAPI->rename_tag()

PinboardAPI->delete_tag()

PinbiardAPI->list_notes()

PinboardAPI->get_note()

PinboardAPI->get_rss_token()

PinboardAPI->get_api_token()

PinboardAPI->get_last_status()

PinboardAPI->dump()

PinboardBookmark类

PinboardDate类

PinboardTag类

PinboardNote类

错误处理