README

An Object-Oriented wrapper for consuming Pinterest API with Laravel.

Warning: This package DOESN'T store Pinterest's credentials, you should provide your own logic!
👉 Please read carefully the Manage credentials section! 👈

Support Me

Hey folks,

Do you like this package? Do you find it useful, and it fits well in your project?

I am glad to help you, and I would be so grateful if you considered supporting my work.

You can even choose 😃:

You can sponsor me 😎 with a monthly subscription.
You can buy me a coffee ☕ or a pizza 🍕 just for this package.
You can plant trees 🌴. By using this link we will both receive 30 trees for free and the planet (and me) will thank you.
You can "Star ⭐" this repository (it's free 😉).

Roadmap

This package still in development.
You can vote for endpoints not yet covered by requesting them here.
If so, it would be great if you wanted sponsor me to support my work.

Pins
- list
- create
- get
- delete
- update
- save
- analytics
Boards
- list
- create
- get
- delete
- update
- pins
Board Sections
Ad Accounts
Ad Groups
Ads
Audience Insights
Audiences
Bulk
Campaigns
Catalogs
Conversion Events
Conversion Tags
Customer Lists
Integrations
Interests
Keywords
Media
OAuth
Order Lines
Product Group Promotions
Product Groups
Resources
Search
Terms
Terms of Service
User Account

Installation

You can require the package via composer:

composer require lemaur/laravel-pinterest-api

You can install it with:

php artisan pinterest-api:install

Manage credentials

Pinterest API Authentication follows the OAuth2 standard.

The package contains helpful methods to obtain the credentials from Pinterest OAuth server, but where to store them is up to you! Every project is different, with different requirements. You can store credentials on disk, or you can write them on DB and so on...

Note: You'll need to register a new app on Pinterest and get the app ID and secret key.
But don't worry, we'll do it in the next section.

Here I'll show you how to configure your project to manage credentials.

The authentication flow returns an object containing access_token and refresh_token within the expiration timestamps and other information.

Here an example:

{
    "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"
}

The package emits Lemaur\Pinterest\Events\CredentialsRetrieved::class event within Lemaur\Pinterest\Data\OAuthData object when it receives the credentials. You can listen for this event in your project and store the credentials where you want.

To do that, you need to create a new listener

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

And inside the handle method you can decide where to store the credentials.

// 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(),
     * ]);
     */
}

Don't forget to register the listener in the 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,
    ],
];

Now it's time to edit the service provider. Open App\Providers\PinterestServiceProvider, and inside the register method you will find a predefined implementation.

As you can see in the @TODO comment, here is where you should pass the credentials you previously stored.

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...
    ));
}

In the previous examples we stored the credentials in the user's table.
So here, we can fetch them from the authenticated user.

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),
    ));
}

Require Pinterest Access

Register and get your app ID and secret key

Note: internally app ID is client_id, internally secret key is client_secret!

Log into www.pinterest.com; open a new tab with the account that you’ll use to manage your apps.
Go to My Apps.
Select Connect app and complete the request form with your app information.
Submit your request to get trial access.
As soon as Pinterest completes the review, Pinterest will notify you by email.
Once you have received the email approval, go to My Apps to see your app ID and secret key.

It's now time to copy/paste the app ID and secret key to the .env file.

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

Configure the redirect URI

The package provides a default redirect URI /pinterest/callack. You are free to change it in your configuration file.

Back to your Pinterest account.
Go to My Apps and select your app.
Go to Configure and, in Redirect URIs, enter the desired URI and save.

Note: For local development it's preferred to use http://localhost/pinterest/callback

PINTEREST_API_REDIRECT_URI=http://localhost/pinterest/callback

Generate an access token

To start the OAuth flow and request user access run php artisan pinterest:get-access-code-link
Copy/Paste the link to your browser and follow the instructions on screen.
At the end of the process you will see a white page with a text saying "All good! You can close this page."

Now you are ready to call the Pinterest API.

NOTES

Pinterest provides an access_token valid for 30 days and a refresh_token valid for 1 year.
The package automatically retrieves a new access token every time it expires, as long as the refresh token is still valid.
After 1 year, when you try to call an API endpoint, the package will throw a OAuthException with a message informing you to request a new access code.

If you are curious you can read the codebase to learn more.

Or you can use Lemaur\Pinterest\Facades\Pinterest::oauth()->credentials()->accessTokenExpiresIn to get the number of days before the access token will expire.
The same for the refresh token Lemaur\Pinterest\Facades\Pinterest::oauth()->credentials()->refreshTokenExpiresIn.

Testing

The package offers a nifty fake method to help you write your tests.
If you want some examples, I suggest to look at the package test suite.

Pinterst::assertSent(callable $callback): void

Pinterst::assertNotSent(callable $callback): void

Pinterst::assertSentCount(int $count): void

Pinterst::assertNothingSent(): void

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

lemaur / laravel-pinterest-api

Maintainers

Details