HookContainer.php

Go to the documentation of this file.

<?php
namespace MediaWiki\HookContainer;
 
use Closure;
use Error;
use InvalidArgumentException;
use LogicException;
use MediaWiki\Debug\MWDebug;
use UnexpectedValueException;
use Wikimedia\Assert\Assert;
use Wikimedia\NonSerializable\NonSerializableTrait;
use Wikimedia\ObjectFactory\ObjectFactory;
use Wikimedia\ScopedCallback;
use Wikimedia\Services\SalvageableService;
use function array_filter;
use function array_keys;
use function array_merge;
use function array_shift;
use function array_unique;
use function is_array;
use function is_object;
use function is_string;
use function strpos;
use function strtr;
 
class HookContainer implements SalvageableService {
    use NonSerializableTrait;
 
    public const NOOP = '*no-op*';
 
    private $handlers = [];
 
    private $handlerObjects = [];
 
    private $registry;
 
    private $extraHandlers = [];
 
    private $objectFactory;
 
    private $nextScopedRegisterId = 0;
 
    public function __construct(
        HookRegistry $hookRegistry,
        ObjectFactory $objectFactory
    ) {
        $this->registry = $hookRegistry;
        $this->objectFactory = $objectFactory;
    }
 
    public function salvage( SalvageableService $other ) {
        Assert::parameterType( self::class, $other, '$other' );
        if ( $this->handlers || $this->handlerObjects || $this->extraHandlers ) {
            throw new LogicException( 'salvage() must be called immediately after construction' );
        }
        $this->handlerObjects = $other->handlerObjects;
        $this->handlers = $other->handlers;
        $this->extraHandlers = $other->extraHandlers;
    }
 
    public function run( string $hook, array $args = [], array $options = [] ): bool {
        $checkDeprecation = isset( $options['deprecatedVersion'] );
 
        $abortable = $options['abortable'] ?? true;
        foreach ( $this->getHandlers( $hook, $options ) as $handler ) {
            if ( $checkDeprecation ) {
                $this->checkDeprecation( $hook, $handler, $options );
            }
 
            // Compose callback arguments.
            if ( !empty( $handler['args'] ) ) {
                $callbackArgs = array_merge( $handler['args'], $args );
            } else {
                $callbackArgs = $args;
            }
            // Call the handler.
            $callback = $handler['callback'];
            $return = $callback( ...$callbackArgs );
 
            // Handler returned false, signal abort to caller
            if ( $return === false ) {
                if ( !$abortable ) {
                    throw new UnexpectedValueException( "Handler {$handler['functionName']}" .
                        " return false for unabortable $hook." );
                }
 
                return false;
            } elseif ( $return !== null && $return !== true ) {
                throw new UnexpectedValueException(
                    "Hook handlers can only return null or a boolean. Got an unexpected value from " .
                    "handler {$handler['functionName']} for $hook" );
            }
        }
 
        return true;
    }
 
    public function clear( string $hook ): void {
        if ( !defined( 'MW_PHPUNIT_TEST' ) ) {
            throw new LogicException( 'Cannot reset hooks in operation.' );
        }
 
        $this->handlers[$hook] = [];
    }
 
    public function scopedRegister( string $hook, $handler ): ScopedCallback {
        $handler = $this->normalizeHandler( $hook, $handler );
        if ( !$handler ) {
            throw new InvalidArgumentException( 'Bad hook handler!' );
        }
 
        $this->checkDeprecation( $hook, $handler );
 
        $id = 'TemporaryHook_' . $this->nextScopedRegisterId++;
 
        $this->getHandlers( $hook );
 
        $this->handlers[$hook][$id] = $handler;
 
        return new ScopedCallback( function () use ( $hook, $id ) {
            unset( $this->handlers[$hook][$id] );
        } );
    }
 
