Merge pull request #8 from hub/feature/friend-service

Feature : Friend service APIs exposed
hub · May 16, 2020 · 9eee63e · 9eee63e
2 parents 16a224c + 251aab1
commit 9eee63e
Show file tree

Hide file tree

Showing 9 changed files with 209 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -14,6 +14,8 @@ composer require hub/hubid-api-client
 
 ## Authentication
 
+Refer to the [https://hubculture.com/developer/home](https://hubculture.com/developer/home) for obtaining the private and public keys.
+
 ```php
 include '/vendor/autoload.php';
 
@@ -57,9 +59,9 @@ var_dump($user);
 Please run the following command to run a PHP server serving examples.
 
 ```bash
-make demo
+HUBID_PRIVATE_KEY=[your-private-key] HUBID_PUBLIC_KEY=[your-public-key] make demo
 ```
 
-Browse to [http://localhost:8085/message-service.php](http://localhost:8085/message-service.php).
+Browse to [http://localhost:8085/friend-service.php](http://localhost:8085/friend-service.php).
 
-You may look at examples under examples directory.
+You may look at examples under `examples` directory.
diff --git a/examples/config.php b/examples/config.php
@@ -7,8 +7,8 @@
 $config = array(
     'base_path' => 'https://id.hubculture.com:466',
     'verify' => false,
-    'private_key' => 'private_5d265de1d9204f6235830ce2',
-    'public_key' => 'public_153222247f4cbe2511208120a',
+    'private_key' => getenv('HUBID_PRIVATE_KEY'), // __YOUR_KEY__
+    'public_key' => getenv('HUBID_PUBLIC_KEY'), // __YOUR_KEY__
     'client_id' => 10014,
     'debug' => true,
 );

diff --git a/examples/event-service.php b/examples/event-service.php
@@ -11,7 +11,7 @@
 
 $redirectUrl = 'http://localhost:8085/event-service.php';
 if (empty($_GET['access_token'])) {
-    $redirectLoginHelper->getAccessToken($redirectUrl);
+    $redirectLoginHelper->redirectToLoginUrl($redirectUrl);
 } else {
     $accessToken = $_GET['access_token'];
     $refreshedToken = $redirectLoginHelper->getRefreshToken($accessToken);

diff --git a/examples/friend-service.php b/examples/friend-service.php
@@ -0,0 +1,43 @@
+<?php
+/**
+ * @author        Tharanga Kothalawala <tharanga.kothalawala@hubculture.com>
+ * @copyright (c) 2020 by HubCulture Ltd.
+ */
+
+use Hub\HubAPI\Service\Exception\HubIdApiException;
+use Hub\HubAPI\Service\FriendService;
+
+include __DIR__ . '/config.php';
+
+$redirectUrl = 'http://localhost:8085/friend-service.php';
+if (empty($_GET['access_token'])) {
+    $redirectLoginHelper->redirectToLoginUrl($redirectUrl);
+} else {
+    $accessToken = $_GET['access_token'];
+    $refreshedToken = $redirectLoginHelper->getRefreshToken($accessToken);
+    echo <<<HTML
+<pre>
+    <br/><b>Access Token</b>: '{$accessToken}'
+    <br/><b>Refresh Token</b>: '{$refreshedToken}'
+</pre>
+HTML;
+    $config['token'] = $accessToken;
+    // example event creation and retrieval
+    $service = new FriendService($config);
+
+
+    var_dump($service->getFriends());
+    var_dump($service->getPendingFriends());
+    var_dump($service->getFriendRequests());
+    var_dump($service->searchFriends('user'));
+//
+//    $potentialFriendId = 123456789;
+//    try {
+//        $response = $service->addFriend('A friend request via the API SDK', $potentialFriendId);
+//        var_dump($response);
+//    } catch (HubIdApiException $ex) {
+//        $service->removeFriend($potentialFriendId);
+//        $response = $service->addFriend('A friend request via the API SDK', $potentialFriendId);
+//    }
+//    var_dump($service->removeFriend($potentialFriendId));
+}
diff --git a/examples/message-service.php b/examples/message-service.php
@@ -13,7 +13,7 @@
 $redirectUrl = 'http://localhost:8085/message-service.php';
 
 if (empty($_GET['access_token'])) {
-    $redirectLoginHelper->getAccessToken($redirectUrl);
+    $redirectLoginHelper->redirectToLoginUrl($redirectUrl);
 } else {
     $accessToken = $_GET['access_token'];
     $refreshedToken = $redirectLoginHelper->getRefreshToken($accessToken);

diff --git a/examples/ultra-service.php b/examples/ultra-service.php
@@ -11,7 +11,7 @@
 $redirectUrl = 'http://localhost:8085/ultra-service.php';
 
 if (empty($_GET['access_token'])) {
-    $redirectLoginHelper->getAccessToken($redirectUrl);
+    $redirectLoginHelper->redirectToLoginUrl($redirectUrl);
 } else {
     $accessToken = $_GET['access_token'];
     $refreshedToken = $redirectLoginHelper->getRefreshToken($accessToken);

diff --git a/examples/user-service.php b/examples/user-service.php
@@ -12,7 +12,7 @@
 $redirectUrl = 'http://localhost:8085/user-service.php';
 
 if (empty($_GET['access_token'])) {
-    $redirectLoginHelper->getAccessToken($redirectUrl);
+    $redirectLoginHelper->redirectToLoginUrl($redirectUrl);
 } else {
     $accessToken = $_GET['access_token'];
     $refreshedToken = $redirectLoginHelper->getRefreshToken($accessToken);

diff --git a/src/Service/FriendService.php b/src/Service/FriendService.php
@@ -8,14 +8,148 @@
 
 class FriendService extends TokenRefreshingService
 {
+    const BASE = '/friends';
+    const DEFAULT_PAGINATION_LIMIT = 10;
+
+    /**
+     * This returns all the friends of the current authenticated user.
+     *
+     * @param int $offset [optional] offset for pagination
+     * @param int $limit  [optional] limit for pagination
+     *
+     * @return array
+     * @see UserService::getFriends()
+     */
+    public function getFriends($offset = 0, $limit = self::DEFAULT_PAGINATION_LIMIT)
+    {
+        $offset = intval($offset) === 0 ? 0 : intval($offset);
+        $limit = intval($limit) === 0 ? self::DEFAULT_PAGINATION_LIMIT : intval($limit);
+
+        return $this->createResponse($this->get(self::BASE . "/?offset={$offset}&limit={$limit}"));
+    }
+
+    /**
+     * Returns the pending friends associated to the current authenticated user (you).
+     * These are the list of users for whom you have sent a friend request to.
+     * However they haven't yet added you as a friend yet
+     *
+     * @return array
+     */
+    public function getPendingFriends()
+    {
+        return $this->createResponse($this->get(self::BASE . "/pending"));
+    }
+
     /**
-     * Returns the friends associated to the current authenticated user.
+     * Returns the users who have sent the current authenticated user (you) friend requests.
+     * You are yet to approve them as your friends.
+     *
      * @return array
      */
-    public function getFriends()
+    public function getFriendRequests()
     {
+        return $this->createResponse($this->get(self::BASE . "/requests"));
+    }
+
+    /**
+     * Returns the full user information of a friend. This returns 'No such friend' if the given user id is not a
+     * friend yet.
+     *
+     * @param int $friendUserId A valid user id of a friend user.
+     *
+     * @return array
+     * @see UserService::getUserById() For retriving any user.
+     */
+    public function getFriendInfo($friendUserId)
+    {
+        return $this->createResponse($this->get(self::BASE . "/{$friendUserId}"));
+    }
+
+    /**
+     * Use this to approve a friend request that the current authenticated user (you) has received.
+     *
+     * @param int $friendUserId A valid user id of a pending user / friend.
+     *
+     * @return array
+     */
+    public function approveFriendRequest($friendUserId)
+    {
+        return $this->createResponse($this->put("/friend/request/{$friendUserId}"));
+    }
+
+    /**
+     * Use this to decline a friend request that the current authenticated user (you) has received.
+     *
+     * @param int $friendUserId A valid user id of a pending user / friend.
+     *
+     * @return array
+     */
+    public function declineFriendRequest($friendUserId)
+    {
+        return $this->createResponse($this->delete("/friend/request/{$friendUserId}"));
+    }
+
+    /**
+     * Use this to add a new user as a friend.
+     *
+     * The following errors will be thrown:
+     *      'You are already friend with that user'
+     *      'A friend request already exists for that user'
+     *
+     * @param string      $message              A personal note to the receiver of the request.
+     *                                          Message length must be between 4 to 500 characters long.
+     * @param null|int    $potentialFriendId    A valid user id
+     * @param null|string $potentialFriendEmail A valid email address of an existing user in the platform
+     *
+     * @return array
+     */
+    public function addFriend($message, $potentialFriendId = null, $potentialFriendEmail = null)
+    {
+        $payload = ['message' => $message];
+        if (!is_null($potentialFriendId) && intval($potentialFriendId) > 0) {
+            $payload['id'] = $potentialFriendId;
+        }
+        if (!is_null($potentialFriendEmail)) {
+            $payload['email'] = $potentialFriendEmail;
+        }
+
+        return $this->createResponse($this->postFormData(self::BASE, $payload));
+    }
+
+    /**
+     * Use this to un-friend a existing friend.
+     *
+     * @param int $friendUserId A valid user id of a friend user.
+     *
+     * @return array
+     */
+    public function removeFriend($friendUserId)
+    {
+        return $this->createResponse($this->delete("/friend/{$friendUserId}"));
+    }
+
+    /**
+     * Use this to search for friends in the current authenticated user's (your) friend list.
+     *
+     * @param string $searchKeyword The search term to search for friends in your friend list.
+     *                              This can be part of a name or an email address.
+     * @param int    $offset        [optional] offset for pagination
+     * @param int    $limit         [optional] limit for pagination
+     *
+     * @return array
+     */
+    public function searchFriends($searchKeyword, $offset = 0, $limit = self::DEFAULT_PAGINATION_LIMIT)
+    {
+        if (empty($searchKeyword)) {
+            return [];
+        }
+
+        $offset = intval($offset) === 0 ? 0 : intval($offset);
+        $limit = intval($limit) === 0 ? self::DEFAULT_PAGINATION_LIMIT : intval($limit);
+        $searchKeyword = urlencode($searchKeyword);
+
         return $this->createResponse(
-            $this->get("/friends")
+            $this->get("/v2/friends/search?search={$searchKeyword}&offset={$offset}&limit={$limit}")
         );
     }
 }
diff --git a/src/Service/UserService.php b/src/Service/UserService.php
@@ -11,6 +11,7 @@
 class UserService extends TokenRefreshingService
 {
     const BASE = '/user';
+    const DEFAULT_PAGINATION_LIMIT = 10;
 
     /**
      * Use this to provision a new user in the Hub Culture platform.
@@ -82,4 +83,21 @@ public function getSelf()
             $this->get(self::BASE)
         );
     }
+
+    /**
+     * This returns all the friends of the current authenticated user.
+     *
+     * @param int $offset [optional] offset for pagination
+     * @param int $limit  [optional] limit for pagination
+     *
+     * @return array
+     * @see FriendService::getFriends()
+     */
+    public function getFriends($offset = 0, $limit = self::DEFAULT_PAGINATION_LIMIT)
+    {
+        $offset = intval($offset) === 0 ? 0 : intval($offset);
+        $limit = intval($limit) === 0 ? self::DEFAULT_PAGINATION_LIMIT : intval($limit);
+
+        return $this->createResponse($this->get("/friends?offset={$offset}&limit={$limit}"));
+    }
 }