README

官方Pinterest API V5+的PHP客户端。

要求

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

开始使用

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

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

安装

Pinterest API V5+包装器仅在GitHub上可用，因此您需要两个步骤来安装它。

Pinterest API V5+客户端可在Composer上找到

composer require siapepfrance/pinterest-php-client

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

简单示例

use SiapepFrance\Pinterest\Pinterest;

$pinterest = new Pinterest(CLIENT_ID, CLIENT_SECRET);

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

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

请参阅Pinterest文档以了解可用的作用域。

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

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

获取用户账户

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

$userAccount = $pinterest->user_accounts->get();
echo $userAccount;

模型

API包装器将通过其相应的模型解析所有数据。这导致可以直接将模型echo为JSON字符串。

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

可用的模型

用户账户

板

钉钉

广告账户

检索额外字段

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

$pinterest->user_accounts->get();

响应

{
    "account_type": "PINNER",
    "profile_image": "https://www.siapep.fr/profile",
    "website_url": "https://www.siapep.fr",
    "username": "siapepfrance"
}

集合

当API返回多个模型时（例如，当您请求板上的钉钉时），包装器将它们放入一个Collection中。

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

集合类可用的方法

获取所有项

all()

$pins = $pinterest->boards->listBoards();
$pins->all();

返回：array<Model>

获取索引处的项

get( int $index )

$pins = $pinterest->boards->listBoards();
$pins->get(0);

返回：Model

检查集合是否有下一页

hasNextPage()

$pins = $pinterest->boards->listBoards();
$pins->hasNextPage();

如果集合有下一页，则获取下一页

getNextPage()

$pins = $pinterest->boards->getNextPage();
$pins->getNextPage();

返回：Boolean

获取分页数据

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

分页

$pins = $pinterest->boards->listBoards();
$pins->pagination['cursor'];

返回：Array

可用的方法

每个包含data数组的data方法都可以填充额外的数据。这可以是额外的字段或分页。

身份验证

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

获取登录 URL

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

$pinterest->auth->getLoginUrl("https://pinterest.dev/callback.php", array("boards:read,boards:write,boards:write_secret,pins:read,pins:write,pins:write_secret"));

请参阅Pinterest文档以了解可用的作用域。

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

设置 redirect_uri（此方法在使用授权码流程进行认证时很有用）

setRedirectUri( string $redirect_uri );

$pinterest->auth->setRedirectUri($redirect_uri);

获取 access_token

getOAuthToken( string $code );

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

设置 access_token

setOAuthToken( string $access_token );

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

使用刷新令牌刷新过期的 access_token

refreshOAuthToken( string $refresh_token );

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

获取状态

getState();

$pinterest->auth->getState();

返回类型：string

设置状态

setState( string $state );

此方法可用于手动设置状态，但不需要这样做，因为 API 在初始化时会自动生成一个随机状态。

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

速率限制

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

获取限制

getRateLimit();

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

$pinterest->getRateLimit();

返回类型：int

获取剩余

getRateLimitRemaining();

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

$pinterest->getRateLimitRemaining();

返回类型：int

用户账户

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

您也无法访问未授权您应用的用户的面板或钉钉。

获取已登录用户账户

get( array $data );

$pinterest->user_accounts->get();

返回类型：UserAccount

获取已登录用户账户分析

getAnalytics( array $data );

$pinterest->user_accounts->getAnalytics($data);

返回类型：Collection<UserAccountAnalytic>

板

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

列出面板

listBoards( array $data );

$pinterest->boards->listBoards();

返回类型：Collection<Board>

获取面板

get( string $boardId, array $data );

$pinterest->boards->get();

返回类型：Board

创建面板

create( array $data );

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

返回类型：Board

编辑面板

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

$pinterest->boards->edit("1234567890", array(
    "name"  => "Test board after edit"
));

返回类型：Board

获取面板的钉钉

delete( string $boardId, array $data );

$pinterest->boards->pins("1234567890", []);

返回类型：Collection<Pin>

