Welcome! I know it's been a while since I added to our Twitter API series. I've been kind of busy. First, there was the brain tumor, then the robotic radiosurgery, then the ongoing Yii Programming Series and its related startup series and finally, the launch of Meeting Planner.

I decided to write today's tutorial using the Twitter API for creating friends (what Twitter calls the people you follow).

Why? Well, the bizarre U.S. presidential election of 2016 has highlighted some of the abuse and harassment that goes on every day on Twitter, something the company has done little to filter—and as programmers, we know that's not that difficult. It's simply feared losing its audience of hateful deplorables who drive a significant share of advertising revenue.

Many women have left the service because of its ongoing harassment—for which Twitter sometimes apologizes, saying that it's trying to allow for free expression. Frankly, there is no freedom of expression when abusive harassment is indefinitely present.

There have also been articles highlighting how many people's followers are predominantly male. While Twitter does not ask users their gender, it does statistically analyze the gender of accounts for its advertisers. 

And you can peek at Twitter advertising's own demographic estimates in its analytics pages. As you can see below, Twitter estimates that 69 percent of my followers are male.

Lost in the din is that woman's voices can be more difficult to find on Twitter. But they are out there. Pew reports that 21% of female Internet users use Twitter, while 25% of male Internet users do.

So today I'll guide you through using the Yii2 Framework for PHP to access the Twitter API and automate adding friends to people's Twitter accounts. (If you'd like to learn more about Yii2, check out our parallel series Programming With Yii2.)

And, I've created a website, Twixxr.com, which will let you demonstrate the feature by adding prominent women on Twitter for your account to follow.

If you have any questions or feedback, please post them below in the comments or reach out to me on Twitter @reifman.

Looking Back: Twitter API Tutorials

While I've written a handful of Twitter API tutorials in the past, they've all been based on Yii 1.x code. Yii2 has been out for a long time, and while I've written about OAuth sign-in, I haven't written about aspects of the API for your own account and/or on behalf of authenticated accounts for the upgraded framework. And it wasn't easy—there aren't great Yii2 plugins for Twitter yet.

Here are some of my past tutorials for you to review:

• 
  Twitter API
  Building With the Twitter API: Getting Started
  Jeff Reifman
• 
  PHP
  Building With the Twitter API: OAuth, Reading and Posting
  Jeff Reifman
• 
  PHP
  Building With the Twitter API: Using Real-Time Streams
  Jeff Reifman
• 
  PHP
  Building With the Twitter API: Repeating Tweets From a Group
  Jeff Reifman
• 
  Twitter API
  Building With the Twitter API: Tweet Storms
  Jeff Reifman

Not only will today's tutorial guide you through using OAuth to authenticating site visitors' accounts, but it will also show you how to add friends to their account using the access they grant you. 

Using the TwitterOAuth PHP Library

Unfortunately, I wasn't able to find a robust working Twitter API extension for Yii2, so I leveraged the generic Twitter OAuth PHP Library to create my own Twitter model.

A lot of complex APIs don't provide good documentation, and I appreciated the step-by-step live walkthrough that TwitterOAuth provides. It's incredibly helpful:

Product Service Goals

The Twixxr service will authenticate site visitors and then automatically add new friends to their accounts. The friends will be chosen from over 600 influential women that I identified on Twitter:

Let's begin walking through the code.

Authenticating a User

My TwitterController.php has two basic methods, Request and Return. Here's the Request method:

public function actionRequest()
  {
    if (Yii::$app->user->isGuest) {
      // user has not logged in to yii site
      $t = new Twitter();
      $url = $t->getAuthorizeUrl();
      $this->redirect($url);
    } else {
      // already verified with us, look up their access keys
      $t = new Twitter();
      $t->refreshConnection(Yii::$app->user->getId());
      $this->goHome();
    }
  }

The Twitter.php model invoked in new Twitter(); gets a unique getAuthorizeURL() for you to redirect a site visitor to the Twitter authentication page, e.g. https://api.twitter.com/oauth/authorize?oauth_token=q-7ChxxxxxxxxnpXAAABzzzzzzz6E:

Once the user authorizes your application at Twitter, they are redirected back to our Return method:

public function actionReturn()
    {
      // returning from authentication
        /* If the oauth_token is old redirect to the connect page. */
        if (isset($_REQUEST['oauth_token']) && Yii::$app->session['oauth_token'] !== $_REQUEST['oauth_token']) {
            Yii::$app->session['oauth_status'] = 'oldtoken';
            return $this->goHome();
        }
        $t = new Twitter();
        $user_id = $t->getConnection($_REQUEST['oauth_verifier']);
        $person = new \common\models\User;
        $identity = $person->findIdentity($user_id);
        $u = User::findOne($user_id);
        if ($identity->validateAuthKey($u->auth_key)) {
            Yii::$app->user->login($identity);
        }
        $this->redirect(['twixxr/amplify']);
    }

The Twitter model uses your application consumer key and consumer secret, which you receive when registering it with the service:

<?php

namespace frontend\models;

use Yii;
use yii\base\Model;
use common\models\User;
use frontend\models\Auth;
use Abraham\TwitterOAuth\TwitterOAuth;
/**
 * This is the model class for table "payment".
 *
 * @property integer $id
 * @property integer $user_id
 * @property string $amount
 * @property integer $created_at
 * @property integer $updated_at
 *
 * @property User $user
 */

class Twitter extends Model {
   public $consumerKey;
   public $consumerSecret;
   public $connection;

  public function init() {
    $this->consumerKey = Yii::$app->components['authClientCollection']['clients']['twitter']['consumerKey'];
    $this->consumerSecret = Yii::$app->components['authClientCollection']['clients']['twitter']['consumerSecret'];
  }

The Return method shown above then registers a user and stores their long-term access keys for the account—this allows you to make API calls on their behalf indefinitely:

public function getConnection($oauth_verifier='') {
    $connection = new TwitterOAuth($this->consumerKey, $this->consumerSecret,Yii::$app->session['oauth_token'],Yii::$app->session['oauth_token_secret']);
    /* Create TwitteroAuth object with app key/secret and token key/secret from default phase */
    $access_token = $connection->oauth("oauth/access_token", ["oauth_verifier" => $oauth_verifier]);
    /* Save the access tokens. Normally these would be saved in a database for future use. */
    $user_id=$this->register($access_token);
    //Yii::$app->session['access_token'] = $access_token;
    /* Remove no longer needed request tokens */
    unset(Yii::$app->session['oauth_token']);
    unset(Yii::$app->session['oauth_token_secret']);
    $this->connection = new TwitterOAuth($this->consumerKey, $this->consumerSecret, $access_token['oauth_token'], $access_token['oauth_token_secret']);
    return $user_id;
  }

  public function register($access_token) {
      $screen_name = $access_token['screen_name'];
      $source_id = $access_token['user_id'];
      $user = User::find()->where(['username'=>$screen_name])->one();
      if (is_null($user)) {
        // sign them up
        $user = new User();
        $user->username = $screen_name;
        $user->email = $screen_name.'@twixxr.com';
        $user->setPassword(Yii::$app->security->generateRandomString(12));
        $user->generateAuthKey();
        $user->save();
      }
      $auth = Auth::find()->where(['source_id'=>$source_id])->one();
      if (is_null($auth)) {
        // add an auth entry
        $auth = new Auth();
        $auth->user_id = $user->id;
        $auth->source = 'twitter';
        $auth->source_id = $source_id;
        $auth->screen_name = $user->username;
        $auth->oauth_token = $access_token['oauth_token'];
        $auth->oauth_token_secret = $access_token['oauth_token_secret'];
        $auth->x_auth_expires =0;
        $auth->save();
      } else {
        $auth->oauth_token = $access_token['oauth_token'];
        $auth->oauth_token_secret = $access_token['oauth_token_secret'];
        $auth->update();
      }
      return $user->id;
    }

For read write access to their accounts, I'm extending the Auth table from the simple authentication access described in our Startup series' Simplifying Onramp With OAuth to include these extra verification keys.

I also encourage you to walk through the live step by step at TwitterOAuth. It's an excellent example showing everything in action with your own Twitter account.

Importing Names, Profile Bios, and Photos

Next, I created a Twixxr.php model which would provide a variety of important functions specific to the service. Firstly, I created Twixxr::loadProfiles()  to synchronize names, bios, and Twitter-related counts, e.g. profile photos, status posts, followers, followings, of each woman identified in my static database of Items.

public function loadProfiles() {
      // clean Item table
      $this->cleanup();
      $t = new Twitter();
      $t->refreshConnection(1); // for admin user = 1
      $time_stale = time()-(24*3600);
      $people = Item::find()
        ->where('updated_at<'.$time_stale)
        ->orWhere('updated_at=created_at')
        ->orderBy('rand()')->all();
      $cnt=0;
      foreach ($people as $i) {
        // to do - or if updated at is stale
        if ($i->detail=='') {
            $result = $t->getUsersShow($i->path);
            echo $i->path.', ';
            if (isset($result->errors)) {
              var_dump($result);
              continue;
            }
            if (isset($result->name)) {
              $i->title = Html::encode($this->removeEmoji($result->name));
              if ($i->title=='') {
                $i->title='n/a';
              }
            }
            if (isset($result->screen_name)) {
                $i->path = $result->screen_name;
            }
            if (isset($result->description)) {
              $i->detail=Html::encode($this->removeEmoji($result->description));
            }
            if (isset($result->profile_image_url_https)) {
              $i->image_url = $result->profile_image_url_https;
            }
            $i->validate();
            var_dump($i->getErrors());
            $i->update();
           SocialProfile::fill($i->id,$result);
           $cnt+=1;
           if ($cnt>25) exit;
        }
      }
  }

This is called by a console cron job which I will describe later in the Yii2 series. So these profiles are synchronized gradually and repeatedly at specific intervals over several days.

Follow: Create a Friendship

I won't detail it here, but basically I created a Log table of individual requests for every user and female account. In other words, Samuel would have 500 entries requesting an add friendship for each woman in the database.

First, though, I would make sure Samuel (and every user of Twixxr) follows the Twixxr_com account.

$result = $t->createFriend('twixxr_com');
          $total_request+=1;
          if ($result !== false) {
            $action->status = Log::STATUS_COMPLETE;
            $action->save();
          }

Before the cron job processes these commands, it refreshes the Twitter authorization and connection for Samuel and each individual user at the appropriate stage:

$t->refreshConnection($action->user_id);

Then, here's the Twitter::createFriend($screen_name) method:

public function createFriend($username) {
    $add = $this->connection
        ->post("friendships/create", ["screen_name" => $username]);
    if ($this->connection->getLastHttpCode() == 200) {
      // successful
      return $add;
    } else {
        // Handle error case
        return false;
    }
  }

Then, it does this for all the women requested by Samuel as detailed in the Log table—and of course, there's a lot happening below, which I'll describe:

echo 'add '.$person->path.' to '.$action->user_id.'<br />';
          if ($x>7) {
            $mode ='limited';
            echo 'Limited to max requests per user<br />';
            // skip this user and go to next one...
            continue; // on to next user
          }
          $followed_by = $t->getFriendshipsShow($u->username,$person->path);
          if ($followed_by == -10) {
            echo 'rate limit error<br />';
            $mode ='limited';
            // skip this user and go to next one...
            continue; // on to next user
          } else if ($followed_by==0) {
            $x+=1;
            echo 'request follow<br />';
            $result = $t->createFriend($person->path);
            $total_request+=1;
            if ($result !== false) {
              $action->status = Log::STATUS_COMPLETE;
              $action->completion_at = time();
              $action->save();
            } else {
              echo 'skip due to error';
              $action->status = Log::STATUS_SKIP_ERROR;
              $action->completion_at = time();
              $action->save();
            }
          } else {
            echo 'already followed<br /><br />';
            $action->status = Log::STATUS_SKIPPED;
            $action->save();
          }
        }

Twitter's API has strict rate limiting, and it makes using their API kind of difficult at times. The cron job above creates friendships for seven target accounts at a time before switching to another user's request until it's called again later.

Here's Twitter::getFriendshipsShow(), which checks to see if this account is already following the desired account. In the above code, it skips requests that are redundant, to spare the rate limit.

public function getFriendshipsShow($source_name,$target_name) {
    $result = $this->connection->get("friendships/show", ["source_screen_name" => $source_name,"target_screen_name" => $target_name]);
    if (isset($result->errors)) {
      if ($result->errors[0]->message=='Rate limit exceeded') {
        return -10;
      }
    } else {
      if (isset($result->relationship->target->followed_by)) {
        if  ($result->relationship->target->followed_by) {
          return 1;
        } else {
          return 0;
        }
      }
    }
    return -1;
  }

In the near future, I'll implement Twitter's bulk API for this, making just one call instead of hundreds per user using get/friendships/lookup. Note that you will need a developer account to access this page.

Unfollow: Destroy a Friendship

You can also undo these friendships via the API:

$statuses = $connection->post("friendships/destroy", ["screen_name" => $u]);

I'm logging every connection Twixxr makes, and if Twitter's API rate limits were less onerous and time-consuming, I'd allow visitors to have an undo feature for Twixxr, to unfollow all the women if they don't like all the new accounts. 

Performance

I did a lot in Twixxr to manage performance. Basically, I built the Log table to quickly record all of the user's requested friendships. But all of these are processed in the background.

Unfortunately, the Twitter API does not allow for posting a list of accounts to follow in bulk. There is simply no way to do this in real time while the user is on your site.

So the user response to a Twixxr request is immediate, but it may take several hours or more for all of the accounts to be followed.

Here's the TwixxrController.php follow All method:

public function actionAll()
    {
      // make request for authenticated user to follow all twitter profiles
      $x = new Twixxr();
      $x->followTwixxr(Yii::$app->user->getId());
      $x->followAll(Yii::$app->user->getId());
      Yii::$app->getSession()->setFlash('success', Yii::t('frontend','Your request has been added to our queue.'));
      $this->redirect(['twixxr/complete',['task'=>'all']]);
      // redir home
    }

Here are the Twixxr::followAll and followCount methods that are also used by the numbered buttons above, for following 100, 200, 300 women, etc.

public function followAll($user_id) {
    $allWomen = Item::find()->count();
    $this->followCount($user_id,$allWomen);
  }

  public function followCount($user_id,$cnt=100) {
    $women = Item::find()->orderBy('rand()')->limit($cnt)->all();
    foreach ($women as $w) {
        $l = Log::find()
          ->where(['user_id'=>$user_id,'item_id'=>$w->id])
          ->one();
        if (!is_null($l)) {
          $l->status = Log::STATUS_PENDING;
          $l->update();
        }  else {
          $l = new Log();
          $l->user_id = $user_id;
          $l->item_id = $w->id;
          $l->event_id = Twixxr::EVENT_ADD;
          $l->status = Log::STATUS_PENDING;
          $l->save();
        }
    }
  }

They're just creating Log entries for each friendship request for the cron job to process in the background.

What's Next?

I hope you've enjoyed learning about using TwitterOAuth.php in Yii2 and how to authorize and apply the Twitter API on behalf of your site users.

Next, I'd like to use the Twitter API to analyze my own followers. I have a suspicion that the vast majority of Twitter followers are spammy bots, and I'd like to use the API to prove this. Stay tuned.

If you have any questions or suggestions, please post them in the comments. If you'd like to keep up on my future Envato Tuts+ tutorials and other series, please visit my instructor page or follow @reifman. Definitely check out my startup series and Meeting Planner.

Related Links

• Twixxr 
• How to Program With Yii2 Series (Envato Tuts+)
• Yii2 Developer Exchange, my Yii2 resource site
• How to use yii2-authclient to communicate with Twitter using Single Access Token (Yii Documentation)
  
• Twitter Developer Documentation
• Twitter OAuth PHP Library