Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lemaur/laravel-pinterest-api
Object-Oriented wrapper for consuming Pinterest API with Laravel
https://github.com/lemaur/laravel-pinterest-api
api laravel lemaur pinterest pinterest-api v5
Last synced: 2 months ago
JSON representation
Object-Oriented wrapper for consuming Pinterest API with Laravel
- Host: GitHub
- URL: https://github.com/lemaur/laravel-pinterest-api
- Owner: leMaur
- License: mit
- Created: 2023-03-26T10:31:04.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-04-29T07:06:47.000Z (8 months ago)
- Last Synced: 2024-05-01T15:28:59.527Z (8 months ago)
- Topics: api, laravel, lemaur, pinterest, pinterest-api, v5
- Language: PHP
- Homepage:
- Size: 85 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# Laravel Pinterest Api
[](https://packagist.org/packages/lemaur/laravel-pinterest-api)
[](https://packagist.org/packages/lemaur/laravel-pinterest-api)
[](https://github.com/leMaur/laravel-pinterest-api/blob/main/LICENSE.md)
[](https://github.com/leMaur/laravel-pinterest-api/actions/workflows/run-tests.yml)
[](https://github.com/sponsors/leMaur)
[](https://ecologi.com/lemaur?r=6012e849de97da001ddfd6c9)
An Object-Oriented wrapper for consuming Pinterest API with Laravel.
It uses [Pinterest API v5](https://developers.pinterest.com/docs/api/v5/).
> **Warning**: This package DOESN'T store Pinterest's credentials, you should provide your own logic!
> 👉 Please read carefully the [Manage credentials](#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 😎](https://github.com/sponsors/leMaur) with a monthly subscription.
* You can [buy me a coffee ☕ or a pizza 🍕](https://github.com/sponsors/leMaur?frequency=one-time&sponsor=leMaur) just for this package.
* You can [plant trees 🌴](https://ecologi.com/lemaur?r=6012e849de97da001ddfd6c9). 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](https://github.com/lemaur/laravel-pinterest-api/discussions/new?category=polls).
If so, it would be great if you wanted [sponsor me](https://github.com/sponsors/leMaur) to support my work.
- [ ] Pins
- [ ] list
- [x] create
- [ ] get
- [x] delete
- [x] update
- [ ] save
- [ ] analytics
- [ ] Boards
- [x] 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
- [x] OAuth
- [ ] Order Lines
- [ ] Product Group Promotions
- [ ] Product Groups
- [ ] Resources
- [ ] Search
- [ ] Terms
- [ ] Terms of Service
- [ ] User Account
## Installation
You can require the package via composer:
```bash
composer require lemaur/laravel-pinterest-api
```
You can install it with:
```bash
php artisan pinterest-api:install
```
## Manage credentials
[Pinterest API Authentication](https://developers.pinterest.com/docs/getting-started/authentication/) follows the [OAuth2 standard](https://datatracker.ietf.org/doc/html/rfc6749/).
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](#require-pinterest-access).
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:
```json
{
"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
```bash
php artisan make:listener --event=\\Lemaur\\Pinterest\\Events\\CredentialsRetrieved StorePinterestCredentials
```
And inside the `handle` method you can decide where to store the credentials.
```php
// 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`.
```php
// file: app/Providers/EventServiceProvider.php
/**
* The event listener mappings for the application.
*
* @var array>
*/
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.
```php
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.
```php
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`!
1. Log into www.pinterest.com; open a new tab with the account that you’ll use to manage your apps.
2. Go to My Apps.
3. Select Connect app and complete the request form with your app information.
4. Submit your request to get trial access.
5. As soon as Pinterest completes the review, Pinterest will notify you by email.
6. 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.
```dotenv
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.
1. Back to your Pinterest account.
2. Go to My Apps and select your app.
3. 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`
```dotenv
PINTEREST_API_REDIRECT_URI=http://localhost/pinterest/callback
```
### Generate an access token
1. To start the OAuth flow and request user access run `php artisan pinterest:get-access-code-link`
2. Copy/Paste the link to your browser and follow the instructions on screen.
3. 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](https://github.com/leMaur/laravel-pinterest-api/blob/main/src/Services/Concerns/BuildBaseRequest.php#L18).
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](https://github.com/leMaur/laravel-pinterest-api/tree/main/tests).
```php
Pinterst::assertSent(callable $callback): void
```
```php
Pinterst::assertNotSent(callable $callback): void
```
```php
Pinterst::assertSentCount(int $count): void
```
```php
Pinterst::assertNothingSent(): void
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Contributing
Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
## Security Vulnerabilities
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
## Credits
- [Maurizio](https://github.com/lemaur)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.