README

This library offers a quick and easy way to create and send notifications in any language. The notifications are usually configured in the config screen of Notifications4Plugin and can then be sent for instance as an email by other plugins dynamic

This project is licensed under the GPL-3.0-only license

The text of the notifications is parsed by default with the Twig template engine!, meaning the developer can replace placeholders and use if statements and loops

The development interface offers easy methods to create, modify and send notifications

Usage

Composer

First add the following to your composer.json file:

"require": {
  "srag/notifications4plugin": ">=0.1.0"
},

And run a composer install.

If you deliver your plugin, the plugin has it's own copy of this library and the user doesn't need to install the library.

Tip: Because of multiple autoloaders of plugins, it could be, that different versions of this library exists and suddenly your plugin use an older or a newer version of an other plugin!

So I recommand to use srag/librariesnamespacechanger in your plugin.

Twig PHP 7.4 patch

For make twig work with PHP 7.4, you may need to patch it (At your own risk)

At the follow in your composer.json

  ...
  "pre-autoload-dump": [
    ...,
    "vendor/srag/notifications4plugin/bin/twig_php74_patch.php"
    ]
  ...

Using trait

Your class in this you want to use Notifications4Plugin needs to use the trait Notifications4PluginTrait

...
use srag\Notifications4Plugin\x\Utils\Notifications4PluginTrait;
...
class x {
...
use Notifications4PluginTrait;
...

Notification ActiveRecord

First you need to init the Notification and NotificationLanguage active record classes with your own table name prefix. Please add this very early in your plugin code

self::notifications4plugin()->withTableNamePrefix(ilXPlugin::PLUGIN_ID)->withPlugin(self::plugin())->withPlaceholderTypes([
    'user' => 'object ' . ilObjUser::class,
    'course' => 'object ' . ilObjCourse::class,
    'id' => 'int'
]);

Add an update step to your dbupdate.php

...
<#x>
<?php
\srag\Notifications4Plugin\x\Repository::getInstance()->installTables();
?>

and not forget to add an uninstaller step in your plugin class too

self::notifications4plugin()->notifications()->dropTables();

Ctrl classes

...
/**
 * ...
 *
 * @ilCtrl_isCalledBy srag\Notifications4Plugin\x\Notification\NotificationsCtrl: x
 */
class x
{
    ...
}

Languages

Expand you plugin class for installing languages of the library to your plugin

...
	/**
     * @inheritDoc
     */
    public function updateLanguages(/*?array*/ $a_lang_keys = null):void {
		parent::updateLanguages($a_lang_keys);

		self::notifications4plugin()->installLanguages();
	}
...

Migrate from old global plugin

Add to your dbupdate.php like:

use srag\Notifications4Plugin\x\Notification\Repository;if (Repository::getInstance()->migrateFromOldGlobalPlugin(x::TEMPLATE_NAME) === null) {

	$notification = Repository::getInstance()->factory()->newInstance();

	$notification->setName(x::TEMPLATE_NAME);

	// TODO: Fill $notification with your default values

	Repository::getInstance()->storeNotification($notification);
}

Get notification(s)

Main

// Get the notification by name
$notification = self::notifications4plugin()->notifications()->getNotificationByName(self::MY_UNIQUE_NAME);

Other

// Get the notification by id
$notification = self::notifications4plugin()->notifications()->getNotificationById(self::MY_UNIQUE_ID);

// Get the notifications
$notifications = self::notifications4plugin()->notifications()->getNotifications();

Send a notification

// Send the notification as external mail
$sender = self::notifications4plugin()->sender()->factory()->externalMail('from_email', 'to_email');

// Send the notification as internal mail
$sender = self::notifications4plugin()->sender()->factory()->internalMail('from_user', 'to_user');

// vcalendar
$sender = self::notifications4plugin()->sender()->factory()->vcalendar(...);

// Implement a custom sender object
// Your class must implement the interface `srag\Notifications4Plugin\x\Sender\Sender`

// Prepare placeholders, note that the keys are the same like declared in the notification template
$placeholders = [
  'user' => new ilObjUser(6),
  'course' => new ilObjCourse(12345)
];

// Sent the notification in english first (default langauge) and in german again
self::notifications4plugin()->sender()->send($sender, $notification, $placeholders);
self::notifications4plugin()->sender()->send($sender, $notification, $placeholders, 'de');

Create a notification

$notification = self::notifications4plugin()->notifications()->factory()->newInstance();

$notification->setName(self::MY_UNIQUE_NAME); // Use the name as unique identifier to retrieve this object later
$notification->setDefaultLanguage('en'); // The text of the default language gets substituted if you try to get the notification of a langauge not available
$notification->setTitle('My first notification');
$notification->setDescription("I'm a description");

// Add subject and text for english and german
$notification->setSubject('Hi {{ user.getFullname }}', 'en');
$notification->setText('You joined the course {{ course.getTitle }}', 'en');
$notification->setSubject('Hallo {{ user.getFullname }}', 'de');
$notification->setText('Sie sind nun Mitglied in folgendem Kurs {{ course.getTitle }}', 'de');

self::notifications4plugin()->notifications()->storeNotification($notification);

Duplicate a notification

$duplicated_notification = self::notifications4plugin()->notifications()->duplicateNotification($notification);

Delete a notification

self::notifications4plugin()->notifications()->deleteNotification($notification);

Get parsed subject and text of a notification

You can get the parsed subject and text from a notification, for example to display it on screen.

$placeholders = [
  'course' => new ilObjCourse(1234),
  'user' => new ilObjUser(6)
];

$parser = self::notifications4plugin()->parser()->getParserForNotification($notification);

$subject = self::notifications4plugin()->parser()->parseSubject($parser, $notification, $placeholders);
$text = self::notifications4plugin()->parser()->parseText($parser, $notification, $placeholders);

Implement a custom parser

Your class must extends srag\Notifications4Plugin\x\Parser\AbstractParser

You can add it

self::notifications4plugin()->parser()->addParser(new CustomParser());

Requirements

ILIAS 6.0 - 7.999
PHP >=7.2

srag / notifications4plugin

Maintainers

Details