findHooks.php

Go to the documentation of this file.

<?php
require_once __DIR__ . '/Maintenance.php';

class FindHooks extends Maintenance {
    const FIND_NON_RECURSIVE = 0;
    const FIND_RECURSIVE = 1;

    /*
     * Hooks that are ignored
     */
    protected static $ignore = [ 'testRunLegacyHooks', 'Test' ];

    public function __construct() {
        parent::__construct();
        $this->addDescription( 'Find hooks that are undocumented, missing, or just plain wrong' );
        $this->addOption( 'online', 'Check against MediaWiki.org hook documentation' );
    }

    public function getDbType() {
        return Maintenance::DB_NONE;
    }

    public function execute() {
        global $IP;

        $documentedHooks = $this->getHooksFromDoc( $IP . '/docs/hooks.txt' );
        $potentialHooks = [];
        $badHooks = [];

        $recurseDirs = [
            "$IP/includes/",
            "$IP/mw-config/",
            "$IP/languages/",
            "$IP/maintenance/",
            // Omit $IP/tests/phpunit as it contains hook tests that shouldn't be documented
            "$IP/tests/parser",
            "$IP/tests/phpunit/suites",
        ];
        $nonRecurseDirs = [
            "$IP/",
        ];

        foreach ( $recurseDirs as $dir ) {
            $ret = $this->getHooksFromDir( $dir, self::FIND_RECURSIVE );
            $potentialHooks = array_merge( $potentialHooks, $ret['good'] );
            $badHooks = array_merge( $badHooks, $ret['bad'] );
        }
        foreach ( $nonRecurseDirs as $dir ) {
            $ret = $this->getHooksFromDir( $dir );
            $potentialHooks = array_merge( $potentialHooks, $ret['good'] );
            $badHooks = array_merge( $badHooks, $ret['bad'] );
        }

        $documented = array_keys( $documentedHooks );
        $potential = array_keys( $potentialHooks );
        $potential = array_unique( $potential );
        $badHooks = array_diff( array_unique( $badHooks ), self::$ignore );
        $todo = array_diff( $potential, $documented, self::$ignore );
        $deprecated = array_diff( $documented, $potential, self::$ignore );

        // Check parameter count and references
        $badParameterCount = $badParameterReference = [];
        foreach ( $potentialHooks as $hook => $args ) {
            if ( !isset( $documentedHooks[$hook] ) ) {
                // Not documented, but that will also be in $todo
                continue;
            }
            $argsDoc = $documentedHooks[$hook];
            if ( $args === 'unknown' || $argsDoc === 'unknown' ) {
                // Could not get parameter information
                continue;
            }
            if ( count( $argsDoc ) !== count( $args ) ) {
                $badParameterCount[] = $hook . ': Doc: ' . count( $argsDoc ) . ' vs. Code: ' . count( $args );
            } else {
                // Check if & is equal
                foreach ( $argsDoc as $index => $argDoc ) {
                    $arg = $args[$index];
                    if ( ( $arg[0] === '&' ) !== ( $argDoc[0] === '&' ) ) {
                        $badParameterReference[] = $hook . ': References different: Doc: ' . $argDoc .
                            ' vs. Code: ' . $arg;
                    }
                }
            }
        }

        // Print the results
        $this->printArray( 'Undocumented', $todo );
        $this->printArray( 'Documented and not found', $deprecated );
        $this->printArray( 'Unclear hook calls', $badHooks );
        $this->printArray( 'Different parameter count', $badParameterCount );
        $this->printArray( 'Different parameter reference', $badParameterReference );

        if ( !$todo && !$deprecated && !$badHooks
            && !$badParameterCount && !$badParameterReference
        ) {
            $this->output( "Looks good!\n" );
        } else {
            $this->error( 'The script finished with errors.', 1 );
        }
    }

    private function getHooksFromDoc( $doc ) {
        if ( $this->hasOption( 'online' ) ) {
            return $this->getHooksFromOnlineDoc();
        } else {
            return $this->getHooksFromLocalDoc( $doc );
        }
    }

    private function getHooksFromLocalDoc( $doc ) {
        $m = [];
        $content = file_get_contents( $doc );
        preg_match_all(
            "/\n'(.*?)':.*((?:\n.+)*)/",
            $content,
            $m,
            PREG_SET_ORDER
        );

        // Extract the documented parameter
        $hooks = [];
        foreach ( $m as $match ) {
            $args = [];
            if ( isset( $match[2] ) ) {
                $n = [];
                if ( preg_match_all( "/\n(&?\\$\w+):.+/", $match[2], $n ) ) {
                    $args = $n[1];
                }
            }
            $hooks[$match[1]] = $args;
        }
        return $hooks;
    }

