Pinterest Bot for PHP

This PHP library will help you to work with your Pinterest account without using any API account credentials.

To have an access to Pinterest API you need to go to developers.pinterest.com and register as a developer, then register your application, then wait for confirmation, and only then you will get an access token. With this library you are already ready to go. Just use only your account login and password, like you do it in your browser. But even your account is not required, if your don't use such operations as creating pins, writing comments or sending messages!

• Dependencies
• Installation
• Quick Start
• Account
• Boards
• Pins
• Pinners
• Interests
• Interests
• Topics
• Conversations
• Search
• User Settings
• News
• Keywords
• Errors handling
• Custom request settings

Dependencies

Library requires CURL extension and PHP 5.5.9 or above.

Installation

Via composer:

composer require seregazhuk/pinterest-bot

Quick Start

// You may need to amend this path to locate composer's autoloader
require('vendor/autoload.php'); 

use seregazhuk\PinterestBot\Factories\PinterestBot;

$bot = PinterestBot::create();

// login
$bot->user->login('mypinterestlogin', 'mypinterestpassword');

// get lists of your boards 
$boards = $bot->boards->forUser('yourUserName');

// create a pin
$bot->pins->create('http://exmaple.com/image.jpg', $boards[0]['id'], 'pin description');

Note: Some functions use pinterest navigation through results, for example, get user followers or search queries. These functions return a generator object with api results. By default functions return all pinterest results, but you can pass a limit num as a second argument. For example,

foreach($bot->pins->search('query', 2) as $pin) {
	// ...
}

will return only 2 pins of the search results.

Account

Login:

$resul = $bot->user->login('mypinterestlogin', 'mypinterestpassword');

Login method returns true on success and failse if fails:

$resul = $bot->user->login('mypinterestlogin', 'mypinterestpassword');
if(!$result) {
	echo $bot->getLastError();
	die();
}

Or you may skip login, if you want. It is only required for such operations as likes, follows and making pins. You can get your current logged in status via isLoggedIn method:

if($bot->user->isLoggedIn()) {
	// ...
}

To logout use logout method:

$bot->user->logout();

To register a new user:

$bot->user->register('[email protected]', 'password', 'Name');

You can specify additional parameters with registration: age and country. By default they are: 18, "UK":

$bot->user->register('[email protected]', 'password', 'Name', "DE", 40);

Register a business account. The last parameter with website url is optional:

$bot->user->registerBusiness('[email protected]', 'password', 'BusinessName');

$bot->user->registerBusiness('[email protected]', 'password', 'BusinessName', 'http://yoursite.com');

Convert your account to a business one. Requires log in. The last parameter with website url is optional:

$bot->user->convertToBusiness('businessName');

$bot->user->convertToBusiness('businessName', 'http://yoursite.com');

Boards

Get all user's boards.

$boards = $bot->boards->forUser($username);

Get full board info by boardName and userName. Here you can get board id, for further functions (for examaple, pin creating or following boards).

$info = $bot->boards->info($username, $board);

Create a new board. As third parameter you can pass privacy. It is public by default, or secret if private.

// create a public board
$bot->boards->create('name', 'description');

// create a private board
$bot->boards->create('name', 'description', 'secret');

Update a board by id.

$bot->boards->update($boardId, ['name' => 'New title', 'description' => 'New description']);

You can pass more options in update: 'privacy' - is public by default and 'category' - is other by default.

$bot->boards->update($boardId, [
    'name'        => 'New title',
    'description' => 'New description',
    'privacy'     => 'secret',
    'category'    => 'sports'
]);

Delete a board by id.

$bot->boards->delete($boardId);

Follow/unfollow board by id.

$bot->boards->follow($boardId);
$bot->boards->unfollow($boardId);

Get all pins for board by id (returns Generator object).

foreach($bot->boards->pins($boardId) as $pin)
{
    // ...
}

Get board followers. Uses pinterest api pagination (return Generator object).

foreach($bot->boards->followers($boardId) as $follower)
{
	// ...
}

When you repin, Pinterest suggests you some board titles for it. You can get these suggestions for pin by its id:

