Hooks.php

Go to the documentation of this file.

<?php

class MWHookException extends MWException {
}

class Hooks {
    protected static $handlers = array();

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

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

    public static function clear( $name ) {
        if ( !defined( 'MW_PHPUNIT_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 array();
        } 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] );
        }
    }

    public static function run( $event, array $args = array(), $deprecatedVersion = null ) {
        wfProfileIn( 'hook: ' . $event );
        foreach ( self::getHandlers( $event ) as $hook ) {
            // Turn non-array values into an array. (Can't use casting because of objects.)
            if ( !is_array( $hook ) ) {
                $hook = array( $hook );
            }

            if ( !array_filter( $hook ) ) {
                // Either array is empty or it's an array filled with null/false/empty.
                continue;
            } elseif ( 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 ) {
                $func = "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";
                }

                $func = get_class( $object ) . '::' . $method;
                $callback = array( $object, $method );
            } elseif ( is_string( $hook[0] ) ) {
                $func = $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 in hooks for ' . $event . "\n" );
            }

            /*
             * Call the hook. The documentation of call_user_func_array says
             * false is returned on failure. However, if the function signature
             * does not match the call signature, PHP will issue an warning and
             * return null instead. The following code catches that warning and
             * provides better error message.
             */
            $retval = null;
            $badhookmsg = null;
            $hook_args = array_merge( $hook, $args );

            // Profile first in case the Profiler causes errors.
            wfProfileIn( $func );
            set_error_handler( 'Hooks::hookErrorHandler' );

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

            try {
                $retval = call_user_func_array( $callback, $hook_args );
            } catch ( MWHookException $e ) {
                $badhookmsg = $e->getMessage();
            } catch ( Exception $e ) {
                restore_error_handler();
                throw $e;
            }
            restore_error_handler();
            wfProfileOut( $func );

            // Process the return value.
            if ( is_string( $retval ) ) {
                // String returned means error.
                throw new FatalError( $retval );
            } elseif ( $badhookmsg !== null ) {
                // Exception was thrown from Hooks::hookErrorHandler.
                throw new MWException(
                    'Detected bug in an extension! ' .
                    "Hook $func has invalid call signature; " . $badhookmsg
                );
            } elseif ( $retval === false ) {
                wfProfileOut( 'hook: ' . $event );
                // False was returned. Stop processing, but no error.
                return false;
            }
        }

        wfProfileOut( 'hook: ' . $event );
        return true;
    }

    public static function hookErrorHandler( $errno, $errstr ) {
        if ( strpos( $errstr, 'expected to be a reference, value given' ) !== false ) {
            throw new MWHookException( $errstr, $errno );
        }
        return false;
    }
}