    private function makeExtensionHandlerCallback( string $hook, array $handler, array $options = [] ): array {
        $spec = $handler['handler'];
        $name = $spec['name'];
 
        if (
            !empty( $options['noServices'] ) && (
                !empty( $spec['services'] ) ||
                !empty( $spec['optional_services'] )
            )
        ) {
            throw new UnexpectedValueException(
                "The handler for the hook $hook registered in " .
                "{$handler['extensionPath']} has a service dependency, " .
                "but this hook does not allow it." );
        }
 
        if ( !isset( $this->handlerObjects[$name] ) ) {
            // @phan-suppress-next-line PhanTypeInvalidCallableArraySize
            $this->handlerObjects[$name] = $this->objectFactory->createObject( $spec );
        }
 
        $obj = $this->handlerObjects[$name];
        $method = $this->getHookMethodName( $hook );
 
        return [ $obj, $method ];
    }
 
    private function normalizeHandler( string $hook, $handler, array $options = [] ) {
        if ( is_object( $handler ) && !$handler instanceof Closure ) {
            $handler = [ $handler, $this->getHookMethodName( $hook ) ];
        }
 
        // Backwards compatibility with old-style callable that uses a qualified method name.
        if ( is_array( $handler ) && is_object( $handler[0] ?? false ) && is_string( $handler[1] ?? false ) ) {
            $ofs = strpos( $handler[1], '::' );
 
            if ( $ofs !== false ) {
                $msg = self::callableToString( $handler );
                wfDeprecatedMsg( "Deprecated handler style for hook '$hook': " .
                    "callable using qualified method name ($msg)" );
                $handler[1] = substr( $handler[1], $ofs + 2 );
            }
        }
 
        // Backwards compatibility: support objects wrapped in an array but no method name.
        if ( is_array( $handler ) && is_object( $handler[0] ?? false ) && !isset( $handler[1] ) ) {
            if ( !$handler[0] instanceof Closure ) {
                $handler[1] = $this->getHookMethodName( $hook );
                $msg = self::callableToString( $handler );
                wfDeprecatedMsg( "Deprecated handler style for hook '$hook': object wrapped in array ($msg)" );
            }
        }
 
        // The empty callback is used to represent a no-op handler in some test cases.
        if ( $handler === [] || $handler === null || $handler === false || $handler === self::NOOP ) {
            if ( $handler !== self::NOOP ) {
                wfDeprecatedMsg(
                    "Deprecated handler style for hook '$hook': falsy value, use HookContainer::NOOP instead."
                );
            }
 
            return [
                'callback' => static function () {
                    // no-op
                },
                'functionName' => self::NOOP,
            ];
        }
 
        // Plain callback
        if ( self::mayBeCallable( $handler ) ) {
            return [
                'callback' => $handler,
                'functionName' => self::callableToString( $handler ),
            ];
        }
 
        // Not callable and not an array. Something is wrong.
        if ( !is_array( $handler ) ) {
            return false;
        }
 
        // Empty array or array filled with null/false/empty.
        if ( !array_filter( $handler ) ) {
            return false;
        }
 
        // ExtensionRegistry style handler
        if ( isset( $handler['handler'] ) ) {
            // Skip hooks that both acknowledge deprecation and are deprecated in core
            if ( $handler['deprecated'] ?? false ) {
                $deprecatedHooks = $this->registry->getDeprecatedHooks();
                $deprecated = $deprecatedHooks->isHookDeprecated( $hook );
                if ( $deprecated ) {
                    return false;
                }
            }
 
            $callback = $this->makeExtensionHandlerCallback( $hook, $handler, $options );
            return [
                'callback' => $callback,
                'functionName' => self::callableToString( $callback ),
            ];
        }
 
        // Not an indexed array, something is wrong.
        if ( !isset( $handler[0] ) ) {
            return false;
        }
 
        // Backwards compatibility: support for arrays of the form [ $object, $method, $data... ]
        if ( is_object( $handler[0] ) && is_string( $handler[1] ?? false ) && array_key_exists( 2, $handler ) ) {
            $obj = $handler[0];
            if ( !$obj instanceof Closure ) {
                // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset
                $method = $handler[1];
                $handler = array_merge(
                    [ [ $obj, $method ] ],
                    array_slice( $handler, 2 )
                );
                $msg = self::callableToString( $handler[1] );
                wfDeprecatedMsg( "Deprecated handler style for hook '$hook': callable array with extra data ($msg)" );
            }
        }
 
        // The only option left is an array of the form [ $callable, $data... ]
        $callback = array_shift( $handler );
 
        // Backwards-compatibility for callbacks in the form [ [ $function ], $data ]
        if ( is_array( $callback ) && count( $callback ) === 1 && is_string( $callback[0] ?? null ) ) {
            $callback = $callback[0];
            $msg = self::callableToString( $callback );
            wfDeprecatedMsg( "Deprecated handler style for hook '$hook': function wrapped in array ($msg)" );
        }
 
        if ( !self::mayBeCallable( $callback ) ) {
            return false;
        }
 
        $msg = self::callableToString( $callback );
        wfDeprecatedMsg( "Deprecated handler style for hook '$hook': callable wrapped in array ($msg)" );
        return [
            'callback' => $callback,
            'functionName' => self::callableToString( $callback ),
            'args' => $handler,
        ];
    }
 
