Merge pull request emilh91#5 from rgaida/master

Basic API request caching and minor functional changes

README.md

@@ -36,7 +36,10 @@ public function unlikeDirectMessage($other_user_id, $message_id)
 
 ##### Group methods
 ```php
-public function getAllGroups($page=1, $per_page=10)
+public function getAllGroups()
+public function getGroups($page = 1, $per_page = 10)
+public function getGroupByName($name)
+public function getGroupById($group_id)
 public function getFormerGroups()
 public function createGroup($name, $description='', $image_url='', $share=false)
 public function getGroupDetails($group_id)
@@ -51,14 +54,18 @@ public function getLeaderboardForMonth($group_id)
 public function getMyLikes($group_id)
 public function getMyHits($group_id)
 public function addMembersToGroup($group_id, array $members)
+public function getAddMembersToGroupResult($group_id, $results_id)
+public function getGroupMembers($group_id)
 public function updateMyGroupMembership($group_id, $nickname)
-public function getGroupMembers($group_id, $results_id)
 public function removeGroupMember($group_id, $user_id)
 public function getLatestGroupMessages($group_id, $limit=20)
 public function getGroupMessagesBefore($group_id, $message_id, $limit=20)
 public function getGroupMessagesAfter($group_id, $message_id, $limit=20)
 public function getGroupMessagesSince($group_id, $message_id, $limit=20)
-public function sendGroupMessage($group_id, $text, $source_guid=null, array $attachments=array())
+public function getGroupNameById($id)
+public function getGroupIdByName($name)
+public function isMemberOfGroup($grp)
+public function sendGroupMessage($group_id, $text, array $attachments=array(), $source_guid=null)
 ```
 
 ##### User methods
@@ -74,6 +81,7 @@ When sending messages (bot, direct, or group), you can specify an array of attac
 ```php
 public static function makeLocationAttachment($lat, $lng, $name='')
 public static function makeImageAttachment($image_url)
+public static function makeMentionsAttachment($users, $strpos)
 public static function makeSplitAttachment()
 public static function makeEmojiAttachment(array $charmap)
 ```

src/AttachmentUtils.php

@@ -4,6 +4,15 @@
 class AttachmentUtils {
     private function __construct() {}
 
+    /**
+     * GroupMe Location Attachment
+     * 
+     * @param float $lat Latitude
+     * @param float $lng Longitude
+     * @param string $name Location description or name
+     * 
+     * @return string[]
+     */
     public static function makeLocationAttachment($lat, $lng, $name='') {
         return array(
             'type' => 'location',
@@ -13,20 +22,83 @@ public static function makeLocationAttachment($lat, $lng, $name='') {
         );
     }
 
+    /**
+     * GroupMe Mentions Attachment
+     * 
+     * $strpos needs a tuple for each user id with the first item consisting of 
+     * the index of the start of the mention, and the second item is the length 
+     * of the mention text
+     * 
+     * @param int[] $users Array of user ids to mention
+     * @param int[] $strpos Text positions of user names to highlight
+     * 
+     * @return array
+     */
+    public static function makeMentionsAttachment($users, $strpos) {
+        return array(
+            'type' => 'mentions',
+            'user_ids' => $users,
+            'loci' => $strpos
+        );
+    }
+
+    /**
+     * Gets text position tuples for the mentions attachment
+     * 
+     * @param mixed $txt       Message text including user mention(s)
+     * @param mixed $usernames User name(s) of mentioned user(s)
+     * @param mixed $mchar     Mention indicator (typically "@")
+     * 
+     * @return array[] Position and length of user names in message
+     */
+    public static function getUsernamePositions($txt, $usernames, $mchar = '@') {
+        $loci = array();
+
+        foreach ($usernames as $username) {
+            $mention = $mchar . $username;
+            $pos = strpos($txt, $mention);
+
+            if ($pos === FALSE) break;
+
+            $loci[] = array($pos, strlen($mention));
+        }
+
+        return $loci;
+    }
+
+    /**
+     * GroupMe Image Attachment
+     * 
+     * @param string $image_url GroupMe Image Service URL
+     * 
+     * @return array
+     */
     public static function makeImageAttachment($image_url) {
         return array(
             'type' => 'image',
             'url' => $image_url,
         );
     }
 
+    /**
+     * Summary of makeSplitAttachment
+     * 
+     * @return string[]
+     */
     public static function makeSplitAttachment() {
         return array(
             'type' => 'split',
             'token' => 'SPLIT_TOKEN',
         );
     }
 
+    /**
+     * GroupMe Emoji Attachment
+     * 
+     * @param array $charmap 
+     * 
+     * @return array
+     */
     public static function makeEmojiAttachment(array $charmap) {
         return array(
             'type' => 'emoji',