BearyChat for Laravel

The Laravel integration for BearyChat to send robot messages.

This package is compatible with Laravel 4/5/6/7/8 and Lumen.

🇨🇳 中文文档

Laravel Notification Channel: BearyChatChannel

Installation
Usage
Changelog
Testing
License

Installation

You can install this package using the Composer manager:

$ composer require elfsundae/laravel-bearychat

After updating composer, you may configure your app according to the following steps:

Laravel 5/6/7/8

For Laravel 5.5+, the service provider will automatically get registered.

Add the service provider to the providers array in config/app.php:

ElfSundae\BearyChat\Laravel\ServiceProvider::class,

'BearyChat' => ElfSundae\BearyChat\Laravel\BearyChat::class,

Then publish the config file:

$ php artisan vendor:publish --tag=bearychat

Next, configure your BearyChat clients by editing the config file in config/bearychat.php.

Laravel 4

Please install version 1.1.x:

$ composer require elfsundae/laravel-bearychat:1.1.*

Add the service provider to the providers array in config/app.php:

'ElfSundae\BearyChat\Laravel\ServiceProvider',

Then publish the config file:

$ php artisan config:publish elfsundae/laravel-bearychat

Next, configure your BearyChat clients by editing the config file in app/config/packages/elfsundae/laravel-bearychat/config.php.

Lumen

$app->register(ElfSundae\BearyChat\Laravel\ServiceProvider::class);

Then copy the config file from this package to your app's config/bearychat.php:

$ cp vendor/elfsundae/laravel-bearychat/config/bearychat.php config/bearychat.php

Now you can configure your BearyChat clients by editing config/bearychat.php.

Usage

Basic Usage

You can obtain the BearyChat Client using the BearyChat facade, or the bearychat() helper function.

BearyChat::send('message');

bearychat()->sendTo('@elf', 'Hi!');

You may access various clients via the client method of the BearyChat facade, or pass a client name to the bearychat() function. The name should correspond to one of the clients listed in your BearyChat configuration file.

BearyChat::client('dev')->send('foo');

bearychat('admin')->send('bar');

For more advanced usage, please read the documentation of the BearyChat PHP package.

Asynchronous Message

Sending a BearyChat message actually requests the Incoming Webhook via synchronous HTTP, so it will slow down your app execution. For sending asynchronous messages, You can queue them using Laravel's awesome queue system.

Here is an example of the Queueable Job for Laravel 5.3:

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use ElfSundae\BearyChat\Message;

class SendBearyChat implements ShouldQueue
{
    use InteractsWithQueue, Queueable, SerializesModels;

    /**
     * The BearyChat client.
     *
     * @var \ElfSundae\BearyChat\Client
     */
    protected $client;

    /**
     * The Message instance to be sent.
     *
     * @var \ElfSundae\BearyChat\Message
     */
    protected $message;

    /**
     * Create a new job instance.
     *
     * @param  mixed  $message  A Message instance, or parameters which can be handled
     *                          by the `send` method of a Message instance.
     */
    public function __construct($message = null)
    {
        if ($message instanceof Message) {
            $this->message = $message;
        } elseif (is_string($message)) {
            $this->text($message);

            if (func_num_args() > 1) {
                if (is_bool($markdown = func_get_arg(1))) {
                    $this->markdown(func_get_arg(1));

                    if (func_num_args() > 2) {
                        $this->notification(func_get_arg(2));
                    }
                } else {
                    call_user_func_array([$this, 'add'], array_slice(func_get_args(), 1));
                }
            }
        }
    }

    /**
     * Any unhandled methods will be sent to the Message instance.
     *
     * @param  string  $method
     * @param  array  $parameters
     * @return $this
     */
    public function __call($method, $parameters)
    {
        $message = $this->message ?: new Message($this->client ?: bearychat());

        $this->message = call_user_func_array([$message, $method], $parameters);

        return $this;
    }

    /**
     * Set the client with client name.
     *
     * @param  string  $name
     * @return $this
     */
    public function client($name)
    {
        $this->client = bearychat($name);

        return $this;
    }

    /**
     * Execute the job.
     */
    public function handle()
    {
        if ($this->client) {
            $this->client->sendMessage($this->message);
        } else {
            $this->message->send();
        }
    }
}

Then you can dispatch SendBearyChat jobs by calling the dispatch method on any object which includes the DispatchesJobs trait, or just use the dispatch() global function:

dispatch(new SendBearyChat('hello'));

dispatch(new SendBearyChat('hello', true, 'notification'));

dispatch(new SendBearyChat('hello', 'attachment content', 'attachment title', 'http://path/to/image', '#f00'));

dispatch((new SendBearyChat)->client('server')->text('hello')->add('attachment'));

dispatch(new SendBearyChat(
    bearychat('admin')->text('New order!')->add($order, $order->name, $order->image_url)
));

Sending Laravel Exceptions

A common usage of BearyChat is real-time reporting Laravel exceptions. Just override the report method of your exception handler:

/**
 * Report or log an exception.
 *
 * This is a great spot to send exceptions to Sentry, Bugsnag, etc.
 *
 * @param  \Exception  $e
 * @return void
 */
public function report(Exception $e)
{
    parent::report($e);

    if (app()->environment('production') && $this->shouldReport($e)) {
        dispatch(
            (new SendBearyChat)
            ->client('server')
            ->text('New Exception!')
            ->notification('New Exception: '.get_class($e))
            ->markdown(false)
            ->add(str_limit($e, 1300), get_class($e), null, '#a0a0a0')
        );
    }
}

Creating Outgoing Responses

Need to respond to an Outgoing Robot? Simply create a JSON response with a Message instance.

Route::post('webhook/bearychat', 'WebhookController@bearychat');

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use ElfSundae\BearyChat\Message;

class WebhookController extends Controller
{
    /**
     * The BearyChat Outgoing Robot.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\JsonResponse
     */
    public function bearychat(Request $request)
    {
        $message = (new Message)
            ->text('Response for ' . $request->input('text'))
            ->add('attachment content');

        return response()->json($message);
    }
}

You may exclude your Outgoing handler from Laravel's CSRF protection.

Customize Guzzle

You can customize Guzzle HTTP clients for BearyChat by calling the customHttpClient method on the BearyChat facade or app('bearychat').

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use GuzzleHttp\Client as HttpClient;
use ElfSundae\BearyChat\Laravel\BearyChat;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        BearyChat::customHttpClient(function ($name) {
            if ($name == 'dev') {
                return new HttpClient([
                    'connect_timeout' => 10,
                    'timeout' => 30,
                    'verify' => false
                ]);
            }
        });
    }
}

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

License

The BearyChat Laravel package is available under the MIT license.

ElfSundae/laravel-bearychat