README

一个使用 Laravel 消费 Pinterest API 的面向对象的包装器。

它使用 Pinterest API v5。

警告：此包不会存储 Pinterest 的凭证，您应提供自己的逻辑！
👉 请仔细阅读 管理凭证 部分！👈

支持我

大家好，

你们喜欢这个包吗？你觉得它有用，并且很好地适应了你的项目吗？

我很乐意帮助你，如果你考虑支持我的工作，我将不胜感激。

你甚至可以选择 😃

• 你可以 通过月度订阅赞助我 😎。
• 你 可以买我一杯咖啡 ☕ 或一块披萨 🍕 只为这个包。
• 你可以在 种树 🌴。通过使用此链接，我们将免费获得 30 棵树，并且地球（和我）将感谢你。
• 你还可以“星标 ⭐”此仓库（这是免费的 😉）。

路线图

此包仍在开发中。
您可以在 此处请求它们 为尚未覆盖的端点投票。
如果是这样，如果你愿意 赞助我 支持我的工作，那就太好了。

• 图钉
  • 列表
  • 创建
  • 获取
  • 删除
  • 更新
  • 保存
  • 分析
• 版块
  • 列表
  • 创建
  • 获取
  • 删除
  • 更新
  • 图钉
• 版块部分
• 广告账户
• 广告组
• 广告
• 受众洞察
• 受众
• 批量
• 活动
• 目录
• 转化事件
• 转化标签
• 客户列表
• 集成
• 兴趣
• 关键词
• 媒体
• OAuth
• 订单行
• 产品组合促销
• 产品组合
• 资源
• 搜索
• 条款
• 服务条款
• 用户账户

安装

您可以通过 composer 需求此包

composer require lemaur/laravel-pinterest-api

您可以使用以下命令安装它

php artisan pinterest-api:install

管理凭证

Pinterest API 身份验证 遵循 OAuth2 标准。

此包包含从 Pinterest OAuth 服务器获取凭证的有用方法，但存储位置由您决定！每个项目都不同，有不同的需求。您可以在磁盘上存储凭证，也可以将它们写入数据库，等等...

注意：您需要在 Pinterest 上注册一个新应用并获取应用 ID 和密钥。
但不用担心，我们将在下一部分中完成。

在这里，我将向您展示如何配置项目以管理凭证。

身份验证流程返回一个对象，其中包含在过期时间戳和其他信息中包含的 access_token 和 refresh_token。

这里是一个示例

{
    "access_token": "{an access token string prefixed with 'pina'}",
    "refresh_token": "{a refresh token string prefixed with 'pinr'}",
    "response_type": "authorization_code",
    "token_type": "bearer",
    "expires_in": 2592000,
    "refresh_token_expires_in": 31536000,
    "scope": "boards:read boards:write pins:read"
}

当收到凭证时，该包在 Lemaur\Pinterest\Data\OAuthData 对象中触发 Lemaur\Pinterest\Events\CredentialsRetrieved::class 事件。您可以在项目中监听此事件并将凭证存储在您想要的位置。

为此，您需要创建一个新的监听器

php artisan make:listener --event=\\Lemaur\\Pinterest\\Events\\CredentialsRetrieved StorePinterestCredentials

在 handle 方法内部，您可以决定在哪里存储凭证。

// file: app/Listeners/StorePinterestCredentials.php

/**
 * Handle the event.
 *
 * @param  \Lemaur\Pinterest\Events\CredentialsRetrieved  $event
 * @return void
 */
public function handle(CredentialsRetrieved $event)
{
    // Store the credentials from `$event->oauth`.
    // Where `$event->oauth` is an instance of `Lemaur\Pinterest\Data\OAuthData`.
    
    /**
     * For e.g. you can extend your User model by adding a json column `pinterest_credentials` 
     * and store the credentials for each authenticated user.
     *
     * \Illuminate\Support\Facades\Auth::user()->update([
     *     'pinterest_credentials' = $event->oauth->toArray(),
     * ]);
     */
}

别忘了在 App\Providers\EventServiceProvider 中注册监听器。

// file: app/Providers/EventServiceProvider.php

/**
 * The event listener mappings for the application.
 *
 * @var array<class-string, array<int, class-string>>
 */