    public function isRegistered( string $hook ): bool {
        return (bool)$this->getHandlers( $hook );
    }
 
    public function register( string $hook, $handler ) {
        $this->checkDeprecation( $hook, $handler );
 
        if ( !isset( $this->handlers[$hook] ) ) {
            // Just remember the handler for later.
            // NOTE: It would be nice to normalize immediately. But since some extensions make extensive
            //       use of this method for registering hooks on every call, that could be a performance
            //       issue. This is particularly true if the hook is declared in a way that would require
            //       service objects to be instantiated.
            $this->extraHandlers[$hook][] = $handler;
            return;
        }
 
        $normalized = $this->normalizeHandler( $hook, $handler );
        if ( !$normalized ) {
            throw new InvalidArgumentException( 'Bad hook handler!' );
        }
 
        $this->getHandlers( $hook );
        $this->handlers[$hook][] = $normalized;
    }
 
    public function getHandlerCallbacks( string $hook ): array {
        wfDeprecated( __METHOD__, '1.41' );
        $handlers = $this->getHandlers( $hook );
 
        $callbacks = [];
        foreach ( $handlers as $h ) {
            $callback = $h['callback'];
 
            if ( isset( $h['args'] ) ) {
                // Needs curry in order to pass extra arguments.
                // NOTE: This does not support reference parameters!
                $extraArgs = $h['args'];
                $callbacks[] = static function ( ...$hookArgs ) use ( $callback, $extraArgs ) {
                    return $callback( ...$extraArgs, ...$hookArgs );
                };
            } else {
                $callbacks[] = $callback;
            }
        }
 
        return $callbacks;
    }
 
    public function getHookNames(): array {
        $names = array_merge(
            array_keys( array_filter( $this->handlers ) ),
            array_keys( array_filter( $this->extraHandlers ) ),
            array_keys( array_filter( $this->registry->getGlobalHooks() ) ),
            array_keys( array_filter( $this->registry->getExtensionHooks() ) )
        );
 
        return array_unique( $names );
    }
 
    private function getHandlers( string $hook, array $options = [] ): array {
        if ( !isset( $this->handlers[$hook] ) ) {
            $handlers = [];
            $registeredHooks = $this->registry->getExtensionHooks();
            $configuredHooks = $this->registry->getGlobalHooks();
 
            $rawHandlers = array_merge(
                $configuredHooks[ $hook ] ?? [],
                $registeredHooks[ $hook ] ?? [],
                $this->extraHandlers[ $hook ] ?? [],
            );
 
            foreach ( $rawHandlers as $raw ) {
                $handler = $this->normalizeHandler( $hook, $raw, $options );
                if ( !$handler ) {
                    // XXX: log this?!
                    // NOTE: also happens for deprecated hooks, which is fine!
                    continue;
                }
 
                $handlers[] = $handler;
            }
 
            $this->handlers[ $hook ] = $handlers;
        }
 
        return $this->handlers[ $hook ];
    }
 
