NotificationEventHandler.php

Go to the documentation of this file.

<?php
 
namespace Elgg\Notifications;
 
use Elgg\Exceptions\RuntimeException;
use Elgg\Traits\Loggable;
use Psr\Log\LogLevel;
 
class NotificationEventHandler {
 
    use Loggable;
    
    protected array $params = [];
    
    protected array $methods_override = [];
    
    public function __construct(
            protected NotificationEvent $event,
            protected NotificationsService $service,
            array $params = []
    ) {
        $methods_override = elgg_extract('methods_override', $params);
        unset($params['methods_override']);
        if (!empty($methods_override) && is_array($methods_override)) {
            $this->setMethodsOverride($methods_override);
        }
        
        $this->params = $params;
    }
    
    final protected function setMethodsOverride(array $methods): void {
        $this->methods_override = $methods;
    }
    
    final protected function getMethodsOverride(): array {
        return $this->methods_override;
    }
    
    protected function getNotificationMethods(): array {
        return [];
    }
    
    final public function send(): array {
        $deliveries = [];
        
        $params = $this->params;
        $params['handler'] = $this;
        $params['event'] = $this->event;
        $params['subscriptions'] = $this->prepareSubscriptions();
 
        // return false to stop the default notification sender
        if (_elgg_services()->events->triggerResults('send:before', 'notifications', $params, true)) {
            $deliveries = $this->sendNotifications($params['subscriptions'], $params);
        }
        
        $params['deliveries'] = $deliveries;
        _elgg_services()->events->triggerResults('send:after', 'notifications', $params);
        
        return $deliveries;
    }
    
    final protected function prepareSubscriptions(): array {
        $subscriptions = $this->getSubscriptions();
        
        $params = [
            'event' => $this->event,
            'methods' => $this->getMethods(),
            'methods_override' => $this->getMethodsOverride(),
            'handler' => $this,
        ];
        $subscriptions = _elgg_services()->events->triggerResults('get', 'subscriptions', $params, $subscriptions);
        
        return _elgg_services()->subscriptions->filterSubscriptions($subscriptions, $this->event, $this->filterMutedSubscriptions());
    }
    
    protected function filterMutedSubscriptions(): bool {
        return (bool) $this->getParam('apply_muting', true);
    }
    
    public function getSubscriptions(): array {
        return _elgg_services()->subscriptions->getNotificationEventSubscriptions($this->event, $this->getMethods(), $this->getNotificationSubscriptionExclusionGUIDs());
    }
    
    final protected function getNotificationSubscriptionExclusionGUIDs(): array {
        $object = $this->event->getObject();
        if (!$object instanceof \ElggEntity) {
            return [];
        }
        
        $exclude = [];
        if ($this->excludeOwnerSubscribers()) {
            $exclude[] = $object->owner_guid;
        }
        
        if ($this->excludeContainerSubscribers()) {
            $exclude[] = $object->container_guid;
        }
        
        if ($this->excludeEntitySubscribers()) {
            $exclude[] = $object->guid;
        }
        
        return $exclude;
    }
    
    protected function excludeOwnerSubscribers(): bool {
        return false;
    }
    
    protected function excludeContainerSubscribers(): bool {
        return false;
    }
    
    protected function excludeEntitySubscribers(): bool {
        return false;
    }
    
    final public function getMethods(): array {
        return $this->service->getMethods();
    }
    
    final protected function sendNotifications(array $subscriptions, array $params = []): array {
        if (empty($this->getMethods())) {
            return [];
        }
        
        $translator = _elgg_services()->translator;
        $current_language = $translator->getCurrentLanguage();
        
        $result = [];
        foreach ($subscriptions as $guid => $methods) {
            $recipient = _elgg_services()->entityTable->get($guid);
            if (!$recipient instanceof \ElggEntity) {
                continue;
            }
            
            if ($recipient instanceof \ElggUser) {
                $translator->setCurrentLanguage($recipient->getLanguage());
            }
            
            try {
                foreach ($methods as $method) {
                    $result[$guid][$method] = false;
                    
                    if ($this->service->isRegisteredMethod($method)) {
                        $result[$guid][$method] = $this->sendNotification($recipient, $method, $params);
                    }
                }
            } catch (\Throwable $t) {
                $translator->setCurrentLanguage($current_language);
                throw $t;
            }
            
            $translator->setCurrentLanguage($current_language);
        }
        
        $this->getLogger()->info("Results for the notification event {$this->event->getDescription()}: " . print_r($result, true));
        return $result;
    }
    
