Hooks.php

Go to the documentation of this file.

<?php

class Hooks {
    protected static $handlers = [];

    public static function register( $name, $callback ) {
        if ( !isset( self::$handlers[$name] ) ) {
            self::$handlers[$name] = [];
        }

        self::$handlers[$name][] = $callback;
    }

    public static function clear( $name ) {
        if ( !defined( 'MW_PHPUNIT_TEST' ) && !defined( 'MW_PARSER_TEST' ) ) {
            throw new MWException( 'Cannot reset hooks in operation.' );
        }

        unset( self::$handlers[$name] );
    }

    public static function isRegistered( $name ) {
        global $wgHooks;
        return !empty( $wgHooks[$name] ) || !empty( self::$handlers[$name] );
    }

    public static function getHandlers( $name ) {
        global $wgHooks;

        if ( !self::isRegistered( $name ) ) {
            return [];
        } elseif ( !isset( self::$handlers[$name] ) ) {
            return $wgHooks[$name];
        } elseif ( !isset( $wgHooks[$name] ) ) {
            return self::$handlers[$name];
        } else {
            return array_merge( self::$handlers[$name], $wgHooks[$name] );
        }
    }

    private static function callHook( $event, $hook, array $args, $deprecatedVersion = null,
        &$fname = null
    ) {
        // Turn non-array values into an array. (Can't use casting because of objects.)
        if ( !is_array( $hook ) ) {
            $hook = [ $hook ];
        }

        if ( !array_filter( $hook ) ) {
            // Either array is empty or it's an array filled with null/false/empty.
            return null;
        }

        if ( is_array( $hook[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.
            $hook = array_merge( $hook[0], array_slice( $hook, 1 ) );
        }

        if ( $hook[0] instanceof Closure ) {
            $fname = "hook-$event-closure";
            $callback = array_shift( $hook );
        } elseif ( is_object( $hook[0] ) ) {
            $object = array_shift( $hook );
            $method = array_shift( $hook );

            // If no method was specified, default to on$event.
            if ( $method === null ) {
                $method = "on$event";
            }

            $fname = get_class( $object ) . '::' . $method;
            $callback = [ $object, $method ];
        } elseif ( is_string( $hook[0] ) ) {
            $fname = $callback = array_shift( $hook );
        } else {
            throw new MWException( 'Unknown datatype in hooks for ' . $event . "\n" );
        }

        // Run autoloader (workaround for call_user_func_array bug)
        // and throw error if not callable.
        if ( !is_callable( $callback ) ) {
            throw new MWException( 'Invalid callback ' . $fname . ' in hooks for ' . $event . "\n" );
        }

        // mark hook as deprecated, if deprecation version is specified
        if ( $deprecatedVersion !== null ) {
            wfDeprecated( "$event hook (used in $fname)", $deprecatedVersion );
        }

        // Call the hook.
        $hook_args = array_merge( $hook, $args );
        return call_user_func_array( $callback, $hook_args );
    }

    public static function run( $event, array $args = [], $deprecatedVersion = null ) {
        foreach ( self::getHandlers( $event ) as $hook ) {
            $retval = self::callHook( $event, $hook, $args, $deprecatedVersion );
            if ( $retval === null ) {
                continue;
            }

            // Process the return value.
            if ( is_string( $retval ) ) {
                // String returned means error.
                throw new FatalError( $retval );
            } elseif ( $retval === false ) {
                // False was returned. Stop processing, but no error.
                return false;
            }
        }

        return true;
    }

    public static function runWithoutAbort( $event, array $args = [], $deprecatedVersion = null ) {
        foreach ( self::getHandlers( $event ) as $hook ) {
            $fname = null;
            $retval = self::callHook( $event, $hook, $args, $deprecatedVersion, $fname );
            if ( $retval !== null && $retval !== true ) {
                throw new UnexpectedValueException( "Invalid return from $fname for unabortable $event." );
            }
        }
        return true;
    }
}