Allows the *Lookup methods to accept arrays of identifiers or screen names

src/Twitter.php

@@ -7,6 +7,7 @@
 
 namespace ZendService\Twitter;
 
+use Closure;
 use Traversable;
 use ZendOAuth as OAuth;
 use Zend\Http;
@@ -803,14 +804,21 @@ public function friendshipsCreate($id, array $params = []) : Response
      *
      * Returns the next cursor if there are more to be returned.
      *
-     * @param int|string $id
+     * $id may be one of any of the following:
+     *
+     * - a single user identifier
+     * - a single screen name
+     * - a list of user identifiers
+     * - a list of screen names
+     *
+     * @param int|string|array $id
      * @throws Http\Client\Exception\ExceptionInterface if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      */
     public function friendshipsLookup($id, array $params = []) : Response
     {
         $path = 'friendships/lookup';
-        $params = $this->createUserParameter($id, $params);
+        $params = $this->createUserListParameter($id, $params, __METHOD__);
         return $this->get($path, $params);
     }
 
@@ -1335,15 +1343,21 @@ public function statusesUserTimeline(array $options = []) : Response
      *
      * This is the most effecient way of gathering bulk user data.
      *
-     * @param int|string $id
+     * $id may be one of any of the following:
+     *
+     * - a single user identifier
+     * - a single screen name
+     * - a list of user identifiers
+     * - a list of screen names
+     *
+     * @param int|string|array $id
      * @throws Http\Client\Exception\ExceptionInterface if HTTP request fails or times out
      * @throws Exception\DomainException if unable to decode JSON payload
      */
     public function usersLookup($id, array $params = []) : Response
     {
         $path = 'users/lookup';
-        // $params = $this->createUserParameter($id, $params);
-        $params['user_id'] = $id;
+        $params = $this->createUserListParameter($id, $params, __METHOD__);
         return $this->post($path, $params);
     }
 
@@ -1446,16 +1460,17 @@ public function init(string $path, Http\Client $client) : void
      * returned verbatim. Otherwise, a zero is returned.
      *
      * @param string|int $int
-     * @return string|int
      */