    final protected function sendNotification(\ElggEntity $recipient, string $method, array $params = []): bool {
        if (!_elgg_services()->events->hasHandler('send', "notification:{$method}")) {
            // no way to deliver given the current method, so quitting early
            return false;
        }
 
        $actor = $this->event->getActor();
        $object = $this->event->getObject();
 
        if (!$this->event instanceof InstantNotificationEvent) {
            if (!$recipient instanceof \ElggUser || $recipient->isBanned()) {
                return false;
            }
        
            if (!$actor || !$object) {
                return false;
            }
 
            if ($object instanceof \ElggEntity && !$object->hasAccess($recipient->guid)) {
                // Recipient does not have access to the notification object
                // The access level may have changed since the event was enqueued
                return false;
            }
        }
        
        $subject = ($recipient instanceof \ElggUser) ? $this->getNotificationSubject($recipient, $method) : '';
        $body = ($recipient instanceof \ElggUser) ? $this->getNotificationBody($recipient, $method) : '';
        $summary = ($recipient instanceof \ElggUser) ? $this->getNotificationSummary($recipient, $method) : '';
        $url = ($recipient instanceof \ElggUser) ? $this->getNotificationURL($recipient, $method) : null;
        $attachments = ($recipient instanceof \ElggUser) ? $this->getNotificationAttachments($recipient, $method) : null;
        
        $params['subject'] = $params['subject'] ?? $subject;
        $params['body'] = $params['body'] ?? $body;
        $params['summary'] = $params['summary'] ?? $summary;
        $params['url'] = $params['url'] ?? $url;
        $params['attachments'] = $params['attachments'] ?? $attachments;
        $params['event'] = $this->event;
        $params['method'] = $method;
        $params['sender'] = $actor;
        $params['recipient'] = $recipient;
        $params['language'] = $recipient instanceof \ElggUser ? $recipient->getLanguage() : _elgg_services()->translator->getCurrentLanguage();
        $params['object'] = $object;
        $params['action'] = $this->event->getAction();
        $params['add_salutation'] = elgg_extract('add_salutation', $params, true);
        $params['add_mute_link'] = elgg_extract('add_mute_link', $params, $this->addMuteLink());
 
        $notification = $this->prepareNotification($params);
        return $this->deliverNotification($notification, $method);
    }
    
    final protected function deliverNotification(Notification $notification, string $method): bool {
        // return true to indicate the notification has been sent
        $params = [
            'notification' => $notification,
            'event' => $this->event,
        ];
 
        $result = _elgg_services()->events->triggerResults('send', "notification:{$method}", $params, false);
        
        if ($this->getLogger()->isLoggable(LogLevel::INFO)) {
            $logger_data = print_r((array) $notification->toObject(), true);
            if ($result) {
                $this->getLogger()->info('Notification sent: ' . $logger_data);
            } else {
                $this->getLogger()->info('Notification was not sent: ' . $logger_data);
            }
        }
        
        return $result;
    }
    
