HookContainer.php

Go to the documentation of this file.

<?php
namespace MediaWiki\HookContainer;
 
use Closure;
use MWDebug;
use MWException;
use UnexpectedValueException;
use Wikimedia\Assert\Assert;
use Wikimedia\ObjectFactory;
use Wikimedia\ScopedCallback;
use Wikimedia\Services\SalvageableService;
 
class HookContainer implements SalvageableService {
 
    private $legacyRegisteredHandlers = [];
 
    private $handlersByName = [];
 
    private $registry;
 
    private $objectFactory;
 
    private $nextScopedRegisterId = 0;
 
    private $originalHooks;
 
    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->legacyRegisteredHandlers || $this->handlersByName ) {
            throw new MWException( 'salvage() must be called immediately after construction' );
        }
        $this->handlersByName = $other->handlersByName;
        $this->legacyRegisteredHandlers = $other->legacyRegisteredHandlers;
    }
 
    public function run( string $hook, array $args = [], array $options = [] ) : bool {
        $legacyHandlers = $this->getLegacyHandlers( $hook );
        $options = array_merge(
            $this->registry->getDeprecatedHooks()->getDeprecationInfo( $hook ) ?? [],
            $options
        );
        // Equivalent of legacy Hooks::runWithoutAbort()
        $notAbortable = ( isset( $options['abortable'] ) && $options['abortable'] === false );
        foreach ( $legacyHandlers as $handler ) {
            $normalizedHandler = $this->normalizeHandler( $handler, $hook );
            if ( $normalizedHandler ) {
                $functionName = $normalizedHandler['functionName'];
                $return = $this->callLegacyHook( $hook, $normalizedHandler, $args, $options );
                if ( $notAbortable && $return !== null && $return !== true ) {
                    throw new UnexpectedValueException( "Invalid return from $functionName" .
                        " for unabortable $hook." );
                }
                if ( $return === false ) {
                    return false;
                }
                if ( is_string( $return ) ) {
                    wfDeprecatedMsg(
                        "Returning a string from a hook handler is deprecated since MediaWiki 1.35 ' .
                         '(done by $functionName for $hook)",
                        '1.35', false, false
                    );
                    throw new UnexpectedValueException( $return );
                }
            }
        }
 
        $handlers = $this->getHandlers( $hook, $options );
        $funcName = 'on' . strtr( ucfirst( $hook ), ':-', '__' );
 
        foreach ( $handlers as $handler ) {
            $return = $handler->$funcName( ...$args );
            if ( $notAbortable && $return !== null && $return !== true ) {
                throw new UnexpectedValueException(
                    "Invalid return from " . $funcName . " for unabortable $hook."
                );
            }
            if ( $return === false ) {
                return false;
            }
            if ( $return !== null && !is_bool( $return ) ) {
                throw new UnexpectedValueException( "Invalid return from " . $funcName . " for $hook." );
            }
        }
        return true;
    }
 
    public function clear( string $hook ) : void {
        if ( !defined( 'MW_PHPUNIT_TEST' ) && !defined( 'MW_PARSER_TEST' ) ) {
            throw new MWException( 'Cannot reset hooks in operation.' );
        }
        unset( $this->legacyRegisteredHandlers[$hook] ); // dynamically registered legacy handlers
    }
 
    public function scopedRegister( string $hook, $callback, bool $replace = false ) : ScopedCallback {
        if ( $replace ) {
            // Stash any previously registered hooks
            if ( !isset( $this->originalHooks[$hook] ) &&
                isset( $this->legacyRegisteredHandlers[$hook] )
            ) {
                $this->originalHooks[$hook] = $this->legacyRegisteredHandlers[$hook];
            }
            $this->legacyRegisteredHandlers[$hook] = [ $callback ];
            return new ScopedCallback( function () use ( $hook ) {
                unset( $this->legacyRegisteredHandlers[$hook] );
            } );
        }
        $id = $this->nextScopedRegisterId++;
        $this->legacyRegisteredHandlers[$hook][$id] = $callback;
        return new ScopedCallback( function () use ( $hook, $id ) {
            unset( $this->legacyRegisteredHandlers[$hook][$id] );
        } );
    }
 
    public function getOriginalHooksForTest() {
        if ( !defined( 'MW_PHPUNIT_TEST' ) && !defined( 'MW_PARSER_TEST' ) ) {
            throw new MWException( 'Cannot get original hooks outside when not in test mode' );
        }
        return $this->originalHooks ?? [];
    }
 
    private function normalizeHandler( $handler, string $hook ) {
        $normalizedHandler = $handler;
        if ( !is_array( $handler ) ) {
            $normalizedHandler = [ $normalizedHandler ];
        }
 
        // Empty array or array filled with null/false/empty.
        if ( !array_filter( $normalizedHandler ) ) {
            return false;
        }
 
        if ( is_array( $normalizedHandler[0] ) ) {
            // First element is an array, meaning the developer intended
            // the first element to be a callback. Merge it in so that
            // processing can be uniform.
            $normalizedHandler = array_merge( $normalizedHandler[0], array_slice( $normalizedHandler, 1 ) );
        }
 
        $firstArg = $normalizedHandler[0];
 
        // Extract function name, handler callback, and any arguments for the callback
        if ( $firstArg instanceof Closure ) {
            $functionName = "hook-$hook-closure";
            $callback = array_shift( $normalizedHandler );
        } elseif ( is_object( $firstArg ) ) {
            $object = array_shift( $normalizedHandler );
            $functionName = array_shift( $normalizedHandler );
 
            // If no method was specified, default to on$event
            if ( $functionName === null ) {
                $functionName = "on$hook";
            } else {
                $colonPos = strpos( $functionName, '::' );
                if ( $colonPos !== false ) {
                    // Some extensions use [ $object, 'Class::func' ] which
                    // worked with call_user_func_array() but doesn't work now
                    // that we use a plain variadic call
                    $functionName = substr( $functionName, $colonPos + 2 );
                }
            }
 
            $callback = [ $object, $functionName ];
        } elseif ( is_string( $firstArg ) ) {
            if ( is_callable( $normalizedHandler, true, $functionName )
                && class_exists( $firstArg ) // $firstArg can be a function in global scope
            ) {
                $callback = $normalizedHandler;
                $normalizedHandler = []; // Can't pass arguments here
            } else {
                $functionName = $callback = array_shift( $normalizedHandler );
            }
        } else {
            throw new UnexpectedValueException( 'Unknown datatype in hooks for ' . $hook );
        }
 
        return [
            'callback' => $callback,
            'args' => $normalizedHandler,
            'functionName' => $functionName,
        ];
    }
 
    private function callLegacyHook( string $hook, $handler, array $args, array $options ) {
        $callback = $handler['callback'];
        $hookArgs = array_merge( $handler['args'], $args );
        if ( isset( $options['deprecatedVersion'] ) && empty( $options['silent'] ) ) {
            wfDeprecated(
                "$hook hook (used in " . $handler['functionName'] . ")",
                $options['deprecatedVersion'] ?? false,
                $options['component'] ?? false
            );
        }
        // Call the hooks
        return $callback( ...$hookArgs );
    }
 
    public function isRegistered( string $hook ) : bool {
        $legacyRegisteredHook = !empty( $this->registry->getGlobalHooks()[$hook] ) ||
            !empty( $this->legacyRegisteredHandlers[$hook] );
        $registeredHooks = $this->registry->getExtensionHooks();
        return !empty( $registeredHooks[$hook] ) || $legacyRegisteredHook;
    }
 
    public function register( string $hook, $callback ) {
        $deprecatedHooks = $this->registry->getDeprecatedHooks();
        $deprecated = $deprecatedHooks->isHookDeprecated( $hook );
        if ( $deprecated ) {
            $info = $deprecatedHooks->getDeprecationInfo( $hook );
            if ( empty( $info['silent'] ) ) {
                $deprecatedVersion = $info['deprecatedVersion'] ?? false;
                $component = $info['component'] ?? false;
                wfDeprecated(
                    "$hook hook", $deprecatedVersion, $component
                );
            }
        }
        $this->legacyRegisteredHandlers[$hook][] = $callback;
    }
 
    public function getLegacyHandlers( string $hook ) : array {
        $handlers = array_merge(
            $this->legacyRegisteredHandlers[$hook] ?? [],
            $this->registry->getGlobalHooks()[$hook] ?? []
        );
        return $handlers;
    }
 
    public function getHandlers( string $hook, array $options = [] ) : array {
        $handlers = [];
        $deprecatedHooks = $this->registry->getDeprecatedHooks();
        $registeredHooks = $this->registry->getExtensionHooks();
        if ( isset( $registeredHooks[$hook] ) ) {
            foreach ( $registeredHooks[$hook] as $hookReference ) {
                // Non-legacy hooks have handler attributes
                $handlerSpec = $hookReference['handler'];
                // Skip hooks that both acknowledge deprecation and are deprecated in core
                $flaggedDeprecated = !empty( $hookReference['deprecated'] );
                $deprecated = $deprecatedHooks->isHookDeprecated( $hook );
                if ( $deprecated && $flaggedDeprecated ) {
                    continue;
                }
                $handlerName = $handlerSpec['name'];
                if ( !empty( $options['noServices'] ) && isset( $handlerSpec['services'] ) ) {
                    throw new UnexpectedValueException(
                        "The handler for the hook $hook registered in " .
                        "{$hookReference['extensionPath']} has a service dependency, " .
                        "but this hook does not allow it." );
                }
                if ( !isset( $this->handlersByName[$handlerName] ) ) {
                    $this->handlersByName[$handlerName] =
                        $this->objectFactory->createObject( $handlerSpec );
                }
                $handlers[] = $this->handlersByName[$handlerName];
            }
        }
        return $handlers;
    }
 
    public function emitDeprecationWarnings() {
        $deprecatedHooks = $this->registry->getDeprecatedHooks();
        $registeredHooks = $this->registry->getExtensionHooks();
        foreach ( $registeredHooks 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']
                        );
                    }
                }
            }
        }
    }
}