README

PHP 官方 Pinterest API 包装器。

需求

• PHP 5.4 或更高版本（已积极测试于 PHP >=7.1）
• cURL
• 已注册 Pinterest 应用

开始使用

要使用 Pinterest API，您必须注册为开发者并 创建 一个应用程序。创建应用程序后，您将收到一个 app_id 和 app_secret。

在这种情况下，术语 client_id 和 client_secret 是 app_id 和 app_secret。

安装

Pinterest API 包装器可在 Composer 上找到。

composer require dirkgroenen/pinterest-api-php

如果您没有使用 Composer（您应该开始使用，除非您有充分的理由不这样做）您可以将 autoload.php 文件包含在您的项目中。

简单示例

use DirkGroenen\Pinterest\Pinterest;

$pinterest = new Pinterest(CLIENT_ID, CLIENT_SECRET);

初始化类后，您可以获取登录 URL

$loginurl = $pinterest->auth->getLoginUrl(CALLBACK_URL, array('read_public'));
echo '<a href=' . $loginurl . '>Authorize Pinterest</a>';

查看 Pinterest 文档 了解可用的作用域。

用户使用登录链接进行授权后，将被发送回给定的 CALLBACK_URL。URL 将包含 code，可以将其交换为 access_token。要交换代码为 access_token 并设置它，可以使用以下代码

if(isset($_GET["code"])){
    $token = $pinterest->auth->getOAuthToken($_GET["code"]);
    $pinterest->auth->setOAuthToken($token->access_token);
}

获取用户的配置文件

要获取当前登录用户的配置文件，您可以使用 Users::me(<array>); 方法。

$me = $pinterest->users->me();
echo $me;

模型

API 包装器将通过其对应模型解析所有数据。这导致可以直接（例如）将模型 echo 到 JSON 字符串中。

模型还显示了可用的字段（这些字段也在 Pinterest 文档中进行了描述）。默认情况下，不会返回所有字段，因此这可以帮助您在请求中提供额外字段时使用。

可用的模型

用户

推文

板

兴趣

• id
• 名称

检索额外字段

如果您需要更多字段，可以在 $data（GET 请求）或 $fields（PATCH 请求）数组中指定这些字段。示例

$pinterest->users->me();

响应

{
    "id": "503066358284560467",
    "username": null,
    "first_name": "Dirk ",
    "last_name": "Groenen",
    "bio": null,
    "created_at": null,
    "counts": null,
    "image": null
}

默认情况下，不会返回所有字段。API 返回的数据已解析为 User 模型。此模型中的每个字段都可以通过解析具有键 fields 的额外 $data 数组来填充。假设我们想要用户的用户名、first_name、last_name 和图像（小和大）

$pinterest->users->me(array(
    'fields' => 'username,first_name,last_name,image[small,large]'
));

现在响应将是

{
    "id": "503066358284560467",
    "username": "dirkgroenen",
    "first_name": "Dirk ",
    "last_name": "Groenen",
    "bio": null,
    "created_at": null,
    "counts": null,
    "image": {
        "small": {
                "url": "http://media-cache-ak0.pinimg.com/avatars/dirkgroenen_1438089829_30.jpg",
                "width": 30,
                "height": 30
            },
            "large": {
                "url": "http://media-cache-ak0.pinimg.com/avatars/dirkgroenen_1438089829_280.jpg",
                "width": 280,
                "height": 280
            }
        }
    }
}

集合

当 API 返回多个模型时（例如，请求板上的推文时），包装器会将这些模型放入一个 Collection 中。

集合的输出包含 data 和页面 key。如果您 echo 集合，您将看到包含这两个的 json 编码输出。将集合用作数组将仅返回 data 中的项目。

集合类的可用方法

获取所有项

all()

$pins = $pinterest->users->getMeLikes();
$pins->all();

返回: array<Model>

获取索引处的项

get( int $index )

$pins = $pinterest->users->getMeLikes();
$pins->get(0);

返回: Model

检查集合是否有下一页

hasNextPage()

$pins = $pinterest->users->getMeLikes();
$pins->hasNextPage();

返回: Boolean

获取分页数据

返回一个包含 URL 和 cursor 的数组，用于下一页，或当没有下一页时返回 false。

分页

$pins = $pinterest->users->getMeLikes();
$pins->pagination['cursor'];

返回值: 数组

可用方法

任何包含 data 数组的方法都可以填充额外数据。这可以是为例如额外字段或分页。

身份验证

以下方法通过 $pinterest->auth 可用。

获取登录 URL

getLoginUrl(string $redirect_uri, array $scopes, string $response_type = "code");

$pinterest->auth->getLoginUrl("https://pinterest.dev/callback.php", array("read_public"));

查看 Pinterest 文档 了解可用的作用域。

注意：从 0.2.0 版本开始，默认的身份验证方法已从 token 改为 code。这意味着您需要用 access_token 交换返回的代码。

获取 access_token

getOAuthToken( string $code );

$pinterest->auth->getOAuthToken($code);

设置 access_token

setOAuthToken( string $access_token );

$pinterest->auth->setOAuthToken($access_token);

获取状态

getState();

$pinterest->auth->getState();

返回值: 字符串

设置状态

setState( string $state );

此方法可以用于手动设置状态，但这是可选的，因为 API 在初始化时会自动生成一个随机的状态。

$pinterest->auth->setState($state);

速率限制

请注意，您应该首先调用端点，否则 getRateLimit() 将返回 unknown。

获取限制

getRateLimit();

此方法可用于获取最大请求数。

$pinterest->getRateLimit();

返回值: 整数

获取剩余

getRateLimitRemaining();