protected $listen = [
    \Lemaur\Pinterest\Events\CredentialsRetrieved::class => [
        \App\Listeners\StorePinterestCredentials::class,
    ],
];

现在，是时候编辑服务提供商了。打开 App\Providers\PinterestServiceProvider，在 register 方法中，您将找到一个预定义的实现。

如 @TODO 注释所示，这里应该传递您之前存储的凭证。

public function register(): void
{
    $this->app->singleton(PinterestContract::class, fn (Application $app) => new PinterestService(
        config: ConfigData::fromConfig($app['config']['pinterest']),
        oauth: OAuthData::from([]), // @TODO: <-- please fill in the credentials...
    ));
}

在前面的例子中，我们将凭证存储在用户表中。
因此，在这里，我们可以从已认证的用户中获取它们。

public function register(): void
{
    $this->app->singleton(PinterestContract::class, fn (Application $app) => new PinterestService(
        config: ConfigData::fromConfig($app['config']['pinterest']),
        oauth: OAuthData::from(\Illuminate\Support\Facades\Auth::user()->pinterest_credentials),
    ));
}

需要 Pinterest 访问权限

注册并获取您的应用 ID 和密钥

注意：内部 应用 ID 是 client_id，内部 密钥 是 client_secret！

1. 登录 www.pinterest.com；使用您将用于管理应用的账户在新标签页中打开。
2. 转到“我的应用”。
3. 选择连接应用，并填写带有您的应用信息的需求表。
4. 提交您的请求以获取试用访问权限。
5. 一旦 Pinterest 完成 review，将通过电子邮件通知您。
6. 收到电子邮件批准后，转到“我的应用”以查看您的应用 ID 和密钥。

现在，是时候复制/粘贴应用 ID 和密钥到 .env 文件中。

PINTEREST_API_CLIENT_ID="app ID"
PINTEREST_API_CLIENT_SECRET="secret key"

配置重定向 URI

此包提供了一个默认的重定向 URI /pinterest/callack。您可以在配置文件中自由更改它。

1. 回到您的 Pinterest 账户。
2. 转到“我的应用”并选择您的应用。
3. 转到“配置”，然后在“重定向 URI”中输入所需的 URI 并保存。

注意：对于本地开发，建议使用 https:///pinterest/callback

PINTEREST_API_REDIRECT_URI=https:///pinterest/callback

生成访问令牌

1. 要启动 OAuth 流程并请求用户访问权限，请运行 php artisan pinterest:get-access-code-link
2. 将链接复制/粘贴到浏览器中，并遵循屏幕上的说明。
3. 过程结束时，您将看到一个白色页面，上面有文本说“一切都好！您可以关闭此页面。”

现在您已经准备好调用 Pinterest API。

注意

Pinterest 提供了一个有效的 30 天的 access_token 和一个有效的 1 年的 refresh_token。
只要刷新令牌仍然有效，包会自动在每次过期时检索新的访问令牌。
一年后，当您尝试调用 API 端点时，包将抛出一个 OAuthException，并显示一条消息，通知您请求新的访问代码。

如果您好奇，可以 查看代码库以了解更多信息。

或者，您可以使用 Lemaur\Pinterest\Facades\Pinterest::oauth()->credentials()->accessTokenExpiresIn 来获取访问令牌将在多少天后过期。
刷新令牌也是一样，使用 Lemaur\Pinterest\Facades\Pinterest::oauth()->credentials()->refreshTokenExpiresIn。

测试

该包提供了一个方便的模拟方法，以帮助您编写测试。
如果您需要一些示例，我建议查看 包测试套件。

Pinterst::assertSent(callable $callback): void

Pinterst::assertNotSent(callable $callback): void

Pinterst::assertSentCount(int $count): void

Pinterst::assertNothingSent(): void

更改日志

有关最近更改的更多信息，请参阅 更改日志。

贡献

有关详细信息，请参阅 贡献。

安全漏洞

有关如何报告安全漏洞的详细信息，请参阅 我们的安全策略。

鸣谢

• Maurizio
• 所有贡献者

许可

MIT 许可证 (MIT)。请参阅许可证文件获取更多信息。