    final protected function prepareNotification(array $params): Notification {
        $notification = new Notification($params['sender'], $params['recipient'], $params['language'], $params['subject'], $params['body'], $params['summary'], $params);
 
        $notification = _elgg_services()->events->triggerResults('prepare', 'notification', $params, $notification);
        if (!$notification instanceof Notification) {
            throw new RuntimeException("'prepare','notification' event must return an instance of " . Notification::class);
        }
 
        $type = 'notification:' . $this->event->getDescription();
        $notification = _elgg_services()->events->triggerResults('prepare', $type, $params, $notification);
        if (!$notification instanceof Notification) {
            throw new RuntimeException("'prepare','{$type}' event must return an instance of " . Notification::class);
        }
 
        if (elgg_extract('add_salutation', $notification->params) === true) {
            $viewtype = elgg_view_exists('notifications/body') ? '' : 'default';
            $notification->body = _elgg_view_under_viewtype('notifications/body', ['notification' => $notification], $viewtype);
        }
        
        $notification = _elgg_services()->events->triggerResults('format', "notification:{$params['method']}", [], $notification);
        if (!$notification instanceof Notification) {
            throw new RuntimeException("'format','notification:{$params['method']}' event must return an instance of " . Notification::class);
        }
        
        return $notification;
    }
 
    protected function getNotificationSubject(\ElggUser $recipient, string $method): string {
        $actor = $this->event->getActor() ?: null;
        $object = $this->event->getObject();
        
        // Check custom notification subject for the action/type/subtype combination
        $subject_key = "notification:{$this->event->getDescription()}:subject";
        if (_elgg_services()->translator->languageKeyExists($subject_key)) {
            return _elgg_services()->translator->translate($subject_key, [
                $actor?->getDisplayName(),
                $object instanceof \ElggEntity ? $object->getDisplayName() : '',
            ]);
        }
 
        // Fall back to default subject
        return _elgg_services()->translator->translate('notification:subject', [$actor?->getDisplayName()]);
    }
 
    protected function getNotificationBody(\ElggUser $recipient, string $method): string {
        $actor = $this->event->getActor() ?: null;
        $object = $this->event->getObject() ?: null;
        
        // Check custom notification body for the action/type/subtype combination
        $body_key = "notification:{$this->event->getDescription()}:body";
        if (_elgg_services()->translator->languageKeyExists($body_key)) {
            $display_name = '';
            $container_name = '';
            if ($object instanceof \ElggEntity) {
                $display_name = $object->getDisplayName();
                $container_name = $object->getContainerEntity()?->getDisplayName();
            }
 
            return _elgg_services()->translator->translate($body_key, [
                $actor?->getDisplayName(),
                $display_name,
                $container_name,
                $object?->description,
                $object?->getURL(),
            ]);
        }
 
        // Fall back to default body
        return _elgg_services()->translator->translate('notification:body', [$object?->getURL()]);
    }
    
    protected function getNotificationSummary(\ElggUser $recipient, string $method): string {
        return '';
    }
    
    protected function getNotificationURL(\ElggUser $recipient, string $method): string {
        $object = $this->event->getObject() ?: null;
        
        return (string) $object?->getURL();
    }
    
    protected function getNotificationAttachments(\ElggUser $recipient, string $method): array {
        return [];
    }
    
    protected function getEventActor(): ?\ElggUser {
        $actor = $this->event->getActor();
        
        return $actor instanceof \ElggUser ? $actor : null;
    }
    
    protected function getEventEntity(): ?\ElggEntity {
        $object = $this->event->getObject();
        
        return $object instanceof \ElggEntity ? $object : null;
    }
    
    public static function isConfigurableByUser(): bool {
        return true;
    }
    
    final public static function isConfigurableForEntity(\ElggEntity $entity): bool {
        if ($entity instanceof \ElggUser) {
            return static::isConfigurableForUser($entity);
        } elseif ($entity instanceof \ElggGroup) {
            return static::isConfigurableForGroup($entity);
        }
        
        return false;
    }
    
    protected static function isConfigurableForUser(\ElggUser $user): bool {
        return true;
    }
    
    protected static function isConfigurableForGroup(\ElggGroup $group): bool {
        return true;
    }
    
    protected function addMuteLink(): bool {
        return true;
    }
    
    final protected function getParam(string $param, mixed $default = null): mixed {
        return elgg_extract($param, $this->params, $default);
    }
}