README

LostLink Laravel-Messenger is a Laravel package for sending messages to various services asynchronously without blocking the processing of your application. Messages are queued and sent during the PHP destruct() phase, ensuring that the application’s performance is not impacted by external service communication.

Features

Non-blocking message dispatch: Messages are processed after the PHP request lifecycle.
Extensible driver system: Add custom drivers to send messages to services of your choice.
Simple configuration: Set up different drivers with environment variables.
Rate limiting: Control the rate at which messages are sent to avoid exceeding service limits.

Supported Drivers

Installation

Install the package via Composer:

composer require lostlink/laravel-messenger

Publish the configuration file (optional):

php artisan vendor:publish --tag=messenger-config

Configure the environment variables for the drivers you wish to use.

Configuration

The package supports multiple drivers, and you can set the default driver using environment variables. Here’s an example configuration file:

return [

    'default' => env('LARAVEL_MESSENGER_DRIVER', 'log'),

    'drivers' => [

        'log' => [
            'class' => Lostlink\Messenger\Drivers\Log::class,
            'rate_limit' => [
                'enabled' => env('LARAVEL_MESSENGER_LOG_RATE_LIMIT_ENABLED', false),
                'max_attempts' => env('LARAVEL_MESSENGER_LOG_RATE_LIMIT_MAX_ATTEMPTS', 10),
                'decay_seconds' => env('LARAVEL_MESSENGER_LOG_RATE_LIMIT_DECAY_SECONDS', 60),
            ],
        ],

        'kinesis' => [
            'class' => Lostlink\Messenger\Drivers\Kinesis::class,
            'name' => env('LARAVEL_MESSENGER_KINESIS_STREAM_NAME'),
            'region' => env('LARAVEL_MESSENGER_KINESIS_STREAM_AWS_REGION', env('AWS_DEFAULT_REGION')),
            'aws_key' => env('LARAVEL_MESSENGER_KINESIS_STREAM_AWS_KEY', env('AWS_ACCESS_KEY_ID')),
            'aws_secret_key' => env('LARAVEL_MESSENGER_KINESIS_STREAM_AWS_SECRET_KEY', env('AWS_SECRET_ACCESS_KEY')),
            'rate_limit' => [
                'enabled' => env('LARAVEL_MESSENGER_KINESIS_RATE_LIMIT_ENABLED', false),
                'max_attempts' => env('LARAVEL_MESSENGER_KINESIS_RATE_LIMIT_MAX_ATTEMPTS', 10),
                'decay_seconds' => env('LARAVEL_MESSENGER_KINESIS_RATE_LIMIT_DECAY_SECONDS', 60),
            ],
        ],

        'tinybird' => [
            'class' => Lostlink\Messenger\Drivers\Tinybird::class,
            'name' => env('LARAVEL_MESSENGER_TINYBIRD_DATA_SOURCE_NAME'),
            'token' => env('LARAVEL_MESSENGER_TINYBIRD_TOKEN'),
            'endpoint' => env('LARAVEL_MESSENGER_TINYBIRD_ENDPOINT', 'https://api.us-east.aws.tinybird.co/v0/events'),
            'rate_limit' => [
                'enabled' => env('LARAVEL_MESSENGER_TINYBIRD_RATE_LIMIT_ENABLED', false),
                'max_attempts' => env('LARAVEL_MESSENGER_TINYBIRD_RATE_LIMIT_MAX_ATTEMPTS', 40), // Free tier limit
                'decay_seconds' => env('LARAVEL_MESSENGER_TINYBIRD_RATE_LIMIT_DECAY_SECONDS', 3600), // Free tier limit
            ],
        ],

    ],

];

Available Environment Variables

Usage

Sending messages with LostLink Laravel-Messenger is simple. After configuring your environment variables, you can use the send method:

use \Lostlink\Messenger\Messenger;

Messenger::send([
   "timestamp" => "2022-10-27T11:43:02.099Z", 
   "transaction_id" => "8d1e1533-6071-4b10-9cda-b8429c1c7a67", 
   "name" => "Bobby Drake", 
   "email" => "bobby.drake@pressure.io", 
   "age" => 42, 
   "passport_number" => 3847665, 
   "flight_from" => "Barcelona", 
   "flight_to" => "London", 
   "extra_bags" => 1, 
   "flight_class" => "economy", 
   "priority_boarding" => false, 
   "meal_choice" => "vegetarian", 
   "seat_number" => "15D", 
   "airline" => "Red Balloon" 
]);

Updating Configuration on the Fly

You can modify the configuration for a specific message by chaining and passing an array to the config([]) method. This allows you to override the default driver settings for that particular message. Here's an example:

use \Lostlink\Messenger\Messenger;

Messenger::send([
   "timestamp" => "2022-10-27T11:43:02.099Z", 
   "transaction_id" => "8d1e1533-6071-4b10-9cda-b8429c1c7a67", 
   "name" => "Bobby Drake", 
   "email" => "bobby.drake@pressure.io", 
   "age" => 42, 
   "passport_number" => 3847665, 
   "flight_from" => "Barcelona", 
   "flight_to" => "London", 
   "extra_bags" => 1, 
   "flight_class" => "economy", 
   "priority_boarding" => false, 
   "meal_choice" => "vegetarian", 
   "seat_number" => "15D", 
   "airline" => "Red Balloon" 
])
->driver('tinybird') // Change the driver to "tinybird" for this message
->config([
    'name' => 'example_events', // Change the data source name to "example_events" for this message
    'token' => 'your_token', // Change the token for this message
    'endpoint' => 'https://api.us-east.aws.tinybird.co/v0/events', // Change the endpoint for this message
    'rate_limit' => [
        'enabled' => true, // Enable rate limiting for this message to use Tinybird Free Tier @ 1000/day
        'max_attempts' => 40, // Set the maximum number of attempts before rate limiting is enforced
        'decay_seconds' => 3600, // Set the number of seconds before the rate limit resets
    ],
]);

Adding Custom Drivers

To create and add your own driver, simply extend the driver system by implementing the required interfaces.

Make sure to publish the laravel-messenger config file
```
php artisan vendor:publish --tag=messenger-config
```

Adjust the laravel-messenger config with the name and class of your custom driver

return [
     ...   

    'drivers' => [

         ...

        'mycustomdriver' => [
            'class' => \App\Messenger\Drivers\MyCustomDriver::class,
            'name' => env('MY_CUSTOM_DRIVER_NAME'),
            'token' => env('MY_CUSTOM_DRIVER_TOKEN'),
            'endpoint' => env('MY_CUSTOM_DRIVER_ENDPOINT'),
            'rate_limit' => [
                'enabled' => env('MY_CUSTOM_DRIVER_RATE_LIMIT_ENABLED', false),
                'max_attempts' => env('MY_CUSTOM_DRIVER_RATE_LIMIT_MAX_ATTEMPTS', 10),
                'decay_seconds' => env('MY_CUSTOM_DRIVER_RATE_LIMIT_DECAY_SECONDS', 60),
            ],
        ],

    ],

    ...

];

Create a class that extends \LostLink\Drivers\Driver

class MyCustomDriver extends Driver
{
    public function handle(): void
    {
        $response = Http::withToken($this->message->token ?? $this->message->config->get('token'))
            ->acceptJson()
            ->withQueryParameters([
                'name' => $this->message->stream ?? $this->message->config->get('name'),
            ])
            ->post(
                $this->message->endpoint ?? $this->message->config->get('endpoint'),
                $this->message->body
            );

        $response->throw();
    }
}
```

License

This package is open-sourced software licensed under the MIT license.

lostlink / laravel-messenger

Maintainers

Details