-    protected function validInteger($int)
+    protected function validInteger($int) : int
     {
-        if (is_int($int)) {
+        if (is_int($int) && $int > -1) {
             return $int;
         }
+
         if (is_string($int) && preg_match('/^(\d+)$/', $int)) {
             return $int;
         }
+
         return 0;
     }
 
@@ -1467,12 +1482,11 @@ protected function validInteger($int)
     protected function validateScreenName(string $name) : string
     {
         if (! is_string($name) || ! preg_match('/^[a-zA-Z0-9_]{1,15}$/', $name)) {
-            throw new Exception\InvalidArgumentException(
-                'Screen name, "'
-                . $name
-                . '" should only contain alphanumeric characters and'
-                . ' underscores, and not exceed 15 characters.'
-            );
+            throw new Exception\InvalidArgumentException(sprintf(
+                'Screen name, "%s" should only contain alphanumeric characters and'
+                . ' underscores, and not exceed 15 characters.',
+                $name
+            ));
         }
         return $name;
     }
@@ -1513,15 +1527,106 @@ protected function performPost(string $method, $data, Http\Client $client) : Htt
      *
      * @param int|string $id
      * @param array $params
+     * @throws Exception\InvalidArgumentException if the value is neither an integer nor a string
      */
     protected function createUserParameter($id, array $params) : array
     {
-        if ($this->validInteger($id)) {
+        if (! is_string($id) && ! is_int($id)) {
+            throw new Exception\InvalidArgumentException(sprintf(
+                '$id must be an integer or a string, received %s',
+                is_object($id) ? get_class($id) : gettype($id)
+            ));
+        }
+
+        if (0 !== $this->validInteger($id)) {
             $params['user_id'] = $id;
             return $params;
         }
 
+        if (! is_string($id)) {
+            throw new Exception\InvalidArgumentException(sprintf(
+                '$id must be an integer or a string, received %s',
+                gettype($id)
+            ));
+        }
+
         $params['screen_name'] = $this->validateScreenName($id);
         return $params;
     }
+
+    /**
+     * Prepares a list of identifiers for use with endpoints accepting lists of users.
+     *
+     * The various `lookup` endpoints allow passing either:
+     *
+     * - a single user identifier
+     * - a single screen name
+     * - a list of user identifiers
+     * - a list of screen names
+     *
+     * This method checks for each of these conditions. For scalar $ids, it
+     * proxies to {@link createUserParameter}. Otherwise, it checks to ensure
+     * that all values are of the same type. For identifiers, it then
+     * concatenates the values and returns them in the `user_id` parameter.
+     * For screen names, it validates them first, before concatenating and
+     * returning them via the `screen_name` parameter.
+     *
+     * @param int|string|array $ids
+     * @throws Exception\InvalidArgumentException for a non-int/string/array $ids value.
+     * @throws Exception\InvalidArgumentException if an array of $ids exceeds 100 items.
+     * @throws Exception\InvalidArgumentException if an array of $ids are not all of the same type.
+     * @throws Exception\InvalidArgumentException if any screen name element is invalid.
+     */
+    protected function createUserListParameter($ids, array $params, string $context) : array
+    {
+        if (! is_array($ids)) {
+            return $this->createUserParameter($ids, $params);
+        }
+
+        if (100 < count($ids)) {
+            throw new Exception\InvalidArgumentException(sprintf(
+                'Lists of identifier(s) or screen name(s) provided for %s; '
+                . 'must contain no more than 100 items. '
+                . 'Received %d',
+                $context,
+                count($ids)
+            ));
+        }
+
+        $detectedType = array_reduce($ids, function ($detectedType, $id) {
+            if (false === $detectedType) {
+                return $detectedType;
+            }
+
+            $idType = 0 !== $this->validInteger($id)
+                ? 'user_id'
+                : 'screen_name';
+
+            if (null === $detectedType) {
+                return $idType;
+            }
+
+            return $detectedType === $idType
+                ? $detectedType
+                : false;
+        }, null);
+
+        if (false === $detectedType) {
+            throw new Exception\InvalidArgumentException(sprintf(
+                'Invalid identifier(s) or screen name(s) provided for %s; '
+                . 'all values must either be identifiers OR screen names. '
+                . 'You cannot provide items of both types.',
+                $context
+            ));
+        }
+
+        if ($detectedType === 'user_id') {
+            $params['user_id'] = implode(',', $ids);
+            return $params;
+        }
+
+        array_walk($ids, Closure::fromCallable([$this, 'validateScreenName']));
+        $params['screen_name'] = implode(',', $ids);
+        return $params;
+    }
 }

test/TwitterTest.php

@@ -1130,4 +1130,99 @@ public function testListsMembersRaisesExceptionIfSlugPassedWithInvalidOwnerScree
         $this->expectExceptionMessage('invalid owner_screen_name');
         $twitter->lists->members('zendframework', ['owner_screen_name' => $owner]);
     }