    public function getHandlerDescriptions( string $hook ): array {
        $descriptions = [];
 
        if ( isset( $this->handlers[ $hook ] ) ) {
            $rawHandlers = $this->handlers[ $hook ];
        } else {
            $registeredHooks = $this->registry->getExtensionHooks();
            $configuredHooks = $this->registry->getGlobalHooks();
 
            $rawHandlers = array_merge(
                $configuredHooks[ $hook ] ?? [],
                $registeredHooks[ $hook ] ?? [],
                $this->extraHandlers[ $hook ] ?? [],
            );
        }
 
        foreach ( $rawHandlers as $raw ) {
            $descr = $this->describeHandler( $hook, $raw );
 
            if ( $descr ) {
                $descriptions[] = $descr;
            }
        }
 
        return $descriptions;
    }
 
    private function describeHandler( string $hook, $handler ): ?string {
        if ( is_array( $handler ) ) {
            // already normalized
            if ( isset( $handler['functionName'] ) ) {
                return $handler['functionName'];
            }
 
            if ( isset( $handler['callback'] ) ) {
                return self::callableToString( $handler['callback'] );
            }
 
            if ( isset( $handler['handler']['class'] ) ) {
                // New style hook. Avoid instantiating the handler object
                $method = $this->getHookMethodName( $hook );
                return $handler['handler']['class'] . '::' . $method;
            }
        }
 
        $handler = $this->normalizeHandler( $hook, $handler );
        return $handler ? $handler['functionName'] : null;
    }
 
    public function emitDeprecationWarnings() {
        $deprecatedHooks = $this->registry->getDeprecatedHooks();
        $extensionHooks = $this->registry->getExtensionHooks();
 
        foreach ( $extensionHooks as $name => $handlers ) {
            if ( $deprecatedHooks->isHookDeprecated( $name ) ) {
                $deprecationInfo = $deprecatedHooks->getDeprecationInfo( $name );
                if ( !empty( $deprecationInfo['silent'] ) ) {
                    continue;
                }
                $version = $deprecationInfo['deprecatedVersion'] ?? '';
                $component = $deprecationInfo['component'] ?? 'MediaWiki';
                foreach ( $handlers as $handler ) {
                    if ( !isset( $handler['deprecated'] ) || !$handler['deprecated'] ) {
                        MWDebug::sendRawDeprecated(
                            "Hook $name was deprecated in $component $version " .
                            "but is registered in " . $handler['extensionPath']
                        );
                    }
                }
            }
        }
    }
 
    private function checkDeprecation( string $hook, $handler, ?array $deprecationInfo = null ): void {
        if ( !$deprecationInfo ) {
            $deprecatedHooks = $this->registry->getDeprecatedHooks();
            $deprecationInfo = $deprecatedHooks->getDeprecationInfo( $hook );
        }
 
        if ( $deprecationInfo && empty( $deprecationInfo['silent'] ) ) {
            $description = $this->describeHandler( $hook, $handler );
            wfDeprecated(
                "$hook hook (used in $description)",
                $deprecationInfo['deprecatedVersion'] ?? false,
                $deprecationInfo['component'] ?? false
            );
        }
    }
 
    private static function callableToString( $callable ): string {
        if ( is_string( $callable ) ) {
            return $callable;
        }
 
        if ( $callable instanceof Closure ) {
            $hash = spl_object_hash( $callable );
            return "*closure#$hash*";
        }
 
        if ( is_array( $callable ) ) {
            [ $on, $func ] = $callable;
 
            if ( is_object( $on ) ) {
                $on = get_class( $on );
            }
 
            return "$on::$func";
        }
 
        throw new InvalidArgumentException( 'Unexpected kind of callable' );
    }
 
    private function getHookMethodName( string $hook ): string {
        $hook = strtr( $hook, ':\\-', '___' );
        return "on$hook";
    }
 
    private static function mayBeCallable( $v ): bool {
        try {
            return is_callable( $v );
        } catch ( Error $error ) {
            // If the callable uses a class that can't be loaded because it extends an unknown base class.
            // Continue as if is_callable had returned true, to allow the handler to be registered.
            if ( preg_match( '/Class.*not found/', $error->getMessage() ) ) {
                return true;
            }
 
            throw $error;
        }
    }
}