$suggestions = $bot->boards->getTitleSuggestionsFor($pinId);

Pins

Notice! Try not to be very aggressive when pinning or commenting pins, or pinterest will gonna ban you.

Get pin info by its id.

$info = $bot->pins->info(1234567890);

Create new pin. Accepts image url, board id, where to post image, description and preview url.

$pinInfo = $bot->pins->create('http://exmaple.com/image.jpg', $boardId, 'pin description');
print_r($pinfInfo['id']);

You can pass a path to your local image. It will be uploaded to pinterest:

$pinInfo = $bot->pins->create('image.jpg', $boardId, 'pin description');

You can specify a link for pin (source) as fourth argument. If not set, link is equal to image url.

$pinInfo = $bot->pins->create('http://exmaple.com/image.jpg', $boardId, 'pin description', 'http://site.com');

Repin other pin by its id.

$pinInfo = $bot->pins->repin($pinId, $boardId, 'my repin');

Edit pin by id. You can change pin's description, link or board.

// change description and link
$bot->pins->edit($pinId, 'new description', 'new link');
// change board
$bot->pins->edit($pinId, 'new description', 'new link', $newBoardId);

Move pin to a new board.

// change board
$bot->pins->moveToBoard($pinId, $newBoardId);

Delete pin by id.

$bot->pins->delete($pinId);

Like/dislike pin by id.

$bot->pins->like($pinId);
$bot->pins->unLike($pinId);

Write a comment.

$result = $bot->pins->comment($pinId, 'your comment'); 
// Result contains info about written comment. For example,
// comment_id if you want to delete it.

Delete a comment.

$bot->pins->deleteComment($pinId, $commentId);

Get pins from a specific url. For example: https://pinterest.com/source/flickr.com/ will return recent pins from flickr.com:

foreach ($bot->pins->fromSource('flickr.com') as $pin) {
    // ...
}

Get user pins feed. Method userFeed() returns Generator object.

foreach ($bot->pins->userFeed() as $pin) {
    //...
}

// only first 20 pins from feed
foreach ($bot->pins->userFeed(20) as $pin) {
    //...
}

Get activity of a pin:

foreach ($bot->pins->activity($pinId) as $data) {
    //...
}

If you don't want to get all activity records, you can pass a limit as the second parameter. Get 5 last activity records:

foreach($bot->pins->activity($pinId, 5) as $activity) {
	//...
}

Get related pins for current pin:

foreach($bot->pins->getRelatedPins($pinId) as $pin) {
	//...
}

Get last 10 related pins for current pin:

foreach($bot->pins->getRelatedPins($pinId, 10) as $pin) {
	//...
}

Pinners

Follow/unfollow user by id.

$bot->pinners->follow($userId);
$bot->pinners->unfollow($userId);

Get user info by username.

$userData = $bot->pinners->info($username);

Get user following info. By default returns following users. Uses pinterest api pagination.

foreach($bot->pinners->following('username') as $following)
{
	// ...
}

You can specify type of entities to be returned: people, interests or boards. For example:

foreach($bot->pinners->following('username', 'people') as $user)
{
	// loop through people
}

foreach($bot->pinners->following('username', 'boards') as $board)
{
	// loop through boards
}

foreach($bot->pinners->following('username', 'interests') as $interest)
{
	// loop through interests
}

Also you can use special methods-helpers to achieve the same results:

foreach($bot->pinners->followingPeople('username') as $user)
{
	// loop through people
}

foreach($bot->pinners->followingBoards('username') as $board)
{
	// loop through boards
}

foreach($bot->pinners->followingInterests('username') as $interest)
{
	// loop through interests
}

Get user followers. Returns Generator object.

foreach($bot->pinners->followers('username') as $follower)
{
	// ...
}

Get the newest pins of a pinner. Returns Generator object.

foreach($bot->pinners->pins('username') as $pin)
{
    // ...
}

Get the last 20 pins of a pinner

foreach($bot->pinners->pins('username', 20) as $pin)
{
    // ...
}