+
+    public function userIdentifierProvider() : iterable
+    {
+        yield 'single-user_id' => [111, 'user_id'];
+        yield 'single-screen_name' => ['zfdevteam', 'screen_name'];
+        yield 'multi-user_id' => [range(100, 150), 'user_id'];
+        yield 'multi-screen_name' => [range('a', 'z'), 'screen_name'];
+    }
+
+    /**
+     * @dataProvider userIdentifierProvider
+     * @param mixed $id
+     */
+    public function testUsersLookupAcceptsAllSupportedUserIdentifiers($id, string $paramKey)
+    {
+        $expected = is_array($id)
+            ? $expected = implode(',', $id)
+            : $id;
+
+        $twitter = new Twitter\Twitter();
+        $twitter->setHttpClient($this->stubOAuthClient(
+            'users/lookup.json',
+            Http\Request::METHOD_POST,
+            'users.lookup.json',
+            [$paramKey => $expected]
+        ));
+
+        $finalResponse = $twitter->users->lookup($id);
+        $this->assertInstanceOf(TwitterResponse::class, $finalResponse);
+    }
+
+    /**
+     * @dataProvider userIdentifierProvider
+     * @param mixed $id
+     */
+    public function testFriendshipsLookupAcceptsAllSupportedUserIdentifiers($id, string $paramKey)
+    {
+        $expected = is_array($id)
+            ? $expected = implode(',', $id)
+            : $id;
+
+        $twitter = new Twitter\Twitter();
+        $twitter->setHttpClient($this->stubOAuthClient(
+            'friendships/lookup.json',
+            Http\Request::METHOD_GET,
+            'friendships.lookup.json',
+            [$paramKey => $expected]
+        ));
+
+        $finalResponse = $twitter->friendships->lookup($id);
+        $this->assertInstanceOf(TwitterResponse::class, $finalResponse);
+    }
+
+    public function invalidUserIdentifierProvider() : iterable
+    {
+        yield 'null'                      => [null, 'integer or a string'];
+        yield 'true'                      => [true, 'integer or a string'];
+        yield 'false'                     => [false, 'integer or a string'];
+        yield 'zero-float'                => [0.0, 'integer or a string'];
+        yield 'float'                     => [1.1, 'integer or a string'];
+        yield 'empty-string'              => ['', 'alphanumeric'];
+        yield 'malformed-string'          => ['not a valid screen name', 'alphanumeric'];
+        yield 'array-too-many'            => [range(1, 200), 'no more than 100'];
+        yield 'array-type-mismatch'       => [[1, 'screenname'], 'identifiers OR screen names'];
+        yield 'array-invalid-screen-name' => [['not a valid screen name'], 'alphanumeric'];
+        yield 'object'                    => [new stdClass(), 'integer or a string'];
+    }
+
+    /**
+     * @dataProvider invalidUserIdentifierProvider
+     * @param mixed $ids
+     */
+    public function testUsersLookupRaisesExceptionIfInvalidIdentifiersProvided($ids, string $expectedMessage)
+    {
+        $twitter = new Twitter\Twitter();
+
+        $this->expectException(Twitter\Exception\InvalidArgumentException::class);
+        $this->expectExceptionMessage($expectedMessage);
+
+        $twitter->users->lookup($ids);
+    }
+
+    /**
+     * @dataProvider invalidUserIdentifierProvider
+     * @param mixed $ids
+     */
+    public function testFriendshipsLookupRaisesExceptionIfInvalidIdentifiersProvided($ids, string $expectedMessage)
+    {
+        $twitter = new Twitter\Twitter();
+
+        $this->expectException(Twitter\Exception\InvalidArgumentException::class);
+        $this->expectExceptionMessage($expectedMessage);
+
+        $twitter->friendships->lookup($ids);
+    }
 }

test/_files/friendships.lookup.json

@@ -0,0 +1,41 @@
+[
+  {
+    "name": "Taylor Singletary",
+    "screen_name": "episod",
+    "id": 819797,
+    "id_str": "819797",
+    "connections": [
+      "following",
+      "followed_by"
+    ]
+  },
+  {
+    "name": "Twitter API",
+    "screen_name": "twitterapi",
+    "id": 6253282,
+    "id_str": "6253282",
+    "connections": [
+      "following",
+      "followed_by"
+    ]
+  },
+  {
+    "name": "White Leaf",
+    "screen_name": "whiteleaf",
+    "id": 22479443,
+    "id_str": "22479443",
+    "connections": [
+      "followed_by",
+      "muting"
+    ]
+  },
+  {
+    "name": "Andy Piper",
+    "screen_name": "andypiper",
+    "id": 786491,
+    "id_str": "786491",
+    "connections": [
+      "none"
+    ]
+  }
+]