lex111 / php-pinterest-bot

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

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. Furthermore, its public API is very poor and has a very limited set of features. With this library you have the entire set of functions, which available on Pinterest website. And there is no need to register an application to receive an access token. Just use your account login and password, like you do it in your browser. But even your account is not required, if you don't use such operations as creating pins, writing comments or sending messages!

• Installation
• Quick Start
• Account
• Boards
• Pins
• Pinners
• Interests
• Topics
• Search
• Inbox
• Keywords
• Errors handling
• Use proxy
• Custom request settings
• Cookies
• Pagination

Installation

Dependencies

Library requires CURL extension and PHP 5.5.9 or above.

Install 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->auth->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 methods use pinterest navigation through results (with bookmarks), for example, get user followers/following, pins likes/dislikes, search and other feed queries. This means that for every batch of results there will be a request to Pinterest. These methods return a [Pagination] object with Pinterest api results.

Account

Login

$result = $bot->auth->login('mypinterestlogin', 'mypinterestpassword');

Login method returns true on success and false if fails:

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

By default bot uses auto-login. It uses cookies, saved from the last session. If auto-login fails, then bot will send login requests.

To skip auto-login and force login requests, you can pass false as the third argument:

$result = $bot->auth->login('mypinterestlogin', 'mypinterestpassword', false);

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->auth->isLoggedIn()) {
	// ...
}

To logout use logout method:

$bot->auth->logout();

Registration

To register a new user:

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

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

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

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

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

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

After registration you will receive a confirmation email. You can pass a link from this email to confirmEmail method:

$bot->auth->confirmEmail($linkFromEmail);

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

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

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

Reset password

You can send to your email a link to reset your password:

$bot->password->sendResetLink('[email protected]');

Then your can grab a link from email and pass use it to reset password:

$bot->password->reset(
    'https://post.pinterest.com/f/a/your-password-reset-params',
    'newPassword'
);

Profile

Change profile. Available settings are:

• last_name,
• first_name,
• username,
• about,
• location,
• website_url,
• country (ISO2 code)
• 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->username();

Check if your account is banned:

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

Change you password:

$bot->password->change('oldPassword', 'newPassword');

Remove things you’ve recently searched for from search suggestions:

$bot->user->clearSearchHistory();

Deactivate current account:

$bot->user->deactivate();

Invitation

To invite someone by email:

$bot->user->invite($email);

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 example, pin creating or following boards).

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

Create a new board.

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

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

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 Pagination object).

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

Get board followers. Uses pinterest api pagination (returns Pagination 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->titleSuggestionsFor($pinId);

Send board with message or by email:

// send board with message
$bot->boards->sendWithMessage($boardId, 'message', $userId); // to a user
$bot->boards->sendWithMessage($boardId, 'message', [$userId1, $userId2]); // to many yusers

// send board by email
$bot->boards->sendWithEmail($boardId, 'message', '[email protected]'); // one email
$bot->boards->sendWithEmail($boardId, 'message', ['[email protected]', '[email protected]']); // many

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 a 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);

Copy/move pins to board. To copy/move one pin, pass it's id as the first argument. Pass an array of ids to copy/move many pins:

$bot->pins->copy($pinId, $boardId);
$bot->pins->move($pinId, $boardId);

Save image from pin to the disk. Saves original image of the pin to the specified path:

$imagePath = $bot->pins->saveOriginalImage($pinId, $pathForPics);

Delete pins from board. To delete one pin, pass it's id as the first argument. Pass an array of ids to delete many pins:

$bot->pins->deleteFromBoard($pinId, $boardId);

Write a comment.

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

Delete a comment.

$bot->comments->delete($pinId, $commentId);

Get pins from a specific url. For example: https://pinterest.com/source/flickr.com/ will return recent pins from flickr.com (returns Pagination object):

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

Get user pins feed (returns Pagination object).

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

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

Get activity of a pin (returns Pagination object):

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:

$activities = $bot->pins->activity($pinId, 5);
// print_r($activities->toArray());
foreach($activities as $activity) {
	//...
}

Get related pins for current pin (returns Pagination object):

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

Get last 10 related pins for current pin:

$related = $bot->pins->related($pinId, 10);
// print_r($related->toArray());
foreach($related as $pin) {
	//...
}

Get the pinners who have tied this pin (returns Pagination object):

$pinners = $bot->pins->tried($pinId);
// print_r($pinners->toArray()); 
foreach($pinners as $pinner) {
    // ...
}

Get visual similar pins:

$result = $bot->pins->visualSimilar($pinId);

Send pin with message or by email:

// send pin with message
$bot->pins->sendWithMessage($pinId, 'message', $userId); // to a user
$bot->pins->sendWithMessage($pinId, 'message', [$userId1, $userId2]); // to many users 
// send pin by email
$bot->pins->sendWithEmail($pinId, 'message', '[email protected]'); // one email
$bot->pins->sendWithEmail($pinId, 'message', ['[email protected]', '[email protected]']); // many