Get pins that user likes. Returns Generator object.

foreach($bot->pinners->likes('username') as $like)
{
    // ...
}

Interests

Get list of main categories.

$categories = $bot->interests->getMain()

Get category info by name (can be taken from getMain()).

$info = $bot->interests->getInfo("gifts")

Get related topics for interest:

$topics = $bot->interests->getRelatedTopics('videos');

Get pins for specific interest:

foreach($bot->interests->getPinsFor('videos') as $pin) {
    // ...
}

Topics

Each interest has a list of related topics.

Follow/unfollow a topic by name:

$bot->topics->follow('content-marketing');
$bot->topics->unFollow('content-marketing');

Get a topic info:

$info = $bot->topics->getInfo('content-marketing');

Get pins for a specific topic:

foreach($bot->topics->getPinsFor('content-marketing') as $pin) {
    // ...
}

Get related topics for topic (similar as related topics for interest):

$topics = $bot->topics->getRelatedTopics('content-marketing');

Conversations

Write a message

Write a message to user by id. You may specify one user by id, or pass an array of user ids.

$bot->conversations->sendMessage($userId, 'message text');

Add pin by id to message.

$pinId = 123456789;
$bot->conversations->sendMessage($userId, 'message text', $pinId);

Send email

Email param may be string or array of emails.

$bot->conversations->sendEmail('[email protected]', 'message text');

Attach pin to email.

$bot->conversations->sendEmail('[email protected]', 'message text', $pindId);

Get array of last conversations.

$conversations = $bot->conversations->last();

Search

Search functions use pinterest pagination in fetching results and return generator.

foreach($bot->pins->search('query') as $pin)
{
	// ...
}

foreach($bot->pinners->search('query') as $pinner)
{
	// ...
}

foreach($bot->boards->search('query') as $board);
{
	// ...
}

User Settings

Change profile. Available settings are: last_name, first_name, username, about, location, website_url and profile_image:

$bot->user->profile(['first_name'=>'My_name']);

You can change your profile avatar by setting profile_image key with a path to image:

$bot->user->profile([
	'first_name' => 'My_name',
	'profile_image' => $path_to_file
]);

You can get your current profile settings calling profile method without any params:

$profile = $bot->user->profile();
echo $profile['username']; //prints your username

In result you can find your username, and all your account settings.

Get your current username:

$username = $bot->user->getUserName();

Check if your account is banned:

if ($bot->user->isBanned() {
    // ... you have ban
}

Change you password:
```php
$bot->user->changePassword('oldPassword', 'newPassword');

Deactivate current account:

$bot->user->deactivate();

News

Get your current user's news. Returns Generator object.

foreach($bot->news->all() as $new) {
    // ...
}

Keywords

Get recommended keywords for the query.

$keywords = $bot->keywords->recommendedFor('dress');
print_r($keywords);

/*
Array
(
    [0] => Array
        (
            [term] => for teens
            [position] => 1
            [display] => For Teens
        )

    [1] => Array
        (
            [term] => wedding
            [position] => 0
            [display] => Wedding
        )
	// ...
)
*/

"position" determine the order to create the complete word. For example:

• "for teens", position = 1 -> the complete keyword is : "dress for teens"
• "wedding", position = 0 -> the complete keywords is: "wedding dress"

So, position = 0 mean the additional keyword should be putted before the search keyword when make concatenation, and position = 1 is for the reverse case.

Errors handling

You can check for occurred errors after requests with method getLastError(). It returns string that contains error from you last request to API:

$error = $bot->getLastError();
echo $error;

Custom request settings

It is possible to override default Curl options for bot requests. For example you can set proxy and user-agent like this:

$bot->getHttpClient()->setOptions([
    CURLOPT_PROXY => 'xx.xx.xxx.xx:80',
    CURLOPT_USERAGENT => 'Your_User_Agent',
]);

With every request Pinterest returns an array with your current client info, with such info as OS, browser, ip and others:

$info = $bot->getClientInfo();

How can I thank you?

Why not star the github repo? I'd love the attention!

Thanks!