README

A PHP package for sending message to BearyChat with the Incoming Webhook, and creating response payload for the Outgoing Robot.

🇨🇳 中文文档
Laravel integration: BearyChat for Laravel
Laravel Notification Channel: BearyChatChannel
Yii integration: BearyChat for Yii 2

Installation

You can install this package using the Composer manager.

composer require elfsundae/bearychat

Then you may create an Incoming Robot on your BearyChat team account, and read the payload format.

Documentation

Overview

(new Client('https://hook.bearychat.com/=...'))
    ->text('content')
    ->add('attachment', 'title')
    ->addImage($imageUrl, 'image description')
    ->sendTo('admin');

(new Client($webhook))->send('content', 'attachment');

To send messages, first create a BearyChat client with your webhook URL:

$client = new ElfSundae\BearyChat\Client('http://hook.bearychat.com/=.../incoming/...');

Besides the webhook, you may want to setup some default values for all messages which will be sent with this client:

use ElfSundae\BearyChat\Client;

$client = new Client($webhook, [
    'channel' => 'server-log',
    'attachment_color' => '#3e4787'
]);

All defaults keys are listed in MessageDefaults . You can access message default with $client->getMessageDefaults($key), or retrieve all defaults with $client->getMessageDefaults() .

To send a message, just call sendMessage on the client instance with a message payload array or a payload JSON string:

$client->sendMessage([
    'text' => 'Hi, Elf!',
    'user' => 'elf'
]);

$json = '{"text": "Good job :+1:", "channel": "all"}';
$client->sendMessage($json);

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 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 class.

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 to achieve one-liner code.

You can also call the powerful send or sendTo method with message contents for sending a message.

$client->to('#all')->text('Hello')->add('World')->send();

$client->sendTo('all', 'Hello', 'World');

Message Modifications

Available methods for message modification in the Message class:

text: getText , setText($text) , text($text)
notification: getNotification , setNotification($notification) , notification($notification)
markdown: getMarkdown , setMarkdown($markdown) , markdown($markdown = true)
channel: getChannel , setChannel($channel) , channel($channel) , to($channel)
user: getUser , setUser($user) , user($user) , to('@'.$user)
target (user or channel): getTarget, setTarget($target), target($target), removeTarget, to($target)
attachments: getAttachments , setAttachments($attachments) , attachments($attachments) , addAttachment(...) , add(...) , addImage , removeAttachments(...) , remove(...)
content($text, $markdown, $notification), content($text, $attachment_text, $attachment_title, $attachment_images, $attachment_color)

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.

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.

$client
    ->to('@elf')
    ->text('message')
    ->add([
        'text' => 'Content of the first attachment.',
        'title' => 'First Attachment',
        'images' => [$imageUrl, $imageUrl2],
        'color' => '#10e4fe'
    ])
    ->add(
        'Content of the second attachment.',
        'Second Attachment',
        [$imageUrl, $imageUrl2],
        'red'
    )
    ->send();

To remove attachments, call removeAttachments or remove with indices.

$message->remove(0)->remove(0, 1)->remove([1, 3])->remove();

Message Representation

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.

⚠️ The message payload may be used for requesting an Incoming Webhook or creating response for an Outgoing Robot.

$message = $client->to('@elf')->text('foo')->markdown(false)
    ->add('bar', 'some images', 'path/to/image', 'blue');

echo $message->toJson(JSON_PRETTY_PRINT);

The above example will output:

{
    "text": "foo",
    "markdown": false,
    "user": "elf",
    "attachments": [
        {
            "text": "bar",
            "title": "some images",
            "images": [
                {
                    "url": "path\/to\/image"
                }
            ],
            "color": "blue"
        }
    ]
}

Sending Message

You can call send or sendTo method on a Message instance to send that message.

The send method optional accepts variable number of arguments to quickly change the payload content:

Sending a basic message: send($text, $markdown = true, $notification)
Sending a message with one attachment added: send($text, $attachment_text, $attachment_title, $attachment_images, $attachment_color)

The sendTo method is useful when you want to change the message's target before calling send method.

$client = new Client($webhook, [
    'channel' => 'all'
]);

// Sending a message to the default channel
$client->send('Hi there :smile:');

// Sending a customized message
$client->send('disable **markdown**', false, 'custom notification');

// Sending a message with one attachment added
$client->send('message title', 'Attachment Content');

// Sending a message with an customized attachment
$client->send(
    'message with an customized attachment',
    'Attachment Content',
    'Attachment Title',
    $imageUrl,
    '#f00'
);

// Sending a message with multiple images
$client->send('multiple images', null, null, [$imageUrl1, $imageUrl2]);

// Sending a message to a different channel
$client->sendTo('iOS', '**Lunch Time !!!**');

// Sending a message to an user
$client->sendTo('@elf', 'Where are you?');

Customize Client

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.

A Client instance is mutable, it means you can change its webhook URL or the message defaults by calling setWebhook, webhook or setMessageDefaults.

$client->webhook($webhook_ios)->setMessageDefaults([
    'channel' => 'ios_dev'
])->send('App reviewing status has updated.');

Testing

$ composer test

License

The BearyChat PHP package is available under the MIT license.

elfsundae / bearychat

Maintainers

Details