Pinners

Follow/unfollow user. You can use both id or username. Notice: When using username, bot will make one additional request to resolve user'id for his name.

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

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

Get user info by username.

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

Get user following info. By default returns following users. Returns Pagination object.

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 Pagination object)

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

Get the newest pins of a pinner (returns Pagination 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 Pagination object)

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

Block a user:

// by name
$bot->pinners->block('username');

// by id. For example after calling info() method
$pinnerInfo = $bot->pinners->info('username');
$bot->pinners->block($pinnerInfo['id']);

Interests

Get a list of main categories. Required bot to be logged in.

$categories = $bot->interests->main();

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

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

Get related topics for interest:

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

Get pins for specific interest (returns Pagination object):

foreach($bot->interests->pins('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->info('content-marketing');

Get pins for a specific topic (returns Pagination object):

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

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

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

Search

Search functions use Pinterest pagination in fetching results and return Pagination object.

$pins = $bot->pins->search('query')->toArray();
print_r($pins);

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

// search only in my pins
$pins = $bot->pins->searchInMyPins('query')->toArray();


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

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

Inbox

News

Get your current user's news (returns Pagination object):

// get result as array
$news = $bot->inbox->news()->toArray();

// iterate with requests
foreach($bot->inbox->news() as $new) {
    // ...
}

Notifications

Get user's notifications (returns Pagination object):

// get result as array
$notifications = $bot->inbox->notifications()->toArray();

// iterate with requests
foreach($bot->inbox->notifications() as $notification) {
    // ...
}

Conversations

Get array of last conversations.

$conversations = $bot->inbox->conversations();
print_r($conversations);

Write a message

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

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

Attach pin by id to message.

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

Send email

Email param may be string or array of emails.

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

Attach pin to email.

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

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 means the additional keyword should be put before the search keyword when making 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;

Use proxy

To set up proxy settings use useProxy method:

$bot->getHttpClient()->useProxy('192.168.1.1', '12345');

By default it uses http proxy without authentication. If your proxy requires authentication, pass auth string as the third parameter:

$bot->getHttpClient()->useProxy('192.168.1.1', '12345', 'username:password');

Use socks proxy:

$bot->getHttpClient()->useSocksProxy('192.168.1.1', '12345');

// with authentication
$bot->getHttpClient()->useSocksProxy('192.168.1.1', '12345', 'username:password');

If you need to stop sending requests via proxy:

$bot->getHttpClient()->dontUseProxy();

Custom request settings

It is possible to add some additional 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:xxxx',
    CURLOPT_PROXYTYPE => CURLPROXY_HTTP // or CURLPROXY_SOCKS5,
    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();

By default it uses client info from the last request. To reload client context pass true argument:

// force to reload client info
$info = $bot->getClientInfo(true);

You can get an url of the last visited page:

$url = $bot->getHttpClient()->getCurrentUrl();

Cookies

Current bot cookies are available through getHttpClient and cookie/cookies methods. All cookies:

$cookies = $bot->getHttpClient()->cookies();

Cookie value by name:

$someCookieValue = $bot->getHttpClient()->cookie('cookieName');

By default cookie files are stored in your system temp directory. You can set custom path to store cookies. Notice! This path should have write permissions:

$bot->getHttpClient()->setCookiesPath($yourCustomPathForCookies);

$currentPath = $bot->getHttpClient()->getCookiesPath();

Remove your cookies:

$bot->getHttpClient()->removeCookies();

Pagination

Most of methods use Pinterest pagination. For example, when you run $bot->pins->search('query'), Pinterest returns only 20 results by request, you cannot get all the pins at once with only one request. So these methods return Pagination object. You can iterate over it to get results:

$pagination = $bot->pins->search('query');
foreach($pagination as $pin) {
    // your code ...
}

Or you can grab all results at once as an array, but it will require some time, to loop through all Pinterest pages to get these results:

$pagination = $bot->pins->search('query');
$results = $pagination->toArray();
// or
$results = $bot->pins->search('query')->toArray();

By default methods return the first 50 results. For example, $bot->pins->search('query') will return only first 50 pins. But you can specify another limit num as a second argument. Or pass 0 for no limit. For example,

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

will return only 20 pins of the search results.

Limit and offset in results:

// skip first 50 results
$results = $bot->pins
    ->search('query')
    ->skip(50)
    ->get();

// skip first 50 results, and then take 20
$results = $bot->pins
    ->search('query')
    ->take(20)
    ->skip(50)
    ->get();

To get all results pass 0 in take() method.

How can I thank you?

Why not star the GitHub repo? I'd love the attention! And you can donate project on PayPal.

Thanks!