    private function getHooksFromOnlineDoc() {
        $allhooks = $this->getHooksFromOnlineDocCategory( 'MediaWiki_hooks' );
        $removed = $this->getHooksFromOnlineDocCategory( 'Removed_hooks' );
        return array_diff_key( $allhooks, $removed );
    }

    private function getHooksFromOnlineDocCategory( $title ) {
        $params = [
            'action' => 'query',
            'list' => 'categorymembers',
            'cmtitle' => "Category:$title",
            'cmlimit' => 500,
            'format' => 'json',
            'continue' => '',
        ];

        $retval = [];
        while ( true ) {
            $json = Http::get(
                wfAppendQuery( 'http://www.mediawiki.org/w/api.php', $params ),
                [],
                __METHOD__
            );
            $data = FormatJson::decode( $json, true );
            foreach ( $data['query']['categorymembers'] as $page ) {
                if ( preg_match( '/Manual\:Hooks\/([a-zA-Z0-9- :]+)/', $page['title'], $m ) ) {
                    // parameters are unknown, because that needs parsing of wikitext
                    $retval[str_replace( ' ', '_', $m[1] )] = 'unknown';
                }
            }
            if ( !isset( $data['continue'] ) ) {
                return $retval;
            }
            $params = array_replace( $params, $data['continue'] );
        }
    }

    private function getHooksFromFile( $filePath ) {
        $content = file_get_contents( $filePath );
        $m = [];
        preg_match_all(
            // All functions which runs hooks
            '/(?:wfRunHooks|Hooks\:\:run|ContentHandler\:\:runLegacyHooks)\s*\(\s*' .
                // First argument is the hook name as string
                '([\'"])(.*?)\1' .
                // Comma for second argument
                '(?:\s*(,))?' .
                // Second argument must start with array to be processed
                '(?:\s*(?:array\s*\(|\[)' .
                // Matching inside array - allows one deep of brackets
                '((?:[^\(\)\[\]]|\((?-1)\)|\[(?-1)\])*)' .
                // End
                '[\)\]])?/',
            $content,
            $m,
            PREG_SET_ORDER
        );

        // Extract parameter
        $hooks = [];
        foreach ( $m as $match ) {
            $args = [];
            if ( isset( $match[4] ) ) {
                $n = [];
                if ( preg_match_all( '/((?:[^,\(\)]|\([^\(\)]*\))+)/', $match[4], $n ) ) {
                    $args = array_map( 'trim', $n[1] );
                }
            } elseif ( isset( $match[3] ) ) {
                // Found a parameter for Hooks::run,
                // but could not extract the hooks argument,
                // because there are given by a variable
                $args = 'unknown';
            }
            $hooks[$match[2]] = $args;
        }

        return $hooks;
    }

    private function getBadHooksFromFile( $filePath ) {
        $content = file_get_contents( $filePath );
        $m = [];
        // We want to skip the "function wfRunHooks()" one.  :)
        preg_match_all( '/(?<!function )wfRunHooks\(\s*[^\s\'"].*/', $content, $m );
        $list = [];
        foreach ( $m[0] as $match ) {
            $list[] = $match . "(" . $filePath . ")";
        }

        return $list;
    }

    private function getHooksFromDir( $dir, $recurse = 0 ) {
        $good = [];
        $bad = [];

        if ( $recurse === self::FIND_RECURSIVE ) {
            $iterator = new RecursiveIteratorIterator(
                new RecursiveDirectoryIterator( $dir, RecursiveDirectoryIterator::SKIP_DOTS ),
                RecursiveIteratorIterator::SELF_FIRST
            );
        } else {
            $iterator = new DirectoryIterator( $dir );
        }

        foreach ( $iterator as $info ) {
            // Ignore directories, work only on php files,
            if ( $info->isFile() && in_array( $info->getExtension(), [ 'php', 'inc' ] )
                // Skip this file as it contains text that looks like a bad wfRunHooks() call
                && $info->getRealPath() !== __FILE__
            ) {
                $good = array_merge( $good, $this->getHooksFromFile( $info->getRealPath() ) );
                $bad = array_merge( $bad, $this->getBadHooksFromFile( $info->getRealPath() ) );
            }
        }

        return [ 'good' => $good, 'bad' => $bad ];
    }

    private function printArray( $msg, $arr ) {
        asort( $arr );

        foreach ( $arr as $v ) {
            $this->output( "$msg: $v\n" );
        }
    }
}

$maintClass = 'FindHooks';
require_once RUN_MAINTENANCE_IF_MAIN;