EventsService.php

Go to the documentation of this file.

<?php

namespace Elgg;

use Elgg\EventsService\MethodMatcher;
use Elgg\Traits\Debug\Profilable;
use Elgg\Traits\Loggable;
use Psr\Log\LogLevel;

class EventsService {
    
    use Loggable;
    use Profilable;
    
    const REG_KEY_PRIORITY = 0;
    const REG_KEY_INDEX = 1;
    const REG_KEY_HANDLER = 2;
    
    const OPTION_STOPPABLE = 'stoppable';

    protected $handlers;
    
    protected $next_index = 0;
    
    protected $registrations = [];
    
    protected $backups = [];

    public function __construct(HandlersService $handlers) {
        $this->handlers = $handlers;
    }

    public function trigger(string $name, string $type, $object = null, array $options = []): bool {
        $options = array_merge([
            self::OPTION_STOPPABLE => true,
        ], $options);

        // get registered handlers
        $handlers = $this->getOrderedHandlers($name, $type);

        // This starts as a string, but if a handler type-hints an object we convert it on-demand inside
        // \Elgg\HandlersService::call and keep it alive during all handler calls. We do this because
        // creating objects for every triggering is expensive.
        /* @var $event Event|string */
        $event = 'event';
        foreach ($handlers as $handler) {
            $handler_description = false;
            if ($this->hasTimer() && $type === 'system' && $name !== 'shutdown') {
                $handler_description = $this->handlers->describeCallable($handler) . '()';
                $this->beginTimer(["[{$name},{$type}]", $handler_description]);
            }

            list($success, $return, $event) = $this->handlers->call($handler, $event, [
                $name,
                $type,
                null,
                [
                    'object' => $object,
                    '_elgg_sequence_id' => elgg_extract('_elgg_sequence_id', $options),
                ],
            ]);

            if ($handler_description) {
                $this->endTimer(["[{$name},{$type}]", $handler_description]);
            }

            if (!$success) {
                continue;
            }

            if (!empty($options[self::OPTION_STOPPABLE]) && ($return === false)) {
                return false;
            }
        }

        return true;
    }
    
    public function triggerResults(string $name, string $type, array $params = [], $value = null) {
        // This starts as a string, but if a handler type-hints an object we convert it on-demand inside
        // \Elgg\HandlersService::call and keep it alive during all handler calls. We do this because
        // creating objects for every triggering is expensive.
        /* @var $event Event|string */
        $event = 'event';
        foreach ($this->getOrderedHandlers($name, $type) as $handler) {
            list($success, $return, $event) = $this->handlers->call($handler, $event, [$name, $type, $value, $params]);
            
            if (!$success) {
                continue;
            }
            
            if ($return !== null) {
                $value = $return;
                $event->setValue($value);
            }
        }
        
        return $value;
    }

    public function triggerBefore(string $name, string $type, $object = null, array $options = []): bool {
        return $this->trigger("{$name}:before", $type, $object, $options);
    }

    public function triggerAfter(string $name, string $type, $object = null, array $options = []): void {
        $options[self::OPTION_STOPPABLE] = false;
        
        $this->trigger("{$name}:after", $type, $object, $options);
    }

    public function triggerSequence(string $name, string $type, $object = null, callable $callable = null, array $options = []): bool {
        // generate a unique ID to identify this sequence
        $options['_elgg_sequence_id'] = uniqid("{$name}{$type}", true);
        
        if (!$this->triggerBefore($name, $type, $object, $options)) {
            return false;
        }

        $result = $this->trigger($name, $type, $object, $options);
        if ($result === false) {
            return false;
        }

        if ($callable) {
            $result = call_user_func($callable, $object);
        }

        $this->triggerAfter($name, $type, $object, $options);

        return $result;
    }

    public function triggerResultsSequence(string $name, string $type, array $params = [], $value = null, callable $callable = null, array $options = []) {
        // generate a unique ID to identify this sequence
        $unique_id = uniqid("{$name}{$type}results", true);
        $options['_elgg_sequence_id'] = $unique_id;
        $params['_elgg_sequence_id'] = $unique_id;
        
        if (!$this->triggerBefore($name, $type, $params, $options)) {
            return false;
        }

        $result = $this->triggerResults($name, $type, $params, $value);
        if ($result === false) {
            return false;
        }

        if ($callable) {
            $result = call_user_func($callable, $params);
        }

        $this->triggerAfter($name, $type, $params, $options);

        return $result;
    }

    public function triggerDeprecated(string $name, string $type, $object = null, string $message = '', string $version = ''): bool {
        $message = "The '{$name}', '{$type}' event is deprecated. {$message}";
        $this->checkDeprecation($name, $type, $message, $version);
        
        return $this->trigger($name, $type, $object);
    }

    public function triggerDeprecatedResults(string $name, string $type, array $params = [], $returnvalue = null, string $message = '', string $version = '') {
        $message = "The '{$name}', '{$type}' event is deprecated. {$message}";
        $this->checkDeprecation($name, $type, $message, $version);
        
        return $this->triggerResults($name, $type, $params, $returnvalue);
    }
    
    public function registerHandler(string $name, string $type, $callback, int $priority = 500): bool {
        if (empty($name) || empty($type) || !is_callable($callback, true)) {
            return false;
        }
        
        if (($name == 'view' || $name == 'view_vars') && $type !== 'all') {
            $type = ViewsService::canonicalizeViewName($type);
        }
                
        $services = _elgg_services();
        if (in_array($this->getLogger()->getLevel(false), [LogLevel::WARNING, LogLevel::NOTICE, LogLevel::INFO, LogLevel::DEBUG])) {
            if (!$services->handlers->isCallable($callback)) {
                $this->getLogger()->warning('Handler: ' . $services->handlers->describeCallable($callback) . ' is not callable');
            }
        }
        
        $this->registrations[$name][$type][] = [
            self::REG_KEY_PRIORITY => $priority,
            self::REG_KEY_INDEX => $this->next_index,
            self::REG_KEY_HANDLER => $callback,
        ];
        $this->next_index++;
        
        return true;
    }
    
    public function unregisterHandler(string $name, string $type, $callback): void {
        if (($name === 'view' || $name === 'view_vars') && $type !== 'all') {
            $type = ViewsService::canonicalizeViewName($type);
        }
        
        if (empty($this->registrations[$name][$type])) {
            return;
        }
        
        $matcher = $this->getMatcher($callback);
        
        foreach ($this->registrations[$name][$type] as $i => $registration) {
            if ($matcher instanceof MethodMatcher) {
                if (!$matcher->matches($registration[self::REG_KEY_HANDLER])) {
                    continue;
                }
            } elseif ($registration[self::REG_KEY_HANDLER] != $callback) {
                continue;
            }
            
            unset($this->registrations[$name][$type][$i]);
            return;
        }
    }
    
    public function clearHandlers(string $name, string $type): void {
        unset($this->registrations[$name][$type]);
    }
    
    public function getAllHandlers(): array {
        $ret = [];
        foreach ($this->registrations as $name => $types) {
            foreach ($types as $type => $registrations) {
                foreach ($registrations as $registration) {
                    $priority = $registration[self::REG_KEY_PRIORITY];
                    $ret[$name][$type][$priority][] = $registration[self::REG_KEY_HANDLER];
                }
            }
        }
        
        return $ret;
    }
    
    public function hasHandler(string $name, string $type): bool {
        return !empty($this->registrations[$name][$type]);
    }
    
    public function getOrderedHandlers(string $name, string $type): array {
        $registrations = [];
        
        if (!empty($this->registrations[$name][$type])) {
            if ($name !== 'all' && $type !== 'all') {
                array_splice($registrations, count($registrations), 0, $this->registrations[$name][$type]);
            }
        }
        
        if (!empty($this->registrations['all'][$type])) {
            if ($type !== 'all') {
                array_splice($registrations, count($registrations), 0, $this->registrations['all'][$type]);
            }
        }
        
        if (!empty($this->registrations[$name]['all'])) {
            if ($name !== 'all') {
                array_splice($registrations, count($registrations), 0, $this->registrations[$name]['all']);
            }
        }
        
        if (!empty($this->registrations['all']['all'])) {
            array_splice($registrations, count($registrations), 0, $this->registrations['all']['all']);
        }
        
        usort($registrations, function ($a, $b) {
            // priority first
            if ($a[self::REG_KEY_PRIORITY] < $b[self::REG_KEY_PRIORITY]) {
                return -1;
            }
            
            if ($a[self::REG_KEY_PRIORITY] > $b[self::REG_KEY_PRIORITY]) {
                return 1;
            }
            
            // then insertion order
            return ($a[self::REG_KEY_INDEX] < $b[self::REG_KEY_INDEX]) ? -1 : 1;
        });
            
        $handlers = [];
        foreach ($registrations as $registration) {
            $handlers[] = $registration[self::REG_KEY_HANDLER];
        }
        
        return $handlers;
    }
    
    protected function getMatcher($spec): ?MethodMatcher {
        if (is_string($spec) && str_contains($spec, '::')) {
            list ($type, $method) = explode('::', $spec, 2);
            return new MethodMatcher($type, $method);
        }
        
        if (!is_array($spec) || empty($spec[0]) || empty($spec[1]) || !is_string($spec[1])) {
            return null;
        }
        
        if (is_object($spec[0])) {
            $spec[0] = get_class($spec[0]);
        }
        
        if (!is_string($spec[0])) {
            return null;
        }
        
        return new MethodMatcher($spec[0], $spec[1]);
    }
    
    public function backup(): void {
        $this->backups[] = $this->registrations;
        $this->registrations = [];
    }
    
    public function restore(): void {
        $backup = array_pop($this->backups);
        if (is_array($backup)) {
            $this->registrations = $backup;
        }
    }
    
    protected function checkDeprecation(string $name, string $type, string $message, string $version): void {
        $message = trim($message);
        if (empty($message)) {
            return;
        }
        
        if (!$this->hasHandler($name, $type)) {
            return;
        }
        
        $this->logDeprecatedMessage($message, $version);
    }
}