├── example ├── outgoing └── incoming ├── CHANGELOG.md ├── LICENSE.md ├── src ├── MessageDefaults.php ├── Client.php └── Message.php ├── composer.json ├── README_zh.md └── README.md /example/outgoing: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env php 2 | text('Response Text') 10 | ->add('Response Attachment'); 11 | 12 | echo json_encode($message); 13 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Release Notes 2 | 3 | ## 1.3.1 (2017-09-04) 4 | 5 | - Add `Message::setClient` 6 | 7 | ## 1.3.0 (2017-09-02) 8 | 9 | - Add `MessageDefaults::allKeys` 10 | - Add `getTarget`, `setTarget`, `target`, `removeTarget` methods to `Message` 11 | - Add `Message::content` 12 | - `addImage` accepts $title as third parameter 13 | - Refactor `Message::configureDefaults` and change it to public 14 | 15 | ## 1.2.0 (2017-08-28) 16 | 17 | - Add `Message::addImage` method 18 | -------------------------------------------------------------------------------- /example/incoming: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env php 2 | send('hello to default target'); 14 | 15 | $client 16 | ->to('@elf') 17 | ->text('Hello, all') 18 | ->add('This is an attachment') 19 | ->addImage($imageUrl, 'Image Description') 20 | ->send(); 21 | 22 | $client->sendTo('all', 23 | '**markdown** content', 24 | 'attachment content', 25 | 'attachment title', 26 | $imageUrl 27 | ); 28 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # The MIT License (MIT) 2 | 3 | Copyright (c) 2016-2019 Elf Sundae 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /src/MessageDefaults.php: -------------------------------------------------------------------------------- 1 | getConstants()); 46 | } 47 | 48 | return $allKeys; 49 | } 50 | } 51 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "elfsundae/bearychat", 3 | "description": "An elegant way of interacting with BearyChat webhooks.", 4 | "keywords": ["bearychat", "incoming", "webhook", "outgoing", "robot"], 5 | "homepage": "https://github.com/ElfSundae/bearychat", 6 | "license": "MIT", 7 | "authors": [ 8 | { 9 | "name": "Elf Sundae", 10 | "email": "elf.sundae@gmail.com", 11 | "homepage": "https://0x123.com" 12 | } 13 | ], 14 | "require": { 15 | "php": ">=5.6.0", 16 | "ext-mbstring": "*", 17 | "guzzlehttp/guzzle": "~5.3|~6.0" 18 | }, 19 | "require-dev": { 20 | "mockery/mockery": "~0.9|~1.0", 21 | "phpunit/phpunit": "~5.7|~6.0|~7.0" 22 | }, 23 | "autoload": { 24 | "psr-4": { 25 | "ElfSundae\\BearyChat\\": "src/" 26 | } 27 | }, 28 | "autoload-dev": { 29 | "psr-4": { 30 | "ElfSundae\\BearyChat\\Test\\": "tests/" 31 | } 32 | }, 33 | "scripts": { 34 | "test": "vendor/bin/phpunit" 35 | }, 36 | "suggest": { 37 | "elfsundae/laravel-bearychat": "Required for Laravel integration.", 38 | "laravel-notification-channels/bearychat": "BearyChat notifications channel for Laravel 5." 39 | } 40 | } 41 | -------------------------------------------------------------------------------- /src/Client.php: -------------------------------------------------------------------------------- 1 | setWebhook($webhook); 41 | $this->setMessageDefaults($messageDefaults); 42 | $this->httpClient = $httpClient; 43 | } 44 | 45 | /** 46 | * Get the webhook. 47 | * 48 | * @return string 49 | */ 50 | public function getWebhook() 51 | { 52 | return $this->webhook; 53 | } 54 | 55 | /** 56 | * Set the webhook. 57 | * 58 | * @param string $webhook 59 | * @return $this 60 | */ 61 | public function setWebhook($webhook) 62 | { 63 | $this->webhook = $webhook; 64 | 65 | return $this; 66 | } 67 | 68 | /** 69 | * Change the webhook URL. 70 | * 71 | * @param string $webhook 72 | * @return $this 73 | */ 74 | public function webhook($webhook) 75 | { 76 | return $this->setWebhook($webhook); 77 | } 78 | 79 | /** 80 | * Retrieve message defaults. 81 | * 82 | * @param string|null $key 83 | * @return mixed 84 | */ 85 | public function getMessageDefaults($key = null) 86 | { 87 | if (is_null($key)) { 88 | return $this->messageDefaults; 89 | } 90 | 91 | if (isset($this->messageDefaults[$key])) { 92 | return $this->messageDefaults[$key]; 93 | } 94 | } 95 | 96 | /** 97 | * Set the message defaults. 98 | * 99 | * @param array $defaults 100 | * @return $this 101 | */ 102 | public function setMessageDefaults($defaults) 103 | { 104 | $this->messageDefaults = (array) $defaults; 105 | 106 | return $this; 107 | } 108 | 109 | /** 110 | * Set the message defaults. 111 | * 112 | * @param array $defaults 113 | * @return $this 114 | */ 115 | public function messageDefaults($defaults) 116 | { 117 | return $this->setMessageDefaults($defaults); 118 | } 119 | 120 | /** 121 | * Create a new Message instance. 122 | * 123 | * @return \ElfSundae\BearyChat\Message 124 | */ 125 | public function createMessage() 126 | { 127 | return new Message($this); 128 | } 129 | 130 | /** 131 | * Send message to the BearyChat. 132 | * 133 | * @param mixed $message A JSON string, or any arrayable object. 134 | * @return bool 135 | */ 136 | public function sendMessage($message) 137 | { 138 | if ($payload = $this->getJsonPayload($message)) { 139 | $response = $this->getHttpClient() 140 | ->post($this->getWebhook(), [ 141 | 'headers' => ['Content-Type' => 'application/json'], 142 | 'body' => $payload, 143 | ]); 144 | 145 | return 200 === $response->getStatusCode(); 146 | } 147 | 148 | return false; 149 | } 150 | 151 | /** 152 | * Get the JSON payload from an object. 153 | * 154 | * @param mixed $message 155 | * @return string 156 | */ 157 | protected function getJsonPayload($message) 158 | { 159 | if (is_array($message) || $message instanceof JsonSerializable) { 160 | return json_encode($message); 161 | } elseif (method_exists($message, 'toJson')) { 162 | return $message->toJson(); 163 | } elseif (method_exists($message, 'toArray')) { 164 | return json_encode($message->toArray()); 165 | } elseif (is_string($message) && is_array(json_decode($message, true))) { 166 | return $message; 167 | } 168 | } 169 | 170 | /** 171 | * Get the http client. 172 | * @return \GuzzleHttp\Client 173 | */ 174 | public function getHttpClient() 175 | { 176 | if (! $this->httpClient instanceof HttpClient) { 177 | $this->httpClient = new HttpClient; 178 | } 179 | 180 | return $this->httpClient; 181 | } 182 | 183 | /** 184 | * Any unhandled methods will be sent to a new Message instance. 185 | * 186 | * @param string $name 187 | * @param array $args 188 | * @return mixed 189 | */ 190 | public function __call($name, $args) 191 | { 192 | $message = $this->createMessage(); 193 | 194 | return call_user_func_array([$message, $name], $args); 195 | } 196 | } 197 | -------------------------------------------------------------------------------- /README_zh.md: -------------------------------------------------------------------------------- 1 | # BearyChat for PHP 2 | 3 | [![Latest Version on Packagist](https://img.shields.io/packagist/v/elfsundae/bearychat.svg?style=flat-square)](https://packagist.org/packages/elfsundae/bearychat) 4 | [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md) 5 | [![Build Status](https://img.shields.io/travis/ElfSundae/bearychat/master.svg?style=flat-square)](https://travis-ci.org/ElfSundae/bearychat) 6 | [![StyleCI](https://styleci.io/repos/62389995/shield)](https://styleci.io/repos/62389995) 7 | [![SensioLabsInsight](https://img.shields.io/sensiolabs/i/830f8475-95b1-4353-a8e1-d19a1a3e16b3.svg?style=flat-square)](https://insight.sensiolabs.com/projects/830f8475-95b1-4353-a8e1-d19a1a3e16b3) 8 | [![Quality Score](https://img.shields.io/scrutinizer/g/ElfSundae/bearychat.svg?style=flat-square)](https://scrutinizer-ci.com/g/ElfSundae/bearychat) 9 | [![Code Coverage](https://img.shields.io/scrutinizer/coverage/g/ElfSundae/bearychat/master.svg?style=flat-square)](https://scrutinizer-ci.com/g/ElfSundae/bearychat/?branch=master) 10 | [![Total Downloads](https://img.shields.io/packagist/dt/elfsundae/bearychat.svg?style=flat-square)](https://packagist.org/packages/elfsundae/bearychat) 11 | 12 | 这是一个用于向 [BearyChat][] 发送 [Incoming][incoming] 消息、创建 [Outgoing][outgoing] 响应的 PHP 扩展包。 13 | 14 | - :us: [**Documentation in English**](README.md) 15 | - **Laravel 集成:** [BearyChat for Laravel](https://github.com/ElfSundae/laravel-bearychat) 16 | - **Laravel Notification Channel:** [BearyChatChannel](https://github.com/laravel-notification-channels/bearychat) 17 | - **Yii 集成:** [BearyChat for Yii 2](https://github.com/krissss/yii2-beary-chart) 18 | 19 | ## 安装 20 | 21 | 你可以使用 [Composer][] 安装此扩展包： 22 | ``` 23 | composer require elfsundae/bearychat 24 | ``` 25 | 26 | 在你的 [BearyChat][] 团队账号下创建 Incoming 机器人，并阅读其[消息格式][incoming]。 27 | 28 | ## 文档 29 | 30 | ### 概述 31 | 32 | ```php 33 | (new Client('https://hook.bearychat.com/=...')) 34 | ->text('content') 35 | ->add('attachment', 'title') 36 | ->addImage($imageUrl, 'image description') 37 | ->sendTo('admin'); 38 | 39 | (new Client($webhook))->send('content', 'attachment'); 40 | ``` 41 | 42 | 要发送消息，首先需要创建一个 [BearyChat client](src/Client.php) ，并在其初始化方法中传入 webhook 的 URL: 43 | 44 | ```php 45 | $client = new ElfSundae\BearyChat\Client('http://hook.bearychat.com/=.../incoming/...'); 46 | ``` 47 | 48 | 除了 webhook URL ，你还可以为所有由这个 client 发出的消息预设一些默认值： 49 | 50 | ```php 51 | use ElfSundae\BearyChat\Client; 52 | 53 | $client = new Client($webhook, [ 54 | 'channel' => 'server-log', 55 | 'attachment_color' => '#3e4787' 56 | ]); 57 | ``` 58 | 59 | 所有支持的消息预设名 (key) 罗列在 [`MessageDefaults`](src/MessageDefaults.php) 类中。可以通过调用 `$client->getMessageDefaults($key)` 获取某个预设值，或者调用 `$client->getMessageDefaults()` （不传参数）来获取所有消息预设值。 60 | 61 | 要发送一条消息，只需调用 client 的 `sendMessage` 方法并传入[消息 payload][incoming] 数组或 JSON 字符串: 62 | 63 | ```php 64 | $client->sendMessage([ 65 | 'text' => 'Hi, Elf!', 66 | 'user' => 'elf' 67 | ]); 68 | 69 | $json = '{"text": "Good job :+1:", "channel": "all"}'; 70 | $client->sendMessage($json); 71 | ``` 72 | 73 | 除了原生的消息 payload ，`sendMessage` 还可以处理 `JsonSerializable` 实例，或任意通过其 `toArray` 或 `toJson` 方法提供 payload 的对象。同时该扩展包也提供了一个现成的 [`Message`](src/Message.php) 类用于创建 Incoming 消息，或生成 Outgoing 响应。`Message` 类有很多便捷方法用来[操作消息 payload](#编辑消息)。 74 | 75 | 为了方便使用，对 `Client` 实例的所有不支持的方法调用将被发送至一个新的 `Message` 对象，并且 `Message` 对象的绝大多数方法支持链接调用，这样就可以实现一行代码完成[编辑消息](#编辑消息)和[发送消息](#发送消息)。 76 | 77 | 另外，`Message` 对象还提供了两个强大的方法 `send` 和 `sendTo` 用来快速实现消息的编辑和发送。 78 | 79 | ```php 80 | $client->to('#all')->text('Hello')->add('World')->send(); 81 | 82 | $client->sendTo('all', 'Hello', 'World'); 83 | ``` 84 | 85 | ### 编辑消息 86 | 87 | `Message` 对象可用的编辑消息的方法如下： 88 | 89 | - **text**: `getText` , `setText($text)` , `text($text)` 90 | - **notification**: `getNotification` , `setNotification($notification)` , `notification($notification)` 91 | - **markdown**: `getMarkdown` , `setMarkdown($markdown)` , `markdown($markdown = true)` 92 | - **channel**: `getChannel` , `setChannel($channel)` , `channel($channel)` , `to($channel)` 93 | - **user**: `getUser` , `setUser($user)` , `user($user)` , `to('@'.$user)` 94 | - **target** (user or channel): `getTarget`, `setTarget($target)`, `target($target)`, `removeTarget`, `to($target)` 95 | - **attachments**: `getAttachments` , `setAttachments($attachments)` , `attachments($attachments)` , `addAttachment(...)` , `add(...)` , `addImage` , `removeAttachments(...)` , `remove(...)` 96 | - `content($text, $markdown, $notification)`, `content($text, $attachment_text, $attachment_title, $attachment_images, $attachment_color)` 97 | 98 | 如你所见，`to($target)` 方法可以改变消息的目标（接收方），如果参数 `$target` 是一个以 `@` 打头的字符串，消息将被发送至某个「人」（ user ），否则消息的目标将是一个「讨论组」（ channel ）。讨论组名字的打头字符 `#` 是可选的，这意味着 `to('#dev')` 和 `to('dev')` 效果一样。 99 | 100 | 方法 `addAttachment($attachment)` 可接受一个 PHP 数组 (attachment payload) 作为其参数，也可以是一个按照 `text, title, images, color` 顺序的可变参数，并且 `images` 可以是一个图片 URL 字符串也可以是一个包含图片 URL 的数组。`addAttachment` 的这种参数类型同样适应于 `add` 方法。 101 | 102 | ```php 103 | $client 104 | ->to('@elf') 105 | ->text('message') 106 | ->add([ 107 | 'text' => 'Content of the first attachment.', 108 | 'title' => 'First Attachment', 109 | 'images' => [$imageUrl, $imageUrl2], 110 | 'color' => '#10e4fe' 111 | ]) 112 | ->add( 113 | 'Content of the second attachment.', 114 | 'Second Attachment', 115 | [$imageUrl, $imageUrl2], 116 | 'red' 117 | ) 118 | ->send(); 119 | ``` 120 | 121 | 调用 `removeAttachments` 或 `remove` 方法并传入附件索引可以移除某附件。不传参数会移除消息里的所有附件。 122 | 123 | ```php 124 | $message->remove(0)->remove(0, 1)->remove([1, 3])->remove(); 125 | ``` 126 | 127 | ### 消息持久化 128 | 129 | 调用 `Message` 对象的 `toArray()` 方法可以得到这个消息的 payload 数组。也可以使用 `$message->toJson()`, `json_encode($message)` 或 `(string) $message` 得到 `$message` 的 JSON payload. 130 | 131 | > :warning: **消息 payload 可以被用来请求 [Incoming Webhook][incoming] 或响应 [Outgoing Robot][outgoing].** 132 | 133 | ```php 134 | $message = $client->to('@elf')->text('foo')->markdown(false) 135 | ->add('bar', 'some images', 'path/to/image', 'blue'); 136 | 137 | echo $message->toJson(JSON_PRETTY_PRINT); 138 | ``` 139 | 140 | 执行上面的代码会输出以下内容： 141 | 142 | ```json 143 | { 144 | "text": "foo", 145 | "markdown": false, 146 | "user": "elf", 147 | "attachments": [ 148 | { 149 | "text": "bar", 150 | "title": "some images", 151 | "images": [ 152 | { 153 | "url": "path\/to\/image" 154 | } 155 | ], 156 | "color": "blue" 157 | } 158 | ] 159 | } 160 | ``` 161 | 162 | ### 发送消息 163 | 164 | 调用 `Message` 对象的 `send` 或 `sendTo` 方法可以发送这条消息，并且这两个方法也接受可变参数以便快速修改消息内容。 165 | 166 | - 发送一条简单的消息: `send($text, $markdown = true, $notification)` 167 | - 发送一条带有附件的消息: `send($text, $attachment_text, $attachment_title, $attachment_images, $attachment_color)` 168 | 169 | `sendTo` 方法的第一个参数是要发送的目标，其他参数跟 `send` 方法的参数一样。 170 | 171 | ```php 172 | $client = new Client($webhook, [ 173 | 'channel' => 'all' 174 | ]); 175 | 176 | // Sending a message to the default channel 177 | $client->send('Hi there :smile:'); 178 | 179 | // Sending a customized message 180 | $client->send('disable **markdown**', false, 'custom notification'); 181 | 182 | // Sending a message with one attachment added 183 | $client->send('message title', 'Attachment Content'); 184 | 185 | // Sending a message with an customized attachment 186 | $client->send( 187 | 'message with an customized attachment', 188 | 'Attachment Content', 189 | 'Attachment Title', 190 | $imageUrl, 191 | '#f00' 192 | ); 193 | 194 | // Sending a message with multiple images 195 | $client->send('multiple images', null, null, [$imageUrl1, $imageUrl2]); 196 | 197 | // Sending a message to a different channel 198 | $client->sendTo('iOS', '**Lunch Time !!!**'); 199 | 200 | // Sending a message to an user 201 | $client->sendTo('@elf', 'Where are you?'); 202 | ``` 203 | 204 | ### 定制 Client 205 | 206 | 如果你想显式创建 `Message` 对象，client 的 `createMessage` 方法会返回一个全新的、带有消息预设值的 `Message` 对象。 207 | 208 | `Client` 对象是可变的，这意味着你可以通过调用 `setWebhook` 、`webhook` 或 `setMessageDefaults` 方法来改变 client 的 webhook URL 、消息的预设值等。 209 | 210 | ```php 211 | $client->webhook($webhook_ios)->setMessageDefaults([ 212 | 'channel' => 'ios_dev' 213 | ])->send('App reviewing status has updated.'); 214 | ``` 215 | 216 | ## 测试 217 | 218 | ```sh 219 | $ composer test 220 | ``` 221 | 222 | ## 许可协议 223 | 224 | BearyChat PHP 扩展包在 [MIT 许可协议](LICENSE)下提供和使用。 225 | 226 | [incoming]: https://bearychat.com/integrations/incoming 227 | [outgoing]: https://bearychat.com/integrations/outgoing 228 | [BearyChat]: https://bearychat.com 229 | [Composer]: https://getcomposer.org 230 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # BearyChat for PHP 2 | 3 | [![Latest Version on Packagist](https://img.shields.io/packagist/v/elfsundae/bearychat.svg?style=flat-square)](https://packagist.org/packages/elfsundae/bearychat) 4 | [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md) 5 | [![Build Status](https://img.shields.io/travis/ElfSundae/bearychat/master.svg?style=flat-square)](https://travis-ci.org/ElfSundae/bearychat) 6 | [![StyleCI](https://styleci.io/repos/62389995/shield)](https://styleci.io/repos/62389995) 7 | [![SensioLabsInsight](https://img.shields.io/sensiolabs/i/830f8475-95b1-4353-a8e1-d19a1a3e16b3.svg?style=flat-square)](https://insight.sensiolabs.com/projects/830f8475-95b1-4353-a8e1-d19a1a3e16b3) 8 | [![Quality Score](https://img.shields.io/scrutinizer/g/ElfSundae/bearychat.svg?style=flat-square)](https://scrutinizer-ci.com/g/ElfSundae/bearychat) 9 | [![Code Coverage](https://img.shields.io/scrutinizer/coverage/g/ElfSundae/bearychat/master.svg?style=flat-square)](https://scrutinizer-ci.com/g/ElfSundae/bearychat/?branch=master) 10 | [![Total Downloads](https://img.shields.io/packagist/dt/elfsundae/bearychat.svg?style=flat-square)](https://packagist.org/packages/elfsundae/bearychat) 11 | 12 | A PHP package for sending message to [BearyChat][] with the [Incoming Webhook][incoming], and creating response payload for the [Outgoing Robot][outgoing]. 13 | 14 | - :cn: [**中文文档**](README_zh.md) 15 | - **Laravel integration:** [BearyChat for Laravel](https://github.com/ElfSundae/laravel-bearychat) 16 | - **Laravel Notification Channel:** [BearyChatChannel](https://github.com/laravel-notification-channels/bearychat) 17 | - **Yii integration:** [BearyChat for Yii 2](https://github.com/krissss/yii2-beary-chart) 18 | 19 | ## Installation 20 | 21 | You can install this package using the [Composer][] manager. 22 | ``` 23 | composer require elfsundae/bearychat 24 | ``` 25 | 26 | Then you may create an Incoming Robot on your [BearyChat][] team account, and read the [payload format][incoming]. 27 | 28 | ## Documentation 29 | 30 | ### Overview 31 | 32 | ```php 33 | (new Client('https://hook.bearychat.com/=...')) 34 | ->text('content') 35 | ->add('attachment', 'title') 36 | ->addImage($imageUrl, 'image description') 37 | ->sendTo('admin'); 38 | 39 | (new Client($webhook))->send('content', 'attachment'); 40 | ``` 41 | 42 | To send messages, first create a [BearyChat client](src/Client.php) with your webhook URL: 43 | 44 | ```php 45 | $client = new ElfSundae\BearyChat\Client('http://hook.bearychat.com/=.../incoming/...'); 46 | ``` 47 | 48 | Besides the webhook, you may want to setup some default values for all messages which will be sent with this client: 49 | 50 | ```php 51 | use ElfSundae\BearyChat\Client; 52 | 53 | $client = new Client($webhook, [ 54 | 'channel' => 'server-log', 55 | 'attachment_color' => '#3e4787' 56 | ]); 57 | ``` 58 | 59 | All defaults keys are listed in [`MessageDefaults`](src/MessageDefaults.php) . You can access message default with `$client->getMessageDefaults($key)`, or retrieve all defaults with `$client->getMessageDefaults()` . 60 | 61 | To send a message, just call `sendMessage` on the client instance with a [message payload][incoming] array or a payload JSON string: 62 | 63 | ```php 64 | $client->sendMessage([ 65 | 'text' => 'Hi, Elf!', 66 | 'user' => 'elf' 67 | ]); 68 | 69 | $json = '{"text": "Good job :+1:", "channel": "all"}'; 70 | $client->sendMessage($json); 71 | ``` 72 | 73 | In addition to the ugly payload, `sendMessage` can handle any `JsonSerializable` instances or any object which provides a payload via its `toArray` or `toJson` method. And there is a ready-made [`Message`](src/Message.php) class available for creating payloads for Incoming messages or Outgoing responses. There are a variety of convenient methods that can work with the payload in [`Message`](src/Message.php) class. 74 | 75 | For convenience, any unhandled methods called to a `Client` instance will be sent to a new `Message` instance, and the most methods of a `Message` instance return itself, so you can chain [message modifications](#message-modifications) to achieve one-liner code. 76 | 77 | You can also call the powerful `send` or `sendTo` method with message contents for [sending a message](#sending-message). 78 | 79 | ```php 80 | $client->to('#all')->text('Hello')->add('World')->send(); 81 | 82 | $client->sendTo('all', 'Hello', 'World'); 83 | ``` 84 | 85 | ### Message Modifications 86 | 87 | Available methods for message modification in the `Message` class: 88 | 89 | - **text**: `getText` , `setText($text)` , `text($text)` 90 | - **notification**: `getNotification` , `setNotification($notification)` , `notification($notification)` 91 | - **markdown**: `getMarkdown` , `setMarkdown($markdown)` , `markdown($markdown = true)` 92 | - **channel**: `getChannel` , `setChannel($channel)` , `channel($channel)` , `to($channel)` 93 | - **user**: `getUser` , `setUser($user)` , `user($user)` , `to('@'.$user)` 94 | - **target** (user or channel): `getTarget`, `setTarget($target)`, `target($target)`, `removeTarget`, `to($target)` 95 | - **attachments**: `getAttachments` , `setAttachments($attachments)` , `attachments($attachments)` , `addAttachment(...)` , `add(...)` , `addImage` , `removeAttachments(...)` , `remove(...)` 96 | - `content($text, $markdown, $notification)`, `content($text, $attachment_text, $attachment_title, $attachment_images, $attachment_color)` 97 | 98 | As you can see, the `to($target)` method can change the message's target to an user if `$target` is started with `@` , otherwise it will set the channel that the message should be sent to. The channel's starter mark `#` is **optional** in `to` method, which means the result of `to('#dev')` and `to('dev')` is the same. 99 | 100 | Method `addAttachment($attachment)` accepts a PHP array of attachment payload, or a variable arguments list in order of `text, title, images, color`, and the `images` can be an image URL or an array contains image URLs. And this type of attachment parameters is also applicable to the method `add`. 101 | 102 | ```php 103 | $client 104 | ->to('@elf') 105 | ->text('message') 106 | ->add([ 107 | 'text' => 'Content of the first attachment.', 108 | 'title' => 'First Attachment', 109 | 'images' => [$imageUrl, $imageUrl2], 110 | 'color' => '#10e4fe' 111 | ]) 112 | ->add( 113 | 'Content of the second attachment.', 114 | 'Second Attachment', 115 | [$imageUrl, $imageUrl2], 116 | 'red' 117 | ) 118 | ->send(); 119 | ``` 120 | 121 | To remove attachments, call `removeAttachments` or `remove` with indices. 122 | 123 | ```php 124 | $message->remove(0)->remove(0, 1)->remove([1, 3])->remove(); 125 | ``` 126 | 127 | ### Message Representation 128 | 129 | Call the `toArray()` method on a Message instance will get the payload array for this message. You may use `$message->toJson()`, `json_encode($message)` or `(string) $message` to get the JSON payload for `$message`. 130 | 131 | > :warning: **The message payload may be used for requesting an [Incoming Webhook][incoming] or creating response for an [Outgoing Robot][outgoing].** 132 | 133 | ```php 134 | $message = $client->to('@elf')->text('foo')->markdown(false) 135 | ->add('bar', 'some images', 'path/to/image', 'blue'); 136 | 137 | echo $message->toJson(JSON_PRETTY_PRINT); 138 | ``` 139 | 140 | The above example will output: 141 | 142 | ```json 143 | { 144 | "text": "foo", 145 | "markdown": false, 146 | "user": "elf", 147 | "attachments": [ 148 | { 149 | "text": "bar", 150 | "title": "some images", 151 | "images": [ 152 | { 153 | "url": "path\/to\/image" 154 | } 155 | ], 156 | "color": "blue" 157 | } 158 | ] 159 | } 160 | ``` 161 | 162 | ### Sending Message 163 | 164 | You can call `send` or `sendTo` method on a Message instance to send that message. 165 | 166 | The `send` method optional accepts variable number of arguments to quickly change the payload content: 167 | 168 | - Sending a basic message: `send($text, $markdown = true, $notification)` 169 | - Sending a message with one attachment added: `send($text, $attachment_text, $attachment_title, $attachment_images, $attachment_color)` 170 | 171 | The `sendTo` method is useful when you want to change the message's target before calling `send` method. 172 | 173 | ```php 174 | $client = new Client($webhook, [ 175 | 'channel' => 'all' 176 | ]); 177 | 178 | // Sending a message to the default channel 179 | $client->send('Hi there :smile:'); 180 | 181 | // Sending a customized message 182 | $client->send('disable **markdown**', false, 'custom notification'); 183 | 184 | // Sending a message with one attachment added 185 | $client->send('message title', 'Attachment Content'); 186 | 187 | // Sending a message with an customized attachment 188 | $client->send( 189 | 'message with an customized attachment', 190 | 'Attachment Content', 191 | 'Attachment Title', 192 | $imageUrl, 193 | '#f00' 194 | ); 195 | 196 | // Sending a message with multiple images 197 | $client->send('multiple images', null, null, [$imageUrl1, $imageUrl2]); 198 | 199 | // Sending a message to a different channel 200 | $client->sendTo('iOS', '**Lunch Time !!!**'); 201 | 202 | // Sending a message to an user 203 | $client->sendTo('@elf', 'Where are you?'); 204 | ``` 205 | 206 | ### Customize Client 207 | 208 | If you want to create a `Message` instance explicitly, the client's `createMessage` method will return a fresh `Message` instance configured with the client's message defaults. 209 | 210 | A `Client` instance is mutable, it means you can change its webhook URL or the message defaults by calling `setWebhook`, `webhook` or `setMessageDefaults`. 211 | 212 | ```php 213 | $client->webhook($webhook_ios)->setMessageDefaults([ 214 | 'channel' => 'ios_dev' 215 | ])->send('App reviewing status has updated.'); 216 | ``` 217 | 218 | ## Testing 219 | 220 | ```sh 221 | $ composer test 222 | ``` 223 | 224 | ## License 225 | 226 | The BearyChat PHP package is available under the [MIT license](LICENSE). 227 | 228 | [incoming]: https://bearychat.com/integrations/incoming 229 | [outgoing]: https://bearychat.com/integrations/outgoing 230 | [BearyChat]: https://bearychat.com 231 | [Composer]: https://getcomposer.org 232 | -------------------------------------------------------------------------------- /src/Message.php: -------------------------------------------------------------------------------- 1 | setClient($client); 73 | } 74 | 75 | /** 76 | * Get the BearyChat client for sending message. 77 | * 78 | * @return \ElfSundae\BearyChat\Client 79 | */ 80 | public function getClient() 81 | { 82 | return $this->client; 83 | } 84 | 85 | /** 86 | * Set the BearyChat Client instance. 87 | * 88 | * @param \ElfSundae\BearyChat\Client|null $client 89 | * @return $this 90 | */ 91 | public function setClient($client) 92 | { 93 | if ($client instanceof Client && $this->client != $client) { 94 | $this->configureDefaults($client->getMessageDefaults(), true); 95 | } 96 | 97 | $this->client = $client; 98 | 99 | return $this; 100 | } 101 | 102 | /** 103 | * Get the text. 104 | * 105 | * @return string 106 | */ 107 | public function getText() 108 | { 109 | return $this->text; 110 | } 111 | 112 | /** 113 | * Set the text. 114 | * 115 | * @param string $text 116 | * @return $this 117 | */ 118 | public function setText($text) 119 | { 120 | $this->text = $text ? (string) $text : null; 121 | 122 | return $this; 123 | } 124 | 125 | /** 126 | * Set the text. 127 | * 128 | * @param string $text 129 | * @return $this 130 | */ 131 | public function text($text) 132 | { 133 | return $this->setText($text); 134 | } 135 | 136 | /** 137 | * Get the notification. 138 | * 139 | * @return string 140 | */ 141 | public function getNotification() 142 | { 143 | return $this->notification; 144 | } 145 | 146 | /** 147 | * Set the notification. 148 | * 149 | * @param string $notification 150 | * @return $this 151 | */ 152 | public function setNotification($notification) 153 | { 154 | $this->notification = $notification ? (string) $notification : null; 155 | 156 | return $this; 157 | } 158 | 159 | /** 160 | * Set the notification. 161 | * 162 | * @param string $notification 163 | * @return $this 164 | */ 165 | public function notification($notification) 166 | { 167 | return $this->setNotification($notification); 168 | } 169 | 170 | /** 171 | * Get the markdown. 172 | * 173 | * @return bool 174 | */ 175 | public function getMarkdown() 176 | { 177 | return $this->markdown; 178 | } 179 | 180 | /** 181 | * Set the markdown. 182 | * 183 | * @param bool $markdown 184 | * @return $this 185 | */ 186 | public function setMarkdown($markdown) 187 | { 188 | $this->markdown = (bool) $markdown; 189 | 190 | return $this; 191 | } 192 | 193 | /** 194 | * Set the markdown. 195 | * 196 | * @param bool $markdown 197 | * @return $this 198 | */ 199 | public function markdown($markdown = true) 200 | { 201 | return $this->setMarkdown($markdown); 202 | } 203 | 204 | /** 205 | * Get the channel which the message should be sent to. 206 | * 207 | * @return string 208 | */ 209 | public function getChannel() 210 | { 211 | return $this->channel; 212 | } 213 | 214 | /** 215 | * Set the channel which the message should be sent to. 216 | * 217 | * @param string $channel 218 | * @return $this 219 | */ 220 | public function setChannel($channel) 221 | { 222 | $this->removeTarget(); 223 | 224 | if ($channel) { 225 | $this->channel = (string) $channel; 226 | } 227 | 228 | return $this; 229 | } 230 | 231 | /** 232 | * Set the channel which the message should be sent to. 233 | * 234 | * @param string $channel 235 | * @return $this 236 | */ 237 | public function channel($channel) 238 | { 239 | return $this->setChannel($channel); 240 | } 241 | 242 | /** 243 | * Get the user which the message should be sent to. 244 | * 245 | * @return string 246 | */ 247 | public function getUser() 248 | { 249 | return $this->user; 250 | } 251 | 252 | /** 253 | * Set the user which the message should be sent to. 254 | * 255 | * @param string $user 256 | * @return $this 257 | */ 258 | public function setUser($user) 259 | { 260 | $this->removeTarget(); 261 | 262 | if ($user) { 263 | $this->user = (string) $user; 264 | } 265 | 266 | return $this; 267 | } 268 | 269 | /** 270 | * Set the user which the message should be sent to. 271 | * 272 | * @param string $user 273 | * @return $this 274 | */ 275 | public function user($user) 276 | { 277 | return $this->setUser($user); 278 | } 279 | 280 | /** 281 | * Get the target that the message should be sent to: 282 | * `#channel` or `@user` or null. 283 | * 284 | * @return string 285 | */ 286 | public function getTarget() 287 | { 288 | if ($this->channel) { 289 | return '#'.$this->channel; 290 | } 291 | 292 | if ($this->user) { 293 | return '@'.$this->user; 294 | } 295 | } 296 | 297 | /** 298 | * Set the target (user or channel) that the message should be sent to. 299 | * 300 | * @param string $target @user, #channel, channel, null 301 | * @return $this 302 | */ 303 | public function setTarget($target) 304 | { 305 | $this->removeTarget(); 306 | 307 | if ($target = (string) $target) { 308 | $mark = mb_substr($target, 0, 1); 309 | $to = mb_substr($target, 1); 310 | 311 | if ($mark === '@') { 312 | $this->setUser($to); 313 | } elseif ($mark === '#') { 314 | $this->setChannel($to); 315 | } else { 316 | $this->setChannel($target); 317 | } 318 | } 319 | 320 | return $this; 321 | } 322 | 323 | /** 324 | * Remove the target, then this message will be sent to 325 | * the webhook defined target. 326 | * 327 | * @return $this 328 | */ 329 | public function removeTarget() 330 | { 331 | $this->channel = $this->user = null; 332 | 333 | return $this; 334 | } 335 | 336 | /** 337 | * Set the target. 338 | * 339 | * @param string $target 340 | * @return $this 341 | */ 342 | public function target($target) 343 | { 344 | return $this->setTarget($target); 345 | } 346 | 347 | /** 348 | * Set the target. 349 | * 350 | * @param string $target 351 | * @return $this 352 | */ 353 | public function to($target) 354 | { 355 | return $this->setTarget($target); 356 | } 357 | 358 | /** 359 | * Get the attachments defaults. 360 | * 361 | * @return array 362 | */ 363 | public function getAttachmentDefaults() 364 | { 365 | return $this->attachmentDefaults; 366 | } 367 | 368 | /** 369 | * Set the attachments defaults. 370 | * 371 | * @param array $defaults 372 | * @return $this 373 | */ 374 | public function setAttachmentDefaults($defaults) 375 | { 376 | if ($this->attachmentDefaults != ($defaults = (array) $defaults)) { 377 | $this->attachmentDefaults = $defaults; 378 | 379 | $this->setAttachments($this->attachments); 380 | } 381 | 382 | return $this; 383 | } 384 | 385 | /** 386 | * Get the attachments for the message. 387 | * 388 | * @return array 389 | */ 390 | public function getAttachments() 391 | { 392 | return $this->attachments; 393 | } 394 | 395 | /** 396 | * Set the attachments for the message. 397 | * 398 | * @param mixed $attachments 399 | * @return $this 400 | */ 401 | public function setAttachments($attachments) 402 | { 403 | $this->removeAttachments(); 404 | 405 | if (is_array($attachments)) { 406 | foreach ($attachments as $attachment) { 407 | $this->addAttachment($attachment); 408 | } 409 | } 410 | 411 | return $this; 412 | } 413 | 414 | /** 415 | * Set the attachments for the message. 416 | * 417 | * @param mixed $attachments 418 | * @return $this 419 | */ 420 | public function attachments($attachments) 421 | { 422 | return $this->setAttachments($attachments); 423 | } 424 | 425 | /** 426 | * Add an attachment to the message. 427 | * 428 | * The parameter can be an payload array that contains all of attachment's fields. 429 | * The parameters can also be attachment's fields that in order of 430 | * text, title, images and color. Except the text, other parameters 431 | * can be ignored. 432 | * 433 | * @param mixed $attachment 434 | * @return $this 435 | */ 436 | public function addAttachment($attachment) 437 | { 438 | if (! is_array($attachment)) { 439 | $attachment = call_user_func_array([$this, 'getAttachmentPayload'], func_get_args()); 440 | } elseif ( 441 | ! empty($attachment['images']) && 442 | $images = $this->getImagesPayload($attachment['images']) 443 | ) { 444 | $attachment['images'] = $images; 445 | } 446 | 447 | if (! empty($attachment)) { 448 | $attachment += $this->attachmentDefaults; 449 | 450 | $this->attachments[] = $attachment; 451 | } 452 | 453 | return $this; 454 | } 455 | 456 | /** 457 | * Get payload for an attachment. 458 | * 459 | * @param mixed $text 460 | * @param mixed $title 461 | * @param mixed $images 462 | * @param mixed $color 463 | * @return array 464 | */ 465 | protected function getAttachmentPayload($text = null, $title = null, $images = null, $color = null) 466 | { 467 | $attachment = []; 468 | 469 | if ($text) { 470 | $attachment['text'] = $this->stringValue($text); 471 | } 472 | 473 | if ($title) { 474 | $attachment['title'] = $this->stringValue($title); 475 | } 476 | 477 | if ($images = $this->getImagesPayload($images)) { 478 | $attachment['images'] = $images; 479 | } 480 | 481 | if ($color) { 482 | $attachment['color'] = (string) $color; 483 | } 484 | 485 | return $attachment; 486 | } 487 | 488 | /** 489 | * Get payload for images. 490 | * 491 | * @param mixed $value 492 | * @return array 493 | */ 494 | protected function getImagesPayload($value) 495 | { 496 | $images = []; 497 | 498 | foreach ((array) $value as $img) { 499 | if (! empty($img['url'])) { 500 | $img = $img['url']; 501 | } 502 | 503 | if (is_string($img) && ! empty($img)) { 504 | $images[] = ['url' => $img]; 505 | } 506 | } 507 | 508 | return $images; 509 | } 510 | 511 | /** 512 | * Convert any type to string. 513 | * 514 | * @param mixed $value 515 | * @param int $jsonOptions 516 | * @return string 517 | */ 518 | protected function stringValue($value, $jsonOptions = JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) 519 | { 520 | if (is_string($value)) { 521 | return $value; 522 | } 523 | 524 | if (method_exists($value, '__toString')) { 525 | return (string) $value; 526 | } 527 | 528 | if (method_exists($value, 'toArray')) { 529 | $value = $value->toArray(); 530 | } 531 | 532 | return json_encode($value, $jsonOptions); 533 | } 534 | 535 | /** 536 | * Add an attachment to the message. 537 | * It alias to `addAttachment`. 538 | * 539 | * @return $this 540 | */ 541 | public function add() 542 | { 543 | return call_user_func_array([$this, 'addAttachment'], func_get_args()); 544 | } 545 | 546 | /** 547 | * Add an image attachment to the message. 548 | * 549 | * @param string|string[] $image 550 | * @param string $desc 551 | * @param string $title 552 | * @return $this 553 | */ 554 | public function addImage($image, $desc = null, $title = null) 555 | { 556 | return $this->addAttachment($desc, $title, $image); 557 | } 558 | 559 | /** 560 | * Remove attachment[s] for the message. 561 | * 562 | * @return $this 563 | */ 564 | public function removeAttachments() 565 | { 566 | if (func_num_args() > 0) { 567 | $indices = is_array(func_get_arg(0)) ? func_get_arg(0) : func_get_args(); 568 | 569 | foreach ($indices as $index) { 570 | unset($this->attachments[$index]); 571 | } 572 | 573 | $this->attachments = array_values($this->attachments); 574 | } else { 575 | $this->attachments = []; 576 | } 577 | 578 | return $this; 579 | } 580 | 581 | /** 582 | * Remove attachment[s] for the message. 583 | * It alias to `removeAttachments`. 584 | * 585 | * @return $this 586 | */ 587 | public function remove() 588 | { 589 | return call_user_func_array([$this, 'removeAttachments'], func_get_args()); 590 | } 591 | 592 | /** 593 | * Configure message defaults. 594 | * 595 | * @param array $defaults 596 | * @param bool $force 597 | * @return $this 598 | */ 599 | public function configureDefaults(array $defaults, $force = false) 600 | { 601 | if ($force || empty($this->toArray())) { 602 | $attachmentDefaults = $this->attachmentDefaults; 603 | 604 | foreach (MessageDefaults::allKeys() as $key) { 605 | if (isset($defaults[$key]) && ! is_null($value = $defaults[$key])) { 606 | if (strpos($key, 'attachment_') !== false) { 607 | if ($key = substr($key, strlen('attachment_'))) { 608 | $attachmentDefaults[$key] = $value; 609 | } 610 | } else { 611 | $this->fillDefaults($key, $value); 612 | } 613 | } 614 | } 615 | 616 | $this->setAttachmentDefaults($attachmentDefaults); 617 | } 618 | 619 | return $this; 620 | } 621 | 622 | /** 623 | * Fill with message defaults. 624 | * 625 | * @param string $key 626 | * @param mixed $value 627 | * @return void 628 | */ 629 | protected function fillDefaults($key, $value) 630 | { 631 | if ( 632 | ($key === MessageDefaults::USER || $key === MessageDefaults::CHANNEL) && 633 | (! is_null($this->getTarget())) 634 | ) { 635 | return; 636 | } 637 | 638 | if ($suffix = $this->studlyCase($key)) { 639 | $getMethod = 'get'.$suffix; 640 | $setMethod = 'set'.$suffix; 641 | if ( 642 | method_exists($this, $getMethod) && 643 | is_null($this->{$getMethod}()) && 644 | method_exists($this, $setMethod) 645 | ) { 646 | $this->{$setMethod}($value); 647 | } 648 | } 649 | } 650 | 651 | /** 652 | * Convert a string to studly caps case. 653 | * 654 | * @param string $string 655 | * @return string 656 | */ 657 | protected function studlyCase($string) 658 | { 659 | return str_replace(' ', '', ucwords(str_replace(['-', '_'], ' ', $string))); 660 | } 661 | 662 | /** 663 | * Conveniently set message content. 664 | * 665 | * The parameters may be: 666 | * `($text, $markdown, $notification)` 667 | * or `($text, $attachment_text, $attachment_title, $attachment_images, $attachment_color)`. 668 | * 669 | * @return $this 670 | */ 671 | public function content() 672 | { 673 | $arguments = func_get_args(); 674 | $count = count($arguments); 675 | 676 | if ($count > 0) { 677 | $this->setText($arguments[0]); 678 | } 679 | 680 | if ($count > 1) { 681 | if (is_bool($arguments[1])) { 682 | $this->setMarkdown($arguments[1]); 683 | 684 | if ($count > 2) { 685 | $this->setNotification($arguments[2]); 686 | } 687 | } else { 688 | call_user_func_array([$this, 'addAttachment'], array_slice($arguments, 1)); 689 | } 690 | } 691 | 692 | return $this; 693 | } 694 | 695 | /** 696 | * Convert the message to an array. 697 | * 698 | * @return array 699 | */ 700 | public function toArray() 701 | { 702 | return array_filter( 703 | [ 704 | 'text' => $this->getText(), 705 | 'notification' => $this->getNotification(), 706 | 'markdown' => $this->getMarkdown(), 707 | 'channel' => $this->getChannel(), 708 | 'user' => $this->getUser(), 709 | 'attachments' => $this->getAttachments(), 710 | ], 711 | function ($value, $key) { 712 | return ! ( 713 | is_null($value) || 714 | ($key === 'markdown' && $value === true) || 715 | (is_array($value) && empty($value)) 716 | ); 717 | }, 718 | ARRAY_FILTER_USE_BOTH 719 | ); 720 | } 721 | 722 | /** 723 | * Convert the message to JSON string. 724 | * 725 | * @param int $options 726 | * @return string 727 | */ 728 | public function toJson($options = 0) 729 | { 730 | return json_encode($this->jsonSerialize(), $options); 731 | } 732 | 733 | /** 734 | * Serializes the object to a value that can be serialized natively by json_encode(). 735 | * 736 | * @return array 737 | */ 738 | public function jsonSerialize() 739 | { 740 | return $this->toArray(); 741 | } 742 | 743 | /** 744 | * Send the message. 745 | * 746 | * The parameters accepts the same format of `content` method. 747 | * 748 | * @return bool 749 | */ 750 | public function send() 751 | { 752 | if (! $this->client) { 753 | return false; 754 | } 755 | 756 | if ( 757 | 1 == func_num_args() && 758 | (is_array(func_get_arg(0)) || is_object(func_get_arg(0))) 759 | ) { 760 | return $this->client->sendMessage(func_get_arg(0)); 761 | } 762 | 763 | if (func_num_args() > 0) { 764 | call_user_func_array([$this, 'content'], func_get_args()); 765 | } 766 | 767 | return $this->client->sendMessage($this); 768 | } 769 | 770 | /** 771 | * Send the message to the given target. 772 | * 773 | * @param mixed $target 774 | * @return bool 775 | */ 776 | public function sendTo($target) 777 | { 778 | $this->to($target); 779 | 780 | return call_user_func_array([$this, 'send'], array_slice(func_get_args(), 1)); 781 | } 782 | 783 | /** 784 | * Convert the message to its string representation. 785 | * 786 | * @return string 787 | */ 788 | public function __toString() 789 | { 790 | return $this->toJson(); 791 | } 792 | } 793 | --------------------------------------------------------------------------------