删除面板

delete( string $boardId, array $data );

$pinterest->boards->delete("1234567890", []);

返回类型：True|PinterestException

部分

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

在面板上创建部分

create( string $boardId, array $data );

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

返回类型：Section

更新面板上的部分

create( string $boardId, string $sectionId, array $data );

$pinterest->sections->update("1234567890", "10111213", array(
    "name" => "Test from API"
));

返回类型：Section

获取面板上的部分

get( string $boardId, array $data );

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

返回类型：Collection<Section>

从部分获取钉钉

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

get( string $boardId, string $sectionId, array $data );

$pinterest->sections->pins("1234567890", "10111213");

返回类型：Collection<Pin>

删除部分

delete( string $boardId, string $sectionId );

$pinterest->sections->delete("1234567890", "10111213");

返回类型：boolean

钉钉

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

获取钉钉

get( string $pinId, array $data );

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

返回类型：Pin

从面板获取钉钉

fromBoard( string $boardId, array $data );

$pinterest->pins->fromBoard("1234567890");

返回类型：Collection<Pin>

创建钉钉

create( array $data );

创建一个在其他位置托管图像的钉钉

$pinterest->pins->create(array(
    'link' => 'https://www.siapep.fr',
    'title' => 'Test board from API',
    'description' => $message,
    'alt_text' => "",
    'board_id' => '1234567890',
    'board_section_id' => null,
    'media_source' => [
        'source_type' => 'image_url',
        'url' => 'https://www.siapep.fr/api/public/file/23/getcontent'
    ]
));

在服务器上使用 base64 编码图像创建钉钉

// Get the image and convert into string
$img = file_get_contents('/path/to/image.png');

// Encode the image string data into base64
$imgBase64 = base64_encode($img);

$pinterest->pins->create(array(
    'link' => 'https://www.siapep.fr',
    'title' => 'Test Pin from API',
    'description' => 'Test Pin description from API',
    'alt_text' => "",
    'board_id' => '1234567890',
    'board_section_id' => null,
    'media_source' => [
        'source_type' => 'image_base64',
        'content_type' => 'image/png',
        'data' => $imgBase64
    ]
));

返回类型：Pin

编辑钉钉

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

$pinterest->pins->edit("15161718", array(
    'description' => 'Test Pin description from API bis',
));

返回类型：Pin

删除钉钉

delete( string $pinId, array $data );

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

返回类型：True|PinterestException

广告账户

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

您也无法访问未授权您应用的用户的面板或钉钉。

获取广告账户

get( array $data );

$pinterest->ad_accounts->get();

返回类型：AdAccount

获取广告账户分析

getAnalytics( string $adAccountId, array $data );

$pinterest->ad_accounts->getAnalytics($adAccountId, $data);

返回类型：Collection<AdAccountAnalytic>

获取广告账户活动

getCampaigns( string $adAccountId, array $data );

$pinterest->ad_accounts->getCampaigns($adAccountId, $data);

返回类型：Collection<AdCampaign>

获取广告账户活动分析

getCampaignAnalytics( string $adAccountId, array $data );

$pinterest->ad_accounts->getCampaignAnalytics($adAccountId, $data);

返回值: Collection

获取广告账户组

getAdGroups( string $adAccountId, array $data );

$pinterest->ad_accounts->getAdGroups($adAccountId, $data);

返回值: Collection

获取广告账户组分析

getAdGroupAnalytics( string $adAccountId, array $data );

$pinterest->ad_accounts->getAdGroupAnalytics($adAccountId, $data);

返回值: Collection

获取广告账户广告

getAds( string $adAccountId, array $data );

$pinterest->ad_accounts->getAds($adAccountId, $data);

返回值: Collection

获取广告账户广告分析

getAdAnalytics( string $adAccountId, array $data );

$pinterest->ad_accounts->getAdAnalytics($adAccountId, $data);

返回值: Collection

示例

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

如果您有使用这个库的（示例）项目，请告诉我。