Stars: 170
Forks: 78
Pull Requests: 39
Issues: 84
Watchers: 21
Last Updated: 2021-09-08 06:56:49
A PHP wrapper for the official Pinterest API. :pushpin:
License: Apache License 2.0
Languages: PHP
https://developers.pinterest.com/docs/getting-started/introduction/
A PHP wrapper for the official Pinterest API.
To use the Pinterest API you have to register yourself as a developer and create an application. After you've created your app you will receive a app_id
and app_secret
.
The terms
client_id
andclient_secret
are in this caseapp_id
andapp_secret
.
The Pinterest API wrapper is available on Composer.
composer require dirkgroenen/pinterest-api-php
If you're not using Composer (which you should start using, unless you've got a good reason not to) you can include the autoload.php
file in your project.
use DirkGroenen\Pinterest\Pinterest;
$pinterest = new Pinterest(CLIENT_ID, CLIENT_SECRET);
After you have initialized the class you can get a login URL:
$loginurl = $pinterest->auth->getLoginUrl(CALLBACK_URL, array('read_public'));
echo '<a href=' . $loginurl . '>Authorize Pinterest</a>';
Check the Pinterest documentation for the available scopes.
After your user has used the login link to authorize he will be send back to the given CALLBACK_URL
. The URL will contain the code
which can be exchanged into an access_token
. To exchange the code for an access_token
and set it you can use the following code:
if(isset($_GET["code"])){
$token = $pinterest->auth->getOAuthToken($_GET["code"]);
$pinterest->auth->setOAuthToken($token->access_token);
}
To get the profile of the current logged in user you can use the Users::me(<array>);
method.
$me = $pinterest->users->me();
echo $me;
The API wrapper will parse all data through it's corresponding model. This results in the possibility to (for example) directly echo
your model into a JSON string.
Models also show the available fields (which are also described in the Pinterest documentation). By default, not all fields are returned, so this can help you when providing extra fields to the request.
If you want more fields you can specify these in the $data
(GET requests) or $fields
(PATCH requests) array. Example:
$pinterest->users->me();
Response:
{
"id": "503066358284560467",
"username": null,
"first_name": "Dirk ",
"last_name": "Groenen",
"bio": null,
"created_at": null,
"counts": null,
"image": null
}
By default, not all fields are returned. The returned data from the API has been parsed into the User
model. Every field in this model can be filled by parsing an extra $data
array with the key fields
. Say we want the user's username, first_name, last_name and image (small and large):
$pinterest->users->me(array(
'fields' => 'username,first_name,last_name,image[small,large]'
));
The response will now be:
{
"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
}
}
}
}
When the API returns multiple models (for instance when your requesting the pins from a board) the wrapper will put those into a Collection
.
The output of a collection contains the data
and page key
. If you echo the collection you will see a json encoded output containing both of these. Using the collection as an array will only return the items from data
.
Available methods for the collection class:
all()
$pins = $pinterest->users->getMeLikes();
$pins->all();
Returns: array<Model>
get( int $index )
$pins = $pinterest->users->getMeLikes();
$pins->get(0);
Returns: Model
hasNextPage()
$pins = $pinterest->users->getMeLikes();
$pins->hasNextPage();
Returns: Boolean
Returns an array with an URL
and cursor
for the next page, or false
when no next page is available.
pagination
$pins = $pinterest->users->getMeLikes();
$pins->pagination['cursor'];
Returns: Array
Every method containing a
data
array can be filled with extra data. This can be for example extra fields or pagination.
The methods below are available through $pinterest->auth
.
getLoginUrl(string $redirect_uri, array $scopes, string $response_type = "code");
$pinterest->auth->getLoginUrl("https://pinterest.dev/callback.php", array("read_public"));
Check the Pinterest documentation for the available scopes.
Note: since 0.2.0 the default authentication method has changed to code
instead of token
. This means you have to exchange the returned code for an access_token.
getOAuthToken( string $code );
$pinterest->auth->getOAuthToken($code);
setOAuthToken( string $access_token );
$pinterest->auth->setOAuthToken($access_token);
getState();
$pinterest->auth->getState();
Returns: string
setState( string $state );
This method can be used to set a state manually, but this isn't required since the API will automatically generate a random state on initialize.
$pinterest->auth->setState($state);
Note that you should call an endpoint first, otherwise
getRateLimit()
will returnunknown
.
getRateLimit();
This method can be used to get the maximum number of requests.
$pinterest->getRateLimit();
Returns: int
getRateLimitRemaining();
This method can be used to get the remaining number of calls.
$pinterest->getRateLimitRemaining();
Returns: int
The methods below are available through $pinterest->users
.
You also cannot access a user’s boards or Pins who has not authorized your app.
me( array $data );
$pinterest->users->me();
Returns: User
find( string $username_or_id );
$pinterest->users->find('dirkgroenen');
Returns: User
getMePins( array $data );
$pinterest->users->getMePins();
Returns: Collection<Pin>
getMePins( string $query, array $data );
$pinterest->users->searchMePins("cats");
Returns: Collection<Pin>
searchMeBoards( string $query, array $data );
$pinterest->users->searchMeBoards("cats");
Returns: Collection<Board>
getMeBoards( array $data );
$pinterest->users->getMeBoards();
Returns: Collection<Board>
getMeLikes( array $data );
$pinterest->users->getMeLikes();
Returns: Collection<Pin>
getMeLikes( array $data );
$pinterest->users->getMeFollowers();
Returns: Collection<Pin>
The methods below are available through $pinterest->boards
.
get( string $board_id, array $data );
$pinterest->boards->get("dirkgroenen/pinterest-api-test");
Returns: Board
create( array $data );
$pinterest->boards->create(array(
"name" => "Test board from API",
"description" => "Test Board From API Test"
));
Returns: Board
edit( string $board_id, array $data, string $fields = null );
$pinterest->boards-edit("dirkgroenen/pinterest-api-test", array(
"name" => "Test board after edit"
));
Returns: Board
delete( string $board_id, array $data );
$pinterest->boards->delete("dirkgroenen/pinterest-api-test");
Returns: True|PinterestException
The methods below are available through $pinterest->sections
.
create( string $board_id, array $data );
$pinterest->sections->create("503066289565421205", array(
"title" => "Test from API"
));
Returns: Section
get( string $board_id, array $data );
$pinterest->sections->get("503066289565421205");
Returns: Collection<Section>
Note: Returned board ids can't directly be provided to
pins()
. The id needs to be extracted from <BoardSection xxx>
get( string $board_id, array $data );
$pinterest->sections->pins("5027630990032422748");
Returns: Collection<Pin>
delete( string $section_id );
$pinterest->sections->delete("5027630990032422748");
Returns: boolean
The methods below are available through $pinterest->pins
.
get( string $pin_id, array $data );
$pinterest->pins->get("181692166190246650");
Returns: Pin
fromBoard( string $board_id, array $data );
$pinterest->pins->fromBoard("dirkgroenen/pinterest-api-test");
Returns: Collection<Pin>
create( array $data );
Creating a pin with an image hosted somewhere else:
$pinterest->pins->create(array(
"note" => "Test board from API",
"image_url" => "https://download.unsplash.com/photo-1438216983993-cdcd7dea84ce",
"board" => "dirkgroenen/pinterest-api-test"
));
Creating a pin with an image located on the server:
$pinterest->pins->create(array(
"note" => "Test board from API",
"image" => "/path/to/image.png",
"board" => "dirkgroenen/pinterest-api-test"
));
Creating a pin with a base64 encoded image:
$pinterest->pins->create(array(
"note" => "Test board from API",
"image_base64" => "[base64 encoded image]",
"board" => "dirkgroenen/pinterest-api-test"
));
Returns: Pin
edit( string $pin_id, array $data, string $fields = null );
$pinterest->pins->edit("181692166190246650", array(
"note" => "Updated name"
));
Returns: Pin
delete( string $pin_id, array $data );
$pinterest->pins->delete("181692166190246650");
Returns: True|PinterestException
The methods below are available through $pinterest->following
.
users( array $data );
$pinterest->following->users();
Returns: Collection<User>
boards( array $data );
$pinterest->following->boards();
Returns: Collection<Board>
interests( array $data );
$pinterest->following->interests();
Returns: Collection<Interest>
followUser( string $username_or_id );
$pinterest->following->followUser("dirkgroenen");
Returns: True|PinterestException
unfollowUser( string $username_or_id );
$pinterest->following->unfollowUser("dirkgroenen");
Returns: True|PinterestException
followBoard( string $board_id );
$pinterest->following->followBoard("503066289565421201");
Returns: True|PinterestException
unfollowBoard( string $board_id );
$pinterest->following->unfollowBoard("503066289565421201");
Returns: True|PinterestException
According to the Pinterest documentation this endpoint exists, but for some reason their API is returning an error at the moment.
followInterest( string $interest );
$pinterest->following->followInterest("architecten-911112299766");
Returns: True|PinterestException
According to the Pinterest documentation this endpoint exists, but for some reason their API is returning an error at the moment.
unfollowInterest( string $interest );
$pinterest->following->unfollowInterest("architecten-911112299766");
Returns: True|PinterestException
Use can take a look at the ./demo
directory for a simple example.
Let me know if you have an (example) project using the this library.