ApiStructureTest.php

Go to the documentation of this file.

<?php
 
use Wikimedia\TestingAccessWrapper;
 
class ApiStructureTest extends MediaWikiTestCase {
 
    private static $main;
 
    private static $testGlobals = [
        [
            'MiserMode' => false,
        ],
        [
            'MiserMode' => true,
        ],
    ];
 
    private static $paramTypes = [
        // ApiBase::PARAM_DFLT => as appropriate for PARAM_TYPE
        ApiBase::PARAM_ISMULTI => [ 'boolean' ],
        ApiBase::PARAM_TYPE => [ 'string', [ 'string' ] ],
        ApiBase::PARAM_MAX => [ 'integer' ],
        ApiBase::PARAM_MAX2 => [ 'integer' ],
        ApiBase::PARAM_MIN => [ 'integer' ],
        ApiBase::PARAM_ALLOW_DUPLICATES => [ 'boolean' ],
        ApiBase::PARAM_DEPRECATED => [ 'boolean' ],
        ApiBase::PARAM_REQUIRED => [ 'boolean' ],
        ApiBase::PARAM_RANGE_ENFORCE => [ 'boolean' ],
        ApiBase::PARAM_HELP_MSG => [ 'string', 'array', Message::class ],
        ApiBase::PARAM_HELP_MSG_APPEND => [ [ 'string', 'array', Message::class ] ],
        ApiBase::PARAM_HELP_MSG_INFO => [ [ 'array' ] ],
        ApiBase::PARAM_VALUE_LINKS => [ [ 'string' ] ],
        ApiBase::PARAM_HELP_MSG_PER_VALUE => [ [ 'string', 'array', Message::class ] ],
        ApiBase::PARAM_SUBMODULE_MAP => [ [ 'string' ] ],
        ApiBase::PARAM_SUBMODULE_PARAM_PREFIX => [ 'string' ],
        ApiBase::PARAM_ALL => [ 'boolean', 'string' ],
        ApiBase::PARAM_EXTRA_NAMESPACES => [ [ 'integer' ] ],
        ApiBase::PARAM_SENSITIVE => [ 'boolean' ],
        ApiBase::PARAM_DEPRECATED_VALUES => [ 'array' ],
        ApiBase::PARAM_ISMULTI_LIMIT1 => [ 'integer' ],
        ApiBase::PARAM_ISMULTI_LIMIT2 => [ 'integer' ],
        ApiBase::PARAM_MAX_BYTES => [ 'integer' ],
        ApiBase::PARAM_MAX_CHARS => [ 'integer' ],
        ApiBase::PARAM_TEMPLATE_VARS => [ 'array' ],
    ];
 
    // param => [ other param that must be present => required value or null ]
    private static $paramRequirements = [
        ApiBase::PARAM_ALLOW_DUPLICATES => [ ApiBase::PARAM_ISMULTI => true ],
        ApiBase::PARAM_ALL => [ ApiBase::PARAM_ISMULTI => true ],
        ApiBase::PARAM_ISMULTI_LIMIT1 => [
            ApiBase::PARAM_ISMULTI => true,
            ApiBase::PARAM_ISMULTI_LIMIT2 => null,
        ],
        ApiBase::PARAM_ISMULTI_LIMIT2 => [
            ApiBase::PARAM_ISMULTI => true,
            ApiBase::PARAM_ISMULTI_LIMIT1 => null,
        ],
    ];
 
    // param => type(s) allowed for this param ('array' is any array)
    private static $paramAllowedTypes = [
        ApiBase::PARAM_MAX => [ 'integer', 'limit' ],
        ApiBase::PARAM_MAX2 => 'limit',
        ApiBase::PARAM_MIN => [ 'integer', 'limit' ],
        ApiBase::PARAM_RANGE_ENFORCE => 'integer',
        ApiBase::PARAM_VALUE_LINKS => 'array',
        ApiBase::PARAM_HELP_MSG_PER_VALUE => 'array',
        ApiBase::PARAM_SUBMODULE_MAP => 'submodule',
        ApiBase::PARAM_SUBMODULE_PARAM_PREFIX => 'submodule',
        ApiBase::PARAM_ALL => 'array',
        ApiBase::PARAM_EXTRA_NAMESPACES => 'namespace',
        ApiBase::PARAM_DEPRECATED_VALUES => 'array',
        ApiBase::PARAM_MAX_BYTES => [ 'NULL', 'string', 'text', 'password' ],
        ApiBase::PARAM_MAX_CHARS => [ 'NULL', 'string', 'text', 'password' ],
    ];
 
    private static $paramProhibitedTypes = [
        ApiBase::PARAM_ISMULTI => [ 'boolean', 'limit', 'upload' ],
        ApiBase::PARAM_ALL => 'namespace',
        ApiBase::PARAM_SENSITIVE => 'password',
    ];
 
    private static $constantNames = null;
 
    private static function getMain() {
        if ( !self::$main ) {
            self::$main = new ApiMain( RequestContext::getMain() );
            self::$main->getContext()->setLanguage( 'en' );
            self::$main->getContext()->setTitle(
                Title::makeTitle( NS_SPECIAL, 'Badtitle/dummy title for ApiStructureTest' )
            );
        }
        return self::$main;
    }
 
    private function checkMessage( $msg, $what ) {
        $msg = ApiBase::makeMessage( $msg, self::getMain()->getContext() );
        $this->assertInstanceOf( Message::class, $msg, "$what message" );
        $this->assertTrue( $msg->exists(), "$what message {$msg->getKey()} exists" );
    }
 
    public function testDocumentationExists( $path, array $globals ) {
        $main = self::getMain();
 
        // Set configuration variables
        $main->getContext()->setConfig( new MultiConfig( [
            new HashConfig( $globals ),
            RequestContext::getMain()->getConfig(),
        ] ) );
        foreach ( $globals as $k => $v ) {
            $this->setMwGlobals( "wg$k", $v );
        }
 
        // Fetch module.
        $module = TestingAccessWrapper::newFromObject( $main->getModuleFromPath( $path ) );
 
        // Test messages for flags.
        foreach ( $module->getHelpFlags() as $flag ) {
            $this->checkMessage( "api-help-flag-$flag", "Flag $flag" );
        }
 
        // Module description messages.
        $this->checkMessage( $module->getSummaryMessage(), 'Module summary' );
        $this->checkMessage( $module->getExtendedDescription(), 'Module help top text' );
 
        // Parameters. Lots of messages in here.
        $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
        $tags = [];
        foreach ( $params as $name => $settings ) {
            if ( !is_array( $settings ) ) {
                $settings = [];
            }
 
            // Basic description message
            if ( isset( $settings[ApiBase::PARAM_HELP_MSG] ) ) {
                $msg = $settings[ApiBase::PARAM_HELP_MSG];
            } else {
                $msg = "apihelp-{$path}-param-{$name}";
            }
            $this->checkMessage( $msg, "Parameter $name description" );
 
            // If param-per-value is in use, each value's message
            if ( isset( $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE] ) ) {
                $this->assertInternalType( 'array', $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE],
                    "Parameter $name PARAM_HELP_MSG_PER_VALUE is array" );
                $this->assertInternalType( 'array', $settings[ApiBase::PARAM_TYPE],
                    "Parameter $name PARAM_TYPE is array for msg-per-value mode" );
                $valueMsgs = $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE];
                foreach ( $settings[ApiBase::PARAM_TYPE] as $value ) {
                    if ( isset( $valueMsgs[$value] ) ) {
                        $msg = $valueMsgs[$value];
                    } else {
                        $msg = "apihelp-{$path}-paramvalue-{$name}-{$value}";
                    }
                    $this->checkMessage( $msg, "Parameter $name value $value" );
                }
            }
 
            // Appended messages (e.g. "disabled in miser mode")
            if ( isset( $settings[ApiBase::PARAM_HELP_MSG_APPEND] ) ) {
                $this->assertInternalType( 'array', $settings[ApiBase::PARAM_HELP_MSG_APPEND],
                    "Parameter $name PARAM_HELP_MSG_APPEND is array" );
                foreach ( $settings[ApiBase::PARAM_HELP_MSG_APPEND] as $i => $msg ) {
                    $this->checkMessage( $msg, "Parameter $name HELP_MSG_APPEND #$i" );
                }
            }
 
            // Info tags (e.g. "only usable in mode 1") are typically shared by
            // several parameters, so accumulate them and test them later.
            if ( !empty( $settings[ApiBase::PARAM_HELP_MSG_INFO] ) ) {
                foreach ( $settings[ApiBase::PARAM_HELP_MSG_INFO] as $i ) {
                    $tags[array_shift( $i )] = 1;
                }
            }
        }
 
        // Info tags (e.g. "only usable in mode 1") accumulated above
        foreach ( $tags as $tag => $dummy ) {
            $this->checkMessage( "apihelp-{$path}-paraminfo-{$tag}", "HELP_MSG_INFO tag $tag" );
        }
 
        // Messages for examples.
        foreach ( $module->getExamplesMessages() as $qs => $msg ) {
            $this->assertStringStartsNotWith( 'api.php?', $qs,
                "Query string must not begin with 'api.php?'" );
            $this->checkMessage( $msg, "Example $qs" );
        }
    }
 
    public static function provideDocumentationExists() {
        $main = self::getMain();
        $paths = self::getSubModulePaths( $main->getModuleManager() );
        array_unshift( $paths, $main->getModulePath() );
 
        $ret = [];
        foreach ( $paths as $path ) {
            foreach ( self::$testGlobals as $globals ) {
                $g = [];
                foreach ( $globals as $k => $v ) {
                    $g[] = "$k=" . var_export( $v, 1 );
                }
                $k = "Module $path with " . implode( ', ', $g );
                $ret[$k] = [ $path, $globals ];
            }
        }
        return $ret;
    }
 
    public function testParameterConsistency( $path ) {
        $main = self::getMain();
        $module = TestingAccessWrapper::newFromObject( $main->getModuleFromPath( $path ) );
 
        $paramsPlain = $module->getFinalParams();
        $paramsForHelp = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
 
        // avoid warnings about empty tests when no parameter needs to be checked
        $this->assertTrue( true );
 
        if ( self::$constantNames === null ) {
            self::$constantNames = [];
 
            foreach ( ( new ReflectionClass( 'ApiBase' ) )->getConstants() as $key => $val ) {
                if ( substr( $key, 0, 6 ) === 'PARAM_' ) {
                    self::$constantNames[$val] = $key;
                }
            }
        }
 
        foreach ( [ $paramsPlain, $paramsForHelp ] as $params ) {
            foreach ( $params as $param => $config ) {
                if ( !is_array( $config ) ) {
                    $config = [ ApiBase::PARAM_DFLT => $config ];
                }
                if ( !isset( $config[ApiBase::PARAM_TYPE] ) ) {
                    $config[ApiBase::PARAM_TYPE] = isset( $config[ApiBase::PARAM_DFLT] )
                        ? gettype( $config[ApiBase::PARAM_DFLT] )
                        : 'NULL';
                }
 
                foreach ( self::$paramTypes as $key => $types ) {
                    if ( !isset( $config[$key] ) ) {
                        continue;
                    }
                    $keyName = self::$constantNames[$key];
                    $this->validateType( $types, $config[$key], $param, $keyName );
                }
 
                foreach ( self::$paramRequirements as $key => $required ) {
                    if ( !isset( $config[$key] ) ) {
                        continue;
                    }
                    foreach ( $required as $requireKey => $requireVal ) {
                        $this->assertArrayHasKey( $requireKey, $config,
                            "$param: When " . self::$constantNames[$key] . " is set, " .
                            self::$constantNames[$requireKey] . " must also be set" );
                        if ( $requireVal !== null ) {
                            $this->assertSame( $requireVal, $config[$requireKey],
                                "$param: When " . self::$constantNames[$key] . " is set, " .
                                self::$constantNames[$requireKey] . " must equal " .
                                var_export( $requireVal, true ) );
                        }
                    }
                }
 
                foreach ( self::$paramAllowedTypes as $key => $allowedTypes ) {
                    if ( !isset( $config[$key] ) ) {
                        continue;
                    }
 
                    $actualType = is_array( $config[ApiBase::PARAM_TYPE] )
                        ? 'array' : $config[ApiBase::PARAM_TYPE];
 
                    $this->assertContains(
                        $actualType,
                        (array)$allowedTypes,
                        "$param: " . self::$constantNames[$key] .
                            " can only be used with PARAM_TYPE " .
                            implode( ', ', (array)$allowedTypes )
                    );
                }
 
                foreach ( self::$paramProhibitedTypes as $key => $prohibitedTypes ) {
                    if ( !isset( $config[$key] ) ) {
                        continue;
                    }
 
                    $actualType = is_array( $config[ApiBase::PARAM_TYPE] )
                        ? 'array' : $config[ApiBase::PARAM_TYPE];
 
                    $this->assertNotContains(
                        $actualType,
                        (array)$prohibitedTypes,
                        "$param: " . self::$constantNames[$key] .
                            " cannot be used with PARAM_TYPE " .
                            implode( ', ', (array)$prohibitedTypes )
                    );
                }
 
                if ( isset( $config[ApiBase::PARAM_DFLT] ) ) {
                    $this->assertFalse(
                        isset( $config[ApiBase::PARAM_REQUIRED] ) &&
                            $config[ApiBase::PARAM_REQUIRED],
                        "$param: A required parameter cannot have a default" );
 
                    $this->validateDefault( $param, $config );
                }
 
                if ( $config[ApiBase::PARAM_TYPE] === 'limit' ) {
                    $this->assertTrue(
                        isset( $config[ApiBase::PARAM_MAX] ) &&
                            isset( $config[ApiBase::PARAM_MAX2] ),
                        "$param: PARAM_MAX and PARAM_MAX2 are required for limits"
                    );
                    $this->assertGreaterThanOrEqual(
                        $config[ApiBase::PARAM_MAX],
                        $config[ApiBase::PARAM_MAX2],
                        "$param: PARAM_MAX cannot be greater than PARAM_MAX2"
                    );
                }
 
                if (
                    isset( $config[ApiBase::PARAM_MIN] ) &&
                    isset( $config[ApiBase::PARAM_MAX] )
                ) {
                    $this->assertGreaterThanOrEqual(
                        $config[ApiBase::PARAM_MIN],
                        $config[ApiBase::PARAM_MAX],
                        "$param: PARAM_MIN cannot be greater than PARAM_MAX"
                    );
                }
 
                if ( isset( $config[ApiBase::PARAM_RANGE_ENFORCE] ) ) {
                    $this->assertTrue(
                        isset( $config[ApiBase::PARAM_MIN] ) ||
                            isset( $config[ApiBase::PARAM_MAX] ),
                        "$param: PARAM_RANGE_ENFORCE can only be set together with " .
                            "PARAM_MIN or PARAM_MAX"
                    );
                }
 
                if ( isset( $config[ApiBase::PARAM_DEPRECATED_VALUES] ) ) {
                    foreach ( $config[ApiBase::PARAM_DEPRECATED_VALUES] as $key => $unused ) {
                        $this->assertContains( $key, $config[ApiBase::PARAM_TYPE],
                            "$param: Deprecated value \"$key\" is not allowed, " .
                            "how can it be deprecated?" );
                    }
                }
 
                if (
                    isset( $config[ApiBase::PARAM_ISMULTI_LIMIT1] ) ||
                    isset( $config[ApiBase::PARAM_ISMULTI_LIMIT2] )
                ) {
                    $this->assertGreaterThanOrEqual( 0, $config[ApiBase::PARAM_ISMULTI_LIMIT1],
                        "$param: PARAM_ISMULTI_LIMIT1 cannot be negative" );
                    // Zero for both doesn't make sense, but you could have
                    // zero for non-bots
                    $this->assertGreaterThanOrEqual( 1, $config[ApiBase::PARAM_ISMULTI_LIMIT2],
                        "$param: PARAM_ISMULTI_LIMIT2 cannot be negative or zero" );
                    $this->assertGreaterThanOrEqual(
                        $config[ApiBase::PARAM_ISMULTI_LIMIT1],
                        $config[ApiBase::PARAM_ISMULTI_LIMIT2],
                        "$param: PARAM_ISMULTI limit cannot be smaller for users with " .
                            "apihighlimits rights" );
                }
 
                if ( isset( $config[ApiBase::PARAM_MAX_BYTES] ) ) {
                    $this->assertGreaterThanOrEqual( 1, $config[ApiBase::PARAM_MAX_BYTES],
                        "$param: PARAM_MAX_BYTES cannot be negative or zero" );
                }
 
                if ( isset( $config[ApiBase::PARAM_MAX_CHARS] ) ) {
                    $this->assertGreaterThanOrEqual( 1, $config[ApiBase::PARAM_MAX_CHARS],
                        "$param: PARAM_MAX_CHARS cannot be negative or zero" );
                }
 
                if (
                    isset( $config[ApiBase::PARAM_MAX_BYTES] ) &&
                    isset( $config[ApiBase::PARAM_MAX_CHARS] )
                ) {
                    // Length of a string in chars is always <= length in bytes,
                    // so PARAM_MAX_CHARS is pointless if > PARAM_MAX_BYTES
                    $this->assertGreaterThanOrEqual(
                        $config[ApiBase::PARAM_MAX_CHARS],
                        $config[ApiBase::PARAM_MAX_BYTES],
                        "$param: PARAM_MAX_BYTES cannot be less than PARAM_MAX_CHARS"
                    );
                }
 
                if ( isset( $config[ApiBase::PARAM_TEMPLATE_VARS] ) ) {
                    $this->assertNotSame( [], $config[ApiBase::PARAM_TEMPLATE_VARS],
                        "$param: PARAM_TEMPLATE_VARS cannot be empty" );
                    foreach ( $config[ApiBase::PARAM_TEMPLATE_VARS] as $key => $target ) {
                        $this->assertRegExp( '/^[^{}]+$/', $key,
                            "$param: PARAM_TEMPLATE_VARS key may not contain '{' or '}'" );
 
                        $this->assertContains( '{' . $key . '}', $param,
                            "$param: Name must contain PARAM_TEMPLATE_VARS key {" . $key . "}" );
                        $this->assertArrayHasKey( $target, $params,
                            "$param: PARAM_TEMPLATE_VARS target parameter '$target' does not exist" );
                        $config2 = $params[$target];
                        $this->assertTrue( !empty( $config2[ApiBase::PARAM_ISMULTI] ),
                            "$param: PARAM_TEMPLATE_VARS target parameter '$target' must have PARAM_ISMULTI = true" );
 
                        if ( isset( $config2[ApiBase::PARAM_TEMPLATE_VARS] ) ) {
                            $this->assertNotSame( $param, $target,
                                "$param: PARAM_TEMPLATE_VARS cannot target itself" );
 
                            $this->assertArraySubset(
                                $config2[ApiBase::PARAM_TEMPLATE_VARS],
                                $config[ApiBase::PARAM_TEMPLATE_VARS],
                                true,
                                "$param: PARAM_TEMPLATE_VARS target parameter '$target': "
                                . "the target's PARAM_TEMPLATE_VARS must be a subset of the original."
                            );
                        }
                    }
 
                    $keys = implode( '|',
                        array_map(
                            function ( $key ) {
                                return preg_quote( $key, '/' );
                            },
                            array_keys( $config[ApiBase::PARAM_TEMPLATE_VARS] )
                        )
                    );
                    $this->assertRegExp( '/^(?>[^{}]+|\{(?:' . $keys . ')\})+$/', $param,
                        "$param: Name may not contain '{' or '}' other than as defined by PARAM_TEMPLATE_VARS" );
                } else {
                    $this->assertRegExp( '/^[^{}]+$/', $param,
                        "$param: Name may not contain '{' or '}' without PARAM_TEMPLATE_VARS" );
                }
            }
        }
    }
 
    private function validateType( $types, $value, $param, $desc ) {
        if ( count( $types ) === 1 ) {
            // Only one type allowed
            if ( is_string( $types[0] ) ) {
                $this->assertType( $types[0], $value, "$param: $desc type" );
            } else {
                // Array whose values have specified types, recurse
                $this->assertInternalType( 'array', $value, "$param: $desc type" );
                foreach ( $value as $subvalue ) {
                    $this->validateType( $types[0], $subvalue, $param, "$desc value" );
                }
            }
        } else {
            // Multiple options
            foreach ( $types as $type ) {
                if ( is_string( $type ) ) {
                    if ( class_exists( $type ) || interface_exists( $type ) ) {
                        if ( $value instanceof $type ) {
                            return;
                        }
                    } elseif ( gettype( $value ) === $type ) {
                        return;
                    }
                } else {
                    // Array whose values have specified types, recurse
                    try {
                        $this->validateType( [ $type ], $value, $param, "$desc type" );
                        // Didn't throw, so we're good
                        return;
                    } catch ( Exception $unused ) {
                    }
                }
            }
            // Doesn't match any of them
            $this->fail( "$param: $desc has incorrect type" );
        }
    }
 
    private function validateDefault( $param, $config ) {
        $type = $config[ApiBase::PARAM_TYPE];
        $default = $config[ApiBase::PARAM_DFLT];
 
        if ( !empty( $config[ApiBase::PARAM_ISMULTI] ) ) {
            if ( $default === '' ) {
                // The empty array is fine
                return;
            }
            $defaults = explode( '|', $default );
            $config[ApiBase::PARAM_ISMULTI] = false;
            foreach ( $defaults as $defaultValue ) {
                // Only allow integers in their simplest form with no leading
                // or trailing characters etc.
                if ( $type === 'integer' && $defaultValue === (string)(int)$defaultValue ) {
                    $defaultValue = (int)$defaultValue;
                }
                $config[ApiBase::PARAM_DFLT] = $defaultValue;
                $this->validateDefault( $param, $config );
            }
            return;
        }
        switch ( $type ) {
            case 'boolean':
                $this->assertFalse( $default,
                    "$param: Boolean params may only default to false" );
                break;
 
            case 'integer':
                $this->assertInternalType( 'integer', $default,
                    "$param: Default $default is not an integer" );
                break;
 
            case 'limit':
                if ( $default === 'max' ) {
                    break;
                }
                $this->assertInternalType( 'integer', $default,
                    "$param: Default $default is neither an integer nor \"max\"" );
                break;
 
            case 'namespace':
                $validValues = MWNamespace::getValidNamespaces();
                if (
                    isset( $config[ApiBase::PARAM_EXTRA_NAMESPACES] ) &&
                    is_array( $config[ApiBase::PARAM_EXTRA_NAMESPACES] )
                ) {
                    $validValues = array_merge(
                        $validValues,
                        $config[ApiBase::PARAM_EXTRA_NAMESPACES]
                    );
                }
                $this->assertContains( $default, $validValues,
                    "$param: Default $default is not a valid namespace" );
                break;
 
            case 'NULL':
            case 'password':
            case 'string':
            case 'submodule':
            case 'tags':
            case 'text':
                $this->assertInternalType( 'string', $default,
                    "$param: Default $default is not a string" );
                break;
 
            case 'timestamp':
                if ( $default === 'now' ) {
                    return;
                }
                $this->assertNotFalse( wfTimestamp( TS_MW, $default ),
                    "$param: Default $default is not a valid timestamp" );
                break;
 
            case 'user':
                // @todo Should we make user validation a public static method
                // in ApiBase() or something so we don't have to resort to
                // this?  Or in User for that matter.
                $wrapper = TestingAccessWrapper::newFromObject( new ApiMain() );
                try {
                    $wrapper->validateUser( $default, '' );
                } catch ( ApiUsageException $e ) {
                    $this->fail( "$param: Default $default is not a valid username/IP address" );
                }
                break;
 
            default:
                if ( is_array( $type ) ) {
                    $this->assertContains( $default, $type,
                        "$param: Default $default is not any of " .
                        implode( ', ', $type ) );
                } else {
                    $this->fail( "Unrecognized type $type" );
                }
        }
    }
 
    public static function provideParameterConsistency() {
        $main = self::getMain();
        $paths = self::getSubModulePaths( $main->getModuleManager() );
        array_unshift( $paths, $main->getModulePath() );
 
        $ret = [];
        foreach ( $paths as $path ) {
            $ret[] = [ $path ];
        }
        return $ret;
    }
 
    protected static function getSubModulePaths( ApiModuleManager $manager ) {
        $paths = [];
        foreach ( $manager->getNames() as $name ) {
            $module = $manager->getModule( $name );
            $paths[] = $module->getModulePath();
            $subManager = $module->getModuleManager();
            if ( $subManager ) {
                $paths = array_merge( $paths, self::getSubModulePaths( $subManager ) );
            }
        }
        return $paths;
    }
}