此方法可用于获取剩余的调用次数。

$pinterest->getRateLimitRemaining();

返回值: 整数

用户

以下方法通过 $pinterest->users 可用。

您也无法访问未授权您的应用程序的用户的名板或钉子。

获取已登录用户

me( array $data );

$pinterest->users->me();

返回值: User

查找用户

find( string $username_or_id );

$pinterest->users->find('dirkgroenen');

返回值: User

获取用户钉子

getMePins( array $data );

$pinterest->users->getMePins();

返回值: Collection<Pin>

在用户钉子中搜索

getMePins( string $query, array $data );

$pinterest->users->searchMePins("cats");

返回值: Collection<Pin>

在用户名板中搜索

searchMeBoards( string $query, array $data );

$pinterest->users->searchMeBoards("cats");

返回值: Collection<Board>

获取用户名板

getMeBoards( array $data );

$pinterest->users->getMeBoards();

返回值: Collection<Board>

获取用户喜欢的内容

getMeLikes( array $data );

$pinterest->users->getMeLikes();

返回值: Collection<Pin>

获取用户的粉丝

getMeLikes( array $data );

$pinterest->users->getMeFollowers();

返回值: Collection<Pin>

名板

以下方法通过 $pinterest->boards 可用。

获取名板

get( string $board_id, array $data );

$pinterest->boards->get("dirkgroenen/pinterest-api-test");

返回值: Board

创建名板

create( array $data );

$pinterest->boards->create(array(
    "name"          => "Test board from API",
    "description"   => "Test Board From API Test"
));

返回值: Board

编辑名板

edit( string $board_id, array $data, string $fields = null );

$pinterest->boards-edit("dirkgroenen/pinterest-api-test", array(
    "name"  => "Test board after edit"
));

返回值: Board

删除名板

delete( string $board_id, array $data );

$pinterest->boards->delete("dirkgroenen/pinterest-api-test");

返回值: True|PinterestException

部分

以下方法通过 $pinterest->sections 可用。

在名板上创建部分

create( string $board_id, array $data );

$pinterest->sections->create("503066289565421205", array(
    "title" => "Test from API"
));

返回值: Section

获取名板上的部分

get( string $board_id, array $data );

$pinterest->sections->get("503066289565421205");

返回值: Collection<Section>

从部分获取钉子

注意：返回的名板 ID 不能直接提供给 pins()。ID 需要从 <BoardSection xxx> 中提取。

get( string $board_id, array $data );

$pinterest->sections->pins("5027630990032422748");

返回值: Collection<Pin>

删除部分

delete( string $section_id );

$pinterest->sections->delete("5027630990032422748");

返回值: 布尔值

钉子

以下方法通过 $pinterest->pins 可用。

获取钉子

get( string $pin_id, array $data );

$pinterest->pins->get("181692166190246650");

返回值: Pin

从名板获取钉子

fromBoard( string $board_id, array $data );

$pinterest->pins->fromBoard("dirkgroenen/pinterest-api-test");

返回值: Collection<Pin>

创建钉子

create( array $data );

创建一个存储在其他地方的图片的钉子

$pinterest->pins->create(array(
    "note"          => "Test board from API",
    "image_url"     => "https://download.unsplash.com/photo-1438216983993-cdcd7dea84ce",
    "board"         => "dirkgroenen/pinterest-api-test"
));

创建位于服务器上的图片的钉子

$pinterest->pins->create(array(
    "note"          => "Test board from API",
    "image"         => "/path/to/image.png",
    "board"         => "dirkgroenen/pinterest-api-test"
));

创建 base64 编码的图片的钉子

$pinterest->pins->create(array(
    "note"          => "Test board from API",
    "image_base64"  => "[base64 encoded image]",
    "board"         => "dirkgroenen/pinterest-api-test"
));

返回值: Pin

编辑钉子

edit( string $pin_id, array $data, string $fields = null );

$pinterest->pins->edit("181692166190246650", array(
    "note"  => "Updated name"
));

返回值: Pin

删除钉子

delete( string $pin_id, array $data );

$pinterest->pins->delete("181692166190246650");

返回值: True|PinterestException

关注

以下方法通过 $pinterest->following 可用。

关注用户

users( array $data );

$pinterest->following->users();

返回值: Collection<User>

关注名板

boards( array $data );

$pinterest->following->boards();

返回值: Collection<Board>

关注兴趣/类别

interests( 数组 $data );

$pinterest->following->interests();

返回值: Collection

关注一个用户

followUser( 字符串 $username_or_id );

$pinterest->following->followUser("dirkgroenen");

返回值: True|PinterestException

取消关注一个用户

unfollowUser( 字符串 $username_or_id );

$pinterest->following->unfollowUser("dirkgroenen");

返回值: True|PinterestException

关注一个板块

followBoard( 字符串 $board_id );

$pinterest->following->followBoard("503066289565421201");

返回值: True|PinterestException

取消关注一个板块

unfollowBoard( 字符串 $board_id );

$pinterest->following->unfollowBoard("503066289565421201");

返回值: True|PinterestException

关注一个兴趣点

根据Pinterest文档，此端点存在，但不知何故，他们的API当前返回错误。

followInterest( 字符串 $interest );

$pinterest->following->followInterest("architecten-911112299766");

返回值: True|PinterestException

取消关注一个兴趣点

根据Pinterest文档，此端点存在，但不知何故，他们的API当前返回错误。

unfollowInterest( 字符串 $interest );

$pinterest->following->unfollowInterest("architecten-911112299766");

返回值: True|PinterestException

示例

您可以在./demo目录中查看一个简单的示例。

如果您有使用此库的项目（示例），请告知我。