diff --git a/README.md b/README.md index 2579dba..5e92ea3 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Install using Composer: `"emilh91/groupme-api-client": "dev-master"` ### Boilerplate -Your GroupMe API key can be found on the page mentioned above once you are logged in. +Your GroupMe API key can be found on the page mentioned above once you are logged in. You do not need to specify an API key if you only plan to use this library for **sending bot messages**. ```php require 'vendor/autoload.php'; $c = new GroupMeApi\Client('API-KEY'); @@ -20,6 +20,7 @@ All the methods in the following sub-sections should be invoked on the newly cre public function getMyBots() public function createBot($bot_name, $group_id, $avatar_url='', $callback_url='') public function sendBotMessage($bot_id, $text, array $attachments=array()) +public function parseBotMessage($bot_id, $text) public function destroyBot($bot_id) ``` @@ -29,7 +30,8 @@ public function getDirectMessageChats($page=1, $per_page=10) public function getLatestDirectMessages($other_user_id, $limit=20) public function getDirectMessagesBefore($other_user_id, $message_id) public function getDirectMessagesSince($other_user_id, $message_id) -public function sendDirectMessage($other_user_id, $text, $source_guid=null, array $attachments=array()) +public function sendDirectMessage($other_user_id, $text, array $attachments=array(), $source_guid=null) +public function parseDirectMessage($other_user_id, $text, $source_guid=null) public function likeDirectMessage($other_user_id, $message_id) public function unlikeDirectMessage($other_user_id, $message_id) ``` @@ -42,7 +44,7 @@ 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) +public function getGroupDetails($group) public function updateGroupDetails($group_id, array $payload) public function destroyGroup($group_id) public function joinGroup($group_id, $share_token) @@ -62,11 +64,12 @@ 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 getGroupNameById($id) -public function getGroupIdByName($name) -public function getGroupMemberId($group_id, $name, $caseSensitive = FALSE) -public function isMemberOfGroup($grp) +public function getGroupNameById($group_id) +public function getGroupIdByName($group_name) +public function getGroupMemberId($group_id, $group_name, $caseSensitive = FALSE) +public function isMemberOfGroup($group_id) public function sendGroupMessage($group_id, $text, array $attachments=array(), $source_guid=null) +public function parseGroupMessage($group_id, $text, $source_guid=null) ``` ##### User methods @@ -88,20 +91,18 @@ public static function makeEmojiAttachment(array $charmap) ``` ### Emojis -Aah, the pinnacle of modern communication... To send emojis in GroupMe, you need to specify a charmap (character map) when creating the attachment. For this purpose, another factory class exists: `GroupMeApi\EmojiUtils`. +Aah, the pinnacle of modern communication... ~~To send emojis in GroupMe, you need to specify a charmap (character map) when creating the attachment. For this purpose, another factory class exists: `GroupMeApi\EmojiUtils`.~~ To send emojis without dealing with charmaps and placeholders, just write them inline and use the `parse*Message(...)` methods to send them. ```php require 'vendor/autoload.php'; $c = new GroupMeApi\Client('API-KEY'); - -$raw_text = 'Hello :cool_guy_face::cigar_face:'; -$emojification = GroupMeApi\EmojiUtils::extractEmojiNamesFromText($raw_text); // returns an array -$emoji_attachment = GroupMeApi\AttachmentUtils::makeEmojiAttachment($emojification['charmap']); -$c->sendDirectMessage('OTHER-USER-ID', $emojification['text'], null, array($emoji_attachment)); +$c->parseBotMessage('BOT-ID', 'Awaiting instructions... :frustrated_face:'); +$c->parseDirectMessage('OTHER-USER-ID', 'Hello :cool_guy_face::cigar_face:'); +$c->parseGroupMessage('GROUP-ID', 'Hello everyone! :smiley_face::content_face:'); ``` ### Image Service -Before using images in messages you have to upload an image to GroupMe's image service. +Before using local images in messages you have to upload an image to GroupMe's image service. ```php require 'vendor/autoload.php'; @@ -109,6 +110,5 @@ $c = new GroupMeApi\Client('API-KEY'); $res = $c->uploadImage('my_image_file.png', 'image/png', 'testpic'); ``` -If the upload was successfull, the return variable contains the image url in `$res['payload']['url']` or an error message in `$res['error'][]`. - +If the upload was successful, the return variable contains the image url in `$res['payload']['url']` or an error message in `$res['error'][]`. Thanks to user [rgaida](https://github.com/rgaida) for fixing the image service! diff --git a/src/Client.php b/src/Client.php index 3f18644..7b8c4e0 100644 --- a/src/Client.php +++ b/src/Client.php @@ -16,7 +16,7 @@ class Client { /** * Maximum length of group descriptions */ - const MAX_GRP_DESC_LEN = 255; + const MAX_GROUP_DESC_LEN = 255; const HTTP_OK = 200; const HTTP_BAD_REQUEST = 400; @@ -105,6 +105,21 @@ public function sendBotMessage($bot_id, $text, array $attachments = array()) { ); return $this->post('/bots/post', $payload); } + + /** + * Parses the message text and then sends it from a bot + * + * @param int $bot_id Bot id + * @param string $text Message text + * + * @return mixed + */ + public function parseBotMessage($bot_id, $text) { + $emojification = \GroupMeApi\EmojiUtils::extractEmojiNamesFromText($text); + $emoji_attachment = \GroupMeApi\AttachmentUtils::makeEmojiAttachment($emojification['charmap']); + + return $this->sendBotMessage($bot_id, $emojification['text'], array($emoji_attachment)); + } /** * Destroys a bot @@ -236,6 +251,23 @@ public function sendDirectMessage($other_user_id, $text, array $attachments=arra $payload = array('direct_message' => $message_info); return $this->post('/direct_messages', $payload); } + + /** + * Parses the message text and then sends it to another user + * + * @param int $other_user_id The other participant + * @param string $text Message text + * @param string $source_guid Unique id + * + * @return mixed + */ + public function parseDirectMessage($other_user_id, $text, $source_guid=null) { + $emojification = \GroupMeApi\EmojiUtils::extractEmojiNamesFromText($text); + $emoji_attachment = \GroupMeApi\AttachmentUtils::makeEmojiAttachment($emojification['charmap']); + + return $this->sendDirectMessage($other_user_id, $emojification['text'], + array($emoji_attachment), $source_guid); + } /** * Likes a message @@ -269,21 +301,21 @@ public function unlikeDirectMessage($other_user_id, $message_id) { * Checks if the authenticated user is a member * of a certain group * - * @param mixed $grp Group name or group id + * @param mixed $group Group name or group id * * @return bool */ - public function isMemberOfGroup($grp) { + public function isMemberOfGroup($group) { $res = $this->getAllGroups(); if($res['meta']['code'] == self::HTTP_OK) { - foreach($res['response'] as $group) { - if ((is_numeric($grp) && $group['id'] == $grp) || - (is_string($grp) && $group['name'] == $grp)) return TRUE; + foreach($res['response'] as $g) { + if ((is_numeric($group) && $g['id'] == $group) || + (is_string($group) && $g['name'] == $group)) return true; } } - return FALSE; + return false; } /** @@ -404,7 +436,7 @@ public function createGroup($name, $description='', $image_url='', $share=false) self::MAX_PRI_NAME_LEN) ? strlen($name) : self::MAX_PRI_NAME_LEN), 'description' => substr($description, 0, (strlen($description) <= - self::MAX_GRP_DESC_LEN) ? strlen($description) : self::MAX_GRP_DESC_LEN), + self::MAX_GROUP_DESC_LEN) ? strlen($description) : self::MAX_GROUP_DESC_LEN), 'image_url' => $image_url, 'share' => boolval($share) @@ -716,8 +748,8 @@ public function getGroupMessagesSince($group_id, $message_id, $limit=20) { * * @return mixed */ - public function sendGroupMessage($group_id, $text, $source_guid=null, - array $attachments=array()) { + public function sendGroupMessage($group_id, $text, array $attachments=array(), + $source_guid=null) { $attachments = $this->verifyAttachments($attachments); @@ -729,6 +761,23 @@ public function sendGroupMessage($group_id, $text, $source_guid=null, $payload = array('message' => $message_info); return $this->post("/groups/$group_id/messages", $payload); } + + /** + * Parses the message text and then sends it to a group + * + * @param int $group_id Group id + * @param string $text Message text + * @param string $source_guid Unique id + * + * @return mixed + */ + public function parseGroupMessage($group_id, $text, $source_guid=null) { + $emojification = \GroupMeApi\EmojiUtils::extractEmojiNamesFromText($text); + $emoji_attachment = \GroupMeApi\AttachmentUtils::makeEmojiAttachment($emojification['charmap']); + + return $this->sendGroupMessage($group_id, $emojification['text'], + array($emoji_attachment), $source_guid); + } // USER METHODS @@ -795,19 +844,21 @@ public function disableSmsMode() { * Looks up a member's id within a group * * @param int $group_id Group id - * @param string $name Member name + * @param string $member_name Member name * @param bool $caseSensitive Name is case sensitive (default NO) * - * @return mixed Member id or FALSE if not found + * @return mixed Member id or FALSE if not found */ - public function getGroupMemberId($group_id, $name, $caseSensitive = FALSE) { + public function getGroupMemberId($group_id, $member_name, $caseSensitive = FALSE) { $group_members = $this->getGroupMembers($group_id); - $name = (!$caseSensitive) ? strtolower($name) : $name; + $member_name = (!$caseSensitive) ? strtolower($member_name) : $member_name; + + foreach ($group_members as $group_member) { + $group_member_name = (!$caseSensitive) ? + strtolower($group_member['nickname']) : $group_member['nickname']; - foreach ($group_members as $member) { - $member_name = (!$caseSensitive) ? strtolower($member['nickname']) : $member['nickname']; - if ($member_name == $name) return $member['user_id']; + if ($member_name == $group_member_name) return $group_member['user_id']; } return FALSE; @@ -1017,7 +1068,7 @@ private function getFromCache($key) { * Clears the cache */ public function clearCache() { - $this->cache = NULL; + $this->cache = array(); } /**