findHooks.php

Go to the documentation of this file.

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

class FindHooks extends Maintenance {
    /*
     * Hooks that are ignored
     */
    protected static $ignore = array( 'testRunLegacyHooks' );

    public function __construct() {
        parent::__construct();
        $this->mDescription = '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;

        $documented = $this->getHooksFromDoc( $IP . '/docs/hooks.txt' );
        $potential = array();
        $bad = array();

        // TODO: Don't hardcode the list of directories
        $pathinc = array(
            $IP . '/',
            $IP . '/includes/',
            $IP . '/includes/actions/',
            $IP . '/includes/api/',
            $IP . '/includes/cache/',
            $IP . '/includes/changes/',
            $IP . '/includes/clientpool/',
            $IP . '/includes/content/',
            $IP . '/includes/context/',
            $IP . '/includes/dao/',
            $IP . '/includes/db/',
            $IP . '/includes/debug/',
            $IP . '/includes/deferred/',
            $IP . '/includes/diff/',
            $IP . '/includes/externalstore/',
            $IP . '/includes/filebackend/',
            $IP . '/includes/filerepo/',
            $IP . '/includes/filerepo/file/',
            $IP . '/includes/gallery/',
            $IP . '/includes/htmlform/',
            $IP . '/includes/installer/',
            $IP . '/includes/interwiki/',
            $IP . '/includes/jobqueue/',
            $IP . '/includes/json/',
            $IP . '/includes/logging/',
            $IP . '/includes/media/',
            $IP . '/includes/page/',
            $IP . '/includes/parser/',
            $IP . '/includes/rcfeed/',
            $IP . '/includes/resourceloader/',
            $IP . '/includes/revisiondelete/',
            $IP . '/includes/search/',
            $IP . '/includes/site/',
            $IP . '/includes/skins/',
            $IP . '/includes/specialpage/',
            $IP . '/includes/specials/',
            $IP . '/includes/upload/',
            $IP . '/includes/utils/',
            $IP . '/languages/',
            $IP . '/maintenance/',
            $IP . '/maintenance/language/',
            $IP . '/tests/',
            $IP . '/tests/parser/',
            $IP . '/tests/phpunit/suites/',
        );

        foreach ( $pathinc as $dir ) {
            $potential = array_merge( $potential, $this->getHooksFromPath( $dir ) );
            $bad = array_merge( $bad, $this->getBadHooksFromPath( $dir ) );
        }

        $potential = array_unique( $potential );
        $bad = array_unique( $bad );
        $todo = array_diff( $potential, $documented );
        $deprecated = array_diff( $documented, $potential );

        // let's show the results:
        $this->printArray( 'Undocumented', $todo );
        $this->printArray( 'Documented and not found', $deprecated );
        $this->printArray( 'Unclear hook calls', $bad );

        if ( count( $todo ) == 0 && count( $deprecated ) == 0 && count( $bad ) == 0 ) {
            $this->output( "Looks good!\n" );
        }
    }

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

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

        return array_unique( $m[1] );
    }

    private function getHooksFromOnlineDoc() {
        // All hooks
        $allhookdata = Http::get(
            'http://www.mediawiki.org/w/api.php?action=query&list=categorymembers&'
            . 'cmtitle=Category:MediaWiki_hooks&cmlimit=500&format=php'
        );
        $allhookdata = unserialize( $allhookdata );
        $allhooks = array();
        foreach ( $allhookdata['query']['categorymembers'] as $page ) {
            $found = preg_match( '/Manual\:Hooks\/([a-zA-Z0-9- :]+)/', $page['title'], $matches );
            if ( $found ) {
                $hook = str_replace( ' ', '_', $matches[1] );
                $allhooks[] = $hook;
            }
        }
        // Removed hooks
        $oldhookdata = Http::get(
            'http://www.mediawiki.org/w/api.php?action=query&list=categorymembers&'
            . 'cmtitle=Category:Removed_hooks&cmlimit=500&format=php'
        );
        $oldhookdata = unserialize( $oldhookdata );
        $removed = array();
        foreach ( $oldhookdata['query']['categorymembers'] as $page ) {
            $found = preg_match( '/Manual\:Hooks\/([a-zA-Z0-9- :]+)/', $page['title'], $matches );
            if ( $found ) {
                $hook = str_replace( ' ', '_', $matches[1] );
                $removed[] = $hook;
            }
        }

        return array_diff( $allhooks, $removed );
    }

    private function getHooksFromFile( $file ) {
        $content = file_get_contents( $file );
        $m = array();
        preg_match_all(
            '/(?:wfRunHooks|Hooks\:\:run|ContentHandler\:\:runLegacyHooks)\(\s*([\'"])(.*?)\1/',
            $content,
            $m
        );

        return $m[2];
    }

    private function getHooksFromPath( $path ) {
        $hooks = array();
        $dh = opendir( $path );
        if ( $dh ) {
            while ( ( $file = readdir( $dh ) ) !== false ) {
                if ( filetype( $path . $file ) == 'file' ) {
                    $hooks = array_merge( $hooks, $this->getHooksFromFile( $path . $file ) );
                }
            }
            closedir( $dh );
        }

        return $hooks;
    }

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

        return $list;
    }

    private function getBadHooksFromPath( $path ) {
        $hooks = array();
        $dh = opendir( $path );
        if ( $dh ) {
            while ( ( $file = readdir( $dh ) ) !== false ) {
                # We don't want to read this file as it contains bad calls to wfRunHooks()
                if ( filetype( $path . $file ) == 'file' && !$path . $file == __FILE__ ) {
                    $hooks = array_merge( $hooks, $this->getBadHooksFromFile( $path . $file ) );
                }
            }
            closedir( $dh );
        }

        return $hooks;
    }

    private function printArray( $msg, $arr, $sort = true ) {
        if ( $sort ) {
            asort( $arr );
        }

        foreach ( $arr as $v ) {
            if ( !in_array( $v, self::$ignore ) ) {
                $this->output( "$msg: $v\n" );
            }
        }
    }
}

$maintClass = 'FindHooks';
require_once RUN_MAINTENANCE_IF_MAIN;