*/ class Dispatcher { public const FILTER_BEFORE = 'before'; public const FILTER_AFTER = 'after'; /** Exception message if thrown by setting the container as a callable method. */ protected ?Throwable $containerException = null; /** @var ?Engine $engine Engine instance. */ protected ?Engine $engine = null; /** @var array Mapped events. */ protected array $events = []; /** * Method filters. * * @var array &$params, mixed &$output): (void|false)>>> */ protected array $filters = []; /** * This is a container for the dependency injection. * * @var null|ContainerInterface|(callable(string $classString, array $params): (null|object)) */ protected $containerHandler = null; /** * Sets the dependency injection container handler. * * @param ContainerInterface|(callable(string $classString, array $params): (null|object)) $containerHandler * Dependency injection container. * * @throws InvalidArgumentException If $containerHandler is not a `callable` or instance of `Psr\Container\ContainerInterface`. */ public function setContainerHandler($containerHandler): void { $containerInterfaceNS = '\Psr\Container\ContainerInterface'; if ( is_a($containerHandler, $containerInterfaceNS) || is_callable($containerHandler) ) { $this->containerHandler = $containerHandler; return; } throw new InvalidArgumentException( "\$containerHandler must be of type callable or instance $containerInterfaceNS" ); } public function setEngine(Engine $engine): void { $this->engine = $engine; } /** * Dispatches an event. * * @param string $name Event name. * @param array $params Callback parameters. * * @return mixed Output of callback * @throws Exception If event name isn't found or if event throws an `Exception`. */ public function run(string $name, array $params = []) { $this->runPreFilters($name, $params); $output = $this->runEvent($name, $params); return $this->runPostFilters($name, $output); } /** * @param array &$params * * @return $this * @throws Exception */ protected function runPreFilters(string $eventName, array &$params): self { $thereAreBeforeFilters = !empty($this->filters[$eventName][self::FILTER_BEFORE]); if ($thereAreBeforeFilters) { $this->filter($this->filters[$eventName][self::FILTER_BEFORE], $params, $output); } return $this; } /** * @param array &$params * * @return void|mixed * @throws Exception */ protected function runEvent(string $eventName, array &$params) { $requestedMethod = $this->get($eventName); if ($requestedMethod === null) { throw new Exception("Event '$eventName' isn't found."); } return $this->execute($requestedMethod, $params); } /** * @param mixed &$output * * @return mixed * @throws Exception */ protected function runPostFilters(string $eventName, &$output) { static $params = []; $thereAreAfterFilters = !empty($this->filters[$eventName][self::FILTER_AFTER]); if ($thereAreAfterFilters) { $this->filter($this->filters[$eventName][self::FILTER_AFTER], $params, $output); } return $output; } /** * Assigns a callback to an event. * * @param string $name Event name. * @param callable(): (void|mixed) $callback Callback function. * * @return $this */ public function set(string $name, callable $callback): self { $this->events[$name] = $callback; return $this; } /** * Gets an assigned callback. * * @param string $name Event name. * * @return null|(callable(): (void|mixed)) $callback Callback function. */ public function get(string $name): ?callable { return $this->events[$name] ?? null; } /** * Checks if an event has been set. * * @param string $name Event name. * * @return bool If event exists or doesn't exists. */ public function has(string $name): bool { return isset($this->events[$name]); } /** * Clears an event. If no name is given, all events will be removed. * * @param ?string $name Event name. */ public function clear(?string $name = null): void { if ($name !== null) { unset($this->events[$name]); unset($this->filters[$name]); return; } $this->reset(); } /** * Hooks a callback to an event. * * @param string $name Event name * @param 'before'|'after' $type Filter type. * @param callable(array &$params, mixed &$output): (void|false)|callable(mixed &$output): (void|false) $callback * * @return $this */ public function hook(string $name, string $type, callable $callback): self { static $filterTypes = [self::FILTER_BEFORE, self::FILTER_AFTER]; if (!in_array($type, $filterTypes, true)) { $noticeMessage = "Invalid filter type '$type', use " . join('|', $filterTypes); trigger_error($noticeMessage, E_USER_NOTICE); } if ($type === self::FILTER_AFTER) { $callbackInfo = new ReflectionFunction($callback); $parametersNumber = $callbackInfo->getNumberOfParameters(); if ($parametersNumber === 1) { /** @disregard &$params in after filters are deprecated. */ $callback = fn (array &$params, &$output) => $callback($output); } } $this->filters[$name][$type][] = $callback; return $this; } /** * Executes a chain of method filters. * * @param array &$params, mixed &$output): (void|false)> $filters * Chain of filters. * @param array $params Method parameters. * @param mixed $output Method output. * * @throws Exception If an event throws an `Exception` or if `$filters` contains an invalid filter. */ public function filter(array $filters, array &$params, &$output): void { foreach ($filters as $key => $callback) { if (!is_callable($callback)) { throw new InvalidArgumentException("Invalid callable \$filters[$key]."); } $continue = $callback($params, $output); if ($continue === false) { break; } } } /** * Executes a callback function. * * @param callable-string|(callable(): mixed)|array{class-string|object, string} $callback * Callback function. * @param array $params Function parameters. * * @return mixed Function results. * @throws Exception If `$callback` also throws an `Exception`. */ public function execute($callback, array &$params = []) { if ( is_string($callback) === true && (strpos($callback, '->') !== false || strpos($callback, '::') !== false) ) { $callback = $this->parseStringClassAndMethod($callback); } return $this->invokeCallable($callback, $params); } /** * Parses a string into a class and method. * * @param string $classAndMethod Class and method * * @return array{0: class-string|object, 1: string} Class and method */ public function parseStringClassAndMethod(string $classAndMethod): array { $classParts = explode('->', $classAndMethod); if (count($classParts) === 1) { $classParts = explode('::', $classParts[0]); } return $classParts; } /** * Calls a function. * * @param callable $func Name of function to call. * @param array &$params Function parameters. * * @return mixed Function results. * @deprecated 3.7.0 Use invokeCallable instead */ public function callFunction(callable $func, array &$params = []) { return $this->invokeCallable($func, $params); } /** * Invokes a method. * * @param array{0: class-string|object, 1: string} $func Class method. * @param array &$params Class method parameters. * * @return mixed Function results. * @throws TypeError For nonexistent class name. * @deprecated 3.7.0 Use invokeCallable instead. */ public function invokeMethod(array $func, array &$params = []) { return $this->invokeCallable($func, $params); } /** * Invokes a callable (anonymous function or Class->method). * * @param array{0: class-string|object, 1: string}|callable $func Class method. * @param array &$params Class method parameters. * * @return mixed Function results. * @throws TypeError For nonexistent class name. * @throws InvalidArgumentException If the constructor requires parameters. * @version 3.7.0 */ public function invokeCallable($func, array &$params = []) { // If this is a directly callable function, call it if (is_array($func) === false) { $this->verifyValidFunction($func); return call_user_func_array($func, $params); } [$class, $method] = $func; $mustUseTheContainer = $this->mustUseContainer($class); if ($mustUseTheContainer === true) { $resolvedClass = $this->resolveContainerClass($class, $params); if ($resolvedClass) { $class = $resolvedClass; } } $this->verifyValidClassCallable($class, $method, $resolvedClass ?? null); // Class is a string, and method exists, create the object by hand and inject only the Engine if (is_string($class)) { $class = new $class($this->engine); } return call_user_func_array([$class, $method], $params); } /** * Handles invalid callback types. * * @param callable-string|(callable(): mixed)|array{0: class-string|object, 1: string} $callback * Callback function. * * @throws InvalidArgumentException If `$callback` is an invalid type. */ protected function verifyValidFunction($callback): void { if (is_string($callback) && !function_exists($callback)) { throw new InvalidArgumentException('Invalid callback specified.'); } } /** * Verifies if the provided class and method are valid callable. * * @param class-string|object $class The class name. * @param string $method The method name. * @param object|null $resolvedClass The resolved class. * * @throws Exception If the class or method is not found. */ protected function verifyValidClassCallable($class, $method, $resolvedClass): void { $exception = null; // Final check to make sure it's actually a class and a method, or throw an error if (is_object($class) === false && class_exists($class) === false) { $exception = new Exception("Class '$class' not found. Is it being correctly autoloaded with Flight::path()?"); // If this tried to resolve a class in a container and failed somehow, throw the exception } elseif (!$resolvedClass && $this->containerException !== null) { $exception = $this->containerException; // Class is there, but no method } elseif (is_object($class) === true && method_exists($class, $method) === false) { $classNamespace = get_class($class); $exception = new Exception("Class found, but method '$classNamespace::$method' not found."); } if ($exception !== null) { $this->fixOutputBuffering(); throw $exception; } } /** * Resolves the container class. * * @param class-string $class Class name. * @param array &$params Class constructor parameters. * * @return ?object Class object. */ public function resolveContainerClass(string $class, array &$params) { // PSR-11 if ( is_a($this->containerHandler, '\Psr\Container\ContainerInterface') && $this->containerHandler->has($class) ) { return $this->containerHandler->get($class); } // Just a callable where you configure the behavior (Dice, PHP-DI, etc.) if (is_callable($this->containerHandler)) { /* This is to catch all the error that could be thrown by whatever container you are using */ try { return ($this->containerHandler)($class, $params); // could not resolve a class for some reason } catch (Exception $exception) { // If the container throws an exception, we need to catch it // and store it somewhere. If we just let it throw itself, it // doesn't properly close the output buffers and can cause other // issues. // This is thrown in the verifyValidClassCallable method. $this->containerException = $exception; } } return null; } /** * Checks to see if a container should be used or not. * * @param string|object $class the class to verify * * @return boolean */ public function mustUseContainer($class): bool { return $this->containerHandler !== null && ( (is_object($class) === true && strpos(get_class($class), 'flight\\') === false) || is_string($class) ); } /** Because this could throw an exception in the middle of an output buffer, */ protected function fixOutputBuffering(): void { // Cause PHPUnit has 1 level of output buffering by default if (ob_get_level() > (getenv('PHPUNIT_TEST') ? 1 : 0)) { ob_end_clean(); } } /** * Resets the object to the initial state. * * @return $this */ public function reset(): self { $this->events = []; $this->filters = []; return $this; } }