2
0
Fork 0
Laravel package for sending notifications with Threema. https://ablota.com
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Fabio Widmer 6309b728e8
Fix unit tests
2 months ago
config Initial commit 3 months ago
src Fix unit tests 2 months ago
tests Fix unit tests 2 months ago
.editorconfig Initial commit 3 months ago
.gitattributes Initial commit 3 months ago
.gitignore Initial commit 3 months ago
.gitlab-ci.yml Fix GitLab pipeline 2 months ago
CHANGELOG.md Add more message types 2 months ago
LICENSE.md Initial commit 3 months ago
README.md Add more message types 2 months ago
composer.json Add more message types 2 months ago
composer.lock Add more message types 2 months ago
phpunit.xml Initial commit 3 months ago

README.md

Laravel Threema Notification Channel

Laravel package for sending notifications with Threema.

Prerequisites

  1. Add the following repository to your composer.json:
{
	"repositories": [
		{
			"type": "package",
			"package": {
				"name": "threema/msgapi-sdk",
				"version": "1.5.6",
				"dist": {
					"url": "https://gateway.threema.ch/sdk/threema-msgapi-sdk-php-1.5.6.zip",
					"type": "zip"
				}
			}
		}
	]
}
  1. Install the package with Composer:
composer require ablota/laravel-threema-notification-channel
  1. Request a Threema Gateway ID. Register to get a basic ID for testing immediately. If you are interested in an end-to-end ID, contact Threema and they will usually provide you with an ID for testing.

Configuration

The package includes a configuration file. However, you are not required to export this configuration file to your own application. You can simply use the environment variables below:

// Required
THREEMA_GATEWAY_ID=
THREEMA_GATEWAY_SECRET=

// Optional
THREEMA_GATEWAY_PRIVATE_KEY=
THREEMA_MSGAPI_HOST=
THREEMA_TLS_FORCE_HTTPS=true|false
THREEMA_TLS_CIPHER=...
THREEMA_TLS_VERSION=1.0|1.1|1.2

The required variables are shown on the Threema Gateway website. The THREEMA_GATEWAY_PRIVATE_KEY is required in hex if you're using the end-to-end mode.

Formatting Notifications

If a notification supports being sent as a Threema message, you should define a toThreema method on the notification class. This method will receive a $notifiable entity and should return an Illuminate\Notifications\Messages\ThreemaMessage instance. Let's take a look at a basic toThreema example:

use Illuminate\Notifications\Messages\ThreemaMessage;
use Illuminate\Notifications\Messages\ThreemaTextMessage;

public function toThreema(mixed $notifiable): ThreemaMessage
{
	return new ThreemaTextMessage('Hello World!');
}

Right now only 1:1 chat messages (text, image, location, audio, video, file) are supported. Group message types are coming soon.

Routing Notifications

To route Threema notifications to the proper Threema ID, define a routeNotificationForThreema method on your notifiable entity:

use Threema\MsgApi\Receiver;

public function routeNotificationForThreema(mixed $notification): Receiver
{
	return new Receiver($this->threema_id, Receiver::TYPE_ID);
}

By using Receiver::TYPE_EMAIL or Receiver::TYPE_PHONE you can make use of an automatic ID lookup.

Exceptions

The package only throws the following exceptions:

ThreemaChannelException

Is thrown in case of fatal errors. For example, if certain types are not supported or the configuration is incorrect.

ThreemaChannelResultException

Since Laravel does not return a result when sending notifications, this exception is thrown instead. For example, sending a message to an unknown Threema ID would lead into this exception. It should be caught and the result it contains should be processed:

use Illuminate\Notifications\Exceptions\ThreemaChannelResultException;

try {
	$notifiable->notify(new TwoFactorVerificationCode());
} catch(ThreemaChannelResultException $exception) {
	$exception->getResult();
}