ParamValidator.php

Go to the documentation of this file.

<?php
 
namespace Wikimedia\ParamValidator;
 
use DomainException;
use InvalidArgumentException;
use Wikimedia\Assert\Assert;
use Wikimedia\Message\DataMessageValue;
use Wikimedia\Message\MessageValue;
use Wikimedia\Message\ParamType;
use Wikimedia\Message\ScalarParam;
use Wikimedia\ObjectFactory\ObjectFactory;
 
class ParamValidator {
 
    // region    Constants for parameter settings arrays
    public const PARAM_DEFAULT = 'param-default';
 
    public const PARAM_TYPE = 'param-type';
 
    public const PARAM_REQUIRED = 'param-required';
 
    public const PARAM_ISMULTI = 'param-ismulti';
 
    public const PARAM_ISMULTI_LIMIT1 = 'param-ismulti-limit1';
 
    public const PARAM_ISMULTI_LIMIT2 = 'param-ismulti-limit2';
 
    public const PARAM_ALL = 'param-all';
 
    public const PARAM_ALLOW_DUPLICATES = 'param-allow-duplicates';
 
    public const PARAM_SENSITIVE = 'param-sensitive';
 
    public const PARAM_DEPRECATED = 'param-deprecated';
 
    public const PARAM_IGNORE_UNRECOGNIZED_VALUES = 'param-ignore-unrecognized-values';
 
    // endregion -- end of Constants for parameter settings arrays
 
    public const ALL_DEFAULT_STRING = '*';
 
    public static $STANDARD_TYPES = [
        'boolean' => [ 'class' => TypeDef\BooleanDef::class ],
        'checkbox' => [ 'class' => TypeDef\PresenceBooleanDef::class ],
        'integer' => [ 'class' => TypeDef\IntegerDef::class ],
        'limit' => [ 'class' => TypeDef\LimitDef::class ],
        'float' => [ 'class' => TypeDef\FloatDef::class ],
        'double' => [ 'class' => TypeDef\FloatDef::class ],
        'string' => [ 'class' => TypeDef\StringDef::class ],
        'password' => [ 'class' => TypeDef\PasswordDef::class ],
        'NULL' => [
            'class' => TypeDef\StringDef::class,
            'args' => [ [
                'allowEmptyWhenRequired' => true,
            ] ],
        ],
        'timestamp' => [ 'class' => TypeDef\TimestampDef::class ],
        'upload' => [ 'class' => TypeDef\UploadDef::class ],
        'enum' => [ 'class' => TypeDef\EnumDef::class ],
        'expiry' => [ 'class' => TypeDef\ExpiryDef::class ],
    ];
 
    private $callbacks;
 
    private $objectFactory;
 
    private $typeDefs = [];
 
    private $ismultiLimit1;
 
    private $ismultiLimit2;
 
    public function __construct(
        Callbacks $callbacks,
        ObjectFactory $objectFactory,
        array $options = []
    ) {
        $this->callbacks = $callbacks;
        $this->objectFactory = $objectFactory;
 
        $this->addTypeDefs( $options['typeDefs'] ?? self::$STANDARD_TYPES );
        $this->ismultiLimit1 = $options['ismultiLimits'][0] ?? 50;
        $this->ismultiLimit2 = $options['ismultiLimits'][1] ?? 500;
    }
 
    public function knownTypes() {
        return array_keys( $this->typeDefs );
    }
 
    public function addTypeDefs( array $typeDefs ) {
        foreach ( $typeDefs as $name => $def ) {
            $this->addTypeDef( $name, $def );
        }
    }
 
    public function addTypeDef( $name, $typeDef ) {
        Assert::parameterType(
            [ TypeDef::class, 'array' ],
            $typeDef,
            '$typeDef'
        );
 
        if ( isset( $this->typeDefs[$name] ) ) {
            throw new InvalidArgumentException( "Type '$name' is already registered" );
        }
        $this->typeDefs[$name] = $typeDef;
    }
 
    public function overrideTypeDef( $name, $typeDef ) {
        Assert::parameterType(
            [ TypeDef::class, 'array', 'null' ],
            $typeDef,
            '$typeDef'
        );
 
        if ( $typeDef === null ) {
            unset( $this->typeDefs[$name] );
        } else {
            $this->typeDefs[$name] = $typeDef;
        }
    }
 
    public function hasTypeDef( $name ) {
        return isset( $this->typeDefs[$name] );
    }
 
    public function getTypeDef( $type ) {
        if ( is_array( $type ) ) {
            $type = 'enum';
        }
 
        if ( !isset( $this->typeDefs[$type] ) ) {
            return null;
        }
 
        $def = $this->typeDefs[$type];
        if ( !$def instanceof TypeDef ) {
            $def = $this->objectFactory->createObject( $def, [
                'extraArgs' => [ $this->callbacks ],
                'assertClass' => TypeDef::class,
            ] );
            $this->typeDefs[$type] = $def;
        }
 
        return $def;
    }
 
    private function normalizeSettingsInternal( $settings ) {
        // Shorthand
        if ( !is_array( $settings ) ) {
            $settings = [
                self::PARAM_DEFAULT => $settings,
            ];
        }
 
        // When type is not given, determine it from the type of the PARAM_DEFAULT
        if ( !isset( $settings[self::PARAM_TYPE] ) ) {
            $settings[self::PARAM_TYPE] = gettype( $settings[self::PARAM_DEFAULT] ?? null );
        }
 
        return $settings;
    }
 
    public function normalizeSettings( $settings ) {
        $settings = $this->normalizeSettingsInternal( $settings );
 
        $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] );
        if ( $typeDef ) {
            $settings = $typeDef->normalizeSettings( $settings );
        }
 
        return $settings;
    }
 
    public function checkSettings( string $name, $settings, array $options ): array {
        $settings = $this->normalizeSettingsInternal( $settings );
        $issues = [];
        $allowedKeys = [
            self::PARAM_TYPE, self::PARAM_DEFAULT, self::PARAM_REQUIRED, self::PARAM_ISMULTI,
            self::PARAM_SENSITIVE, self::PARAM_DEPRECATED, self::PARAM_IGNORE_UNRECOGNIZED_VALUES,
        ];
        $messages = [];
 
        $type = $settings[self::PARAM_TYPE];
        $typeDef = null;
        if ( !is_string( $type ) && !is_array( $type ) ) {
            $issues[self::PARAM_TYPE] = 'PARAM_TYPE must be a string or array, got ' . gettype( $type );
        } else {
            $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] );
            if ( !$typeDef ) {
                if ( is_array( $type ) ) {
                    $type = 'enum';
                }
                $issues[self::PARAM_TYPE] = "Unknown/unregistered PARAM_TYPE \"$type\"";
            }
        }
 
        if ( isset( $settings[self::PARAM_DEFAULT] ) ) {
            try {
                $this->validateValue(
                    $name, $settings[self::PARAM_DEFAULT], $settings, [ 'is-default' => true ] + $options
                );
            } catch ( ValidationException $ex ) {
                $issues[self::PARAM_DEFAULT] = 'Value for PARAM_DEFAULT does not validate (code '
                    . $ex->getFailureMessage()->getCode() . ')';
            }
        }
 
        if ( !is_bool( $settings[self::PARAM_REQUIRED] ?? false ) ) {
            $issues[self::PARAM_REQUIRED] = 'PARAM_REQUIRED must be boolean, got '
                . gettype( $settings[self::PARAM_REQUIRED] );
        }
 
        if ( !is_bool( $settings[self::PARAM_ISMULTI] ?? false ) ) {
            $issues[self::PARAM_ISMULTI] = 'PARAM_ISMULTI must be boolean, got '
                . gettype( $settings[self::PARAM_ISMULTI] );
        }
 
        if ( !empty( $settings[self::PARAM_ISMULTI] ) ) {
            $allowedKeys = array_merge( $allowedKeys, [
                self::PARAM_ISMULTI_LIMIT1, self::PARAM_ISMULTI_LIMIT2,
                self::PARAM_ALL, self::PARAM_ALLOW_DUPLICATES
            ] );
 
            $limit1 = $settings[self::PARAM_ISMULTI_LIMIT1] ?? $this->ismultiLimit1;
            $limit2 = $settings[self::PARAM_ISMULTI_LIMIT2] ?? $this->ismultiLimit2;
            if ( !is_int( $limit1 ) ) {
                $issues[self::PARAM_ISMULTI_LIMIT1] = 'PARAM_ISMULTI_LIMIT1 must be an integer, got '
                    . gettype( $settings[self::PARAM_ISMULTI_LIMIT1] );
            } elseif ( $limit1 <= 0 ) {
                $issues[self::PARAM_ISMULTI_LIMIT1] =
                    "PARAM_ISMULTI_LIMIT1 must be greater than 0, got $limit1";
            }
            if ( !is_int( $limit2 ) ) {
                $issues[self::PARAM_ISMULTI_LIMIT2] = 'PARAM_ISMULTI_LIMIT2 must be an integer, got '
                    . gettype( $settings[self::PARAM_ISMULTI_LIMIT2] );
            } elseif ( $limit2 < $limit1 ) {
                $issues[self::PARAM_ISMULTI_LIMIT2] =
                    'PARAM_ISMULTI_LIMIT2 must be greater than or equal to PARAM_ISMULTI_LIMIT1, but '
                    . "$limit2 < $limit1";
            }
 
            $all = $settings[self::PARAM_ALL] ?? false;
            if ( !is_string( $all ) && !is_bool( $all ) ) {
                $issues[self::PARAM_ALL] = 'PARAM_ALL must be a string or boolean, got ' . gettype( $all );
            } elseif ( $all !== false && $typeDef ) {
                if ( $all === true ) {
                    $all = self::ALL_DEFAULT_STRING;
                }
                $values = $typeDef->getEnumValues( $name, $settings, $options );
                if ( !is_array( $values ) ) {
                    $issues[self::PARAM_ALL] = 'PARAM_ALL cannot be used with non-enumerated types';
                } elseif ( in_array( $all, $values, true ) ) {
                    $issues[self::PARAM_ALL] = 'Value for PARAM_ALL conflicts with an enumerated value';
                }
            }
 
            if ( !is_bool( $settings[self::PARAM_ALLOW_DUPLICATES] ?? false ) ) {
                $issues[self::PARAM_ALLOW_DUPLICATES] = 'PARAM_ALLOW_DUPLICATES must be boolean, got '
                    . gettype( $settings[self::PARAM_ALLOW_DUPLICATES] );
            }
        }
 
        if ( !is_bool( $settings[self::PARAM_SENSITIVE] ?? false ) ) {
            $issues[self::PARAM_SENSITIVE] = 'PARAM_SENSITIVE must be boolean, got '
                . gettype( $settings[self::PARAM_SENSITIVE] );
        }
 
        if ( !is_bool( $settings[self::PARAM_DEPRECATED] ?? false ) ) {
            $issues[self::PARAM_DEPRECATED] = 'PARAM_DEPRECATED must be boolean, got '
                . gettype( $settings[self::PARAM_DEPRECATED] );
        }
 
        if ( !is_bool( $settings[self::PARAM_IGNORE_UNRECOGNIZED_VALUES] ?? false ) ) {
            $issues[self::PARAM_IGNORE_UNRECOGNIZED_VALUES] = 'PARAM_IGNORE_UNRECOGNIZED_VALUES must be '
                . 'boolean, got ' . gettype( $settings[self::PARAM_IGNORE_UNRECOGNIZED_VALUES] );
        }
 
        $ret = [ 'issues' => $issues, 'allowedKeys' => $allowedKeys, 'messages' => $messages ];
        if ( $typeDef ) {
            $ret = $typeDef->checkSettings( $name, $settings, $options, $ret );
        }
 
        return $ret;
    }
 
    public function getValue( $name, $settings, array $options = [] ) {
        $settings = $this->normalizeSettings( $settings );
 
        $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] );
        if ( !$typeDef ) {
            throw new DomainException(
                "Param $name's type is unknown - {$settings[self::PARAM_TYPE]}"
            );
        }
 
        $value = $typeDef->getValue( $name, $settings, $options );
 
        if ( $value !== null ) {
            if ( !empty( $settings[self::PARAM_SENSITIVE] ) ) {
                $strValue = $typeDef->stringifyValue( $name, $value, $settings, $options );
                $this->callbacks->recordCondition(
                    DataMessageValue::new( 'paramvalidator-param-sensitive', [], 'param-sensitive' )
                        ->plaintextParams( $name, $strValue ),
                    $name, $value, $settings, $options
                );
            }
 
            // Set a warning if a deprecated parameter has been passed
            if ( !empty( $settings[self::PARAM_DEPRECATED] ) ) {
                $strValue = $typeDef->stringifyValue( $name, $value, $settings, $options );
                $this->callbacks->recordCondition(
                    DataMessageValue::new( 'paramvalidator-param-deprecated', [], 'param-deprecated' )
                        ->plaintextParams( $name, $strValue ),
                    $name, $value, $settings, $options
                );
            }
        } elseif ( isset( $settings[self::PARAM_DEFAULT] ) ) {
            $value = $settings[self::PARAM_DEFAULT];
            $options['is-default'] = true;
        }
 
        return $this->validateValue( $name, $value, $settings, $options );
    }
 
    public function validateValue( $name, $value, $settings, array $options = [] ) {
        $settings = $this->normalizeSettings( $settings );
 
        $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] );
        if ( !$typeDef ) {
            throw new DomainException(
                "Param $name's type is unknown - {$settings[self::PARAM_TYPE]}"
            );
        }
 
        if ( $value === null ) {
            if ( !empty( $settings[self::PARAM_REQUIRED] ) ) {
                throw new ValidationException(
                    DataMessageValue::new( 'paramvalidator-missingparam', [], 'missingparam' )
                        ->plaintextParams( $name ),
                    $name, $value, $settings
                );
            }
            return null;
        }
 
        // Non-multi
        if ( empty( $settings[self::PARAM_ISMULTI] ) ) {
            if ( is_string( $value ) && substr( $value, 0, 1 ) === "\x1f" ) {
                throw new ValidationException(
                    DataMessageValue::new( 'paramvalidator-notmulti', [], 'badvalue' )
                        ->plaintextParams( $name, $value ),
                    $name, $value, $settings
                );
            }
 
            // T326764: If the type of the actual param value is different from
            // the type that is defined via getParamSettings(), throw an exception
            // because this is a type to value mismatch.
            if ( is_array( $value ) && !$typeDef->supportsArrays() ) {
                throw new ValidationException(
                    DataMessageValue::new( 'paramvalidator-notmulti', [], 'badvalue' )
                        ->plaintextParams( $name, gettype( $value ) ),
                    $name, $value, $settings
                );
            }
 
            return $typeDef->validate( $name, $value, $settings, $options );
        }
 
        // Split the multi-value and validate each parameter
        $limit1 = $settings[self::PARAM_ISMULTI_LIMIT1] ?? $this->ismultiLimit1;
        $limit2 = max( $limit1, $settings[self::PARAM_ISMULTI_LIMIT2] ?? $this->ismultiLimit2 );
        $valuesList = is_array( $value ) ? $value : self::explodeMultiValue( $value, $limit2 + 1 );
 
        // Handle PARAM_ALL
        $enumValues = $typeDef->getEnumValues( $name, $settings, $options );
        if ( is_array( $enumValues ) && isset( $settings[self::PARAM_ALL] ) &&
            count( $valuesList ) === 1
        ) {
            $allValue = is_string( $settings[self::PARAM_ALL] )
                ? $settings[self::PARAM_ALL]
                : self::ALL_DEFAULT_STRING;
            if ( $valuesList[0] === $allValue ) {
                return $enumValues;
            }
        }
 
        // Avoid checking useHighLimits() unless it's actually necessary
        $sizeLimit = (
            $limit2 > $limit1 && count( $valuesList ) > $limit1 &&
            $this->callbacks->useHighLimits( $options )
        ) ? $limit2 : $limit1;
        if ( count( $valuesList ) > $sizeLimit ) {
            throw new ValidationException(
                DataMessageValue::new( 'paramvalidator-toomanyvalues', [], 'toomanyvalues', [
                    'parameter' => $name,
                    'limit' => $sizeLimit,
                    'lowlimit' => $limit1,
                    'highlimit' => $limit2,
                ] )->plaintextParams( $name )->numParams( $sizeLimit ),
                $name, $valuesList, $settings
            );
        }
 
        $options['values-list'] = $valuesList;
        $validValues = [];
        $invalidValues = [];
        foreach ( $valuesList as $v ) {
            try {
                $validValues[] = $typeDef->validate( $name, $v, $settings, $options );
            } catch ( ValidationException $ex ) {
                if ( $ex->getFailureMessage()->getCode() !== 'badvalue' ||
                    empty( $settings[self::PARAM_IGNORE_UNRECOGNIZED_VALUES] )
                ) {
                    throw $ex;
                }
                $invalidValues[] = $v;
            }
        }
        if ( $invalidValues ) {
            if ( is_array( $value ) ) {
                $value = self::implodeMultiValue( $value );
            }
            $this->callbacks->recordCondition(
                DataMessageValue::new( 'paramvalidator-unrecognizedvalues', [], 'unrecognizedvalues', [
                    'values' => $invalidValues,
                ] )
                    ->plaintextParams( $name, $value )
                    ->commaListParams( array_map( static function ( $v ) {
                        return new ScalarParam( ParamType::PLAINTEXT, $v );
                    }, $invalidValues ) )
                    ->numParams( count( $invalidValues ) ),
                $name, $value, $settings, $options
            );
        }
 
        // Throw out duplicates if requested
        if ( empty( $settings[self::PARAM_ALLOW_DUPLICATES] ) ) {
            $validValues = array_values( array_unique( $validValues ) );
        }
 
        return $validValues;
    }
 
    public function getParamInfo( $name, $settings, array $options ) {
        $settings = $this->normalizeSettings( $settings );
        $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] );
        $info = [];
 
        $info['type'] = $settings[self::PARAM_TYPE];
        $info['required'] = !empty( $settings[self::PARAM_REQUIRED] );
        if ( !empty( $settings[self::PARAM_DEPRECATED] ) ) {
            $info['deprecated'] = true;
        }
        if ( !empty( $settings[self::PARAM_SENSITIVE] ) ) {
            $info['sensitive'] = true;
        }
        if ( isset( $settings[self::PARAM_DEFAULT] ) ) {
            $info['default'] = $settings[self::PARAM_DEFAULT];
        }
        $info['multi'] = !empty( $settings[self::PARAM_ISMULTI] );
        if ( $info['multi'] ) {
            $info['lowlimit'] = $settings[self::PARAM_ISMULTI_LIMIT1] ?? $this->ismultiLimit1;
            $info['highlimit'] = max(
                $info['lowlimit'], $settings[self::PARAM_ISMULTI_LIMIT2] ?? $this->ismultiLimit2
            );
            $info['limit'] =
                $info['highlimit'] > $info['lowlimit'] && $this->callbacks->useHighLimits( $options )
                    ? $info['highlimit']
                    : $info['lowlimit'];
 
            if ( !empty( $settings[self::PARAM_ALLOW_DUPLICATES] ) ) {
                $info['allowsduplicates'] = true;
            }
 
            $allSpecifier = $settings[self::PARAM_ALL] ?? false;
            if ( $allSpecifier !== false ) {
                if ( !is_string( $allSpecifier ) ) {
                    $allSpecifier = self::ALL_DEFAULT_STRING;
                }
                $info['allspecifier'] = $allSpecifier;
            }
        }
 
        if ( $typeDef ) {
            $info = array_merge( $info, $typeDef->getParamInfo( $name, $settings, $options ) );
        }
 
        // Filter out nulls (strictly)
        return array_filter( $info, static function ( $v ) {
            return $v !== null;
        } );
    }
 
    public function getHelpInfo( $name, $settings, array $options ) {
        $settings = $this->normalizeSettings( $settings );
        $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] );
 
        // Define ordering. Some are overwritten below, some expected from the TypeDef
        $info = [
            self::PARAM_DEPRECATED => null,
            self::PARAM_REQUIRED => null,
            self::PARAM_SENSITIVE => null,
            self::PARAM_TYPE => null,
            self::PARAM_ISMULTI => null,
            self::PARAM_ISMULTI_LIMIT1 => null,
            self::PARAM_ALL => null,
            self::PARAM_DEFAULT => null,
        ];
 
        if ( !empty( $settings[self::PARAM_DEPRECATED] ) ) {
            $info[self::PARAM_DEPRECATED] = MessageValue::new( 'paramvalidator-help-deprecated' );
        }
 
        if ( !empty( $settings[self::PARAM_REQUIRED] ) ) {
            $info[self::PARAM_REQUIRED] = MessageValue::new( 'paramvalidator-help-required' );
        }
 
        if ( !empty( $settings[self::PARAM_ISMULTI] ) ) {
            $info[self::PARAM_ISMULTI] = MessageValue::new( 'paramvalidator-help-multi-separate' );
 
            $lowcount = $settings[self::PARAM_ISMULTI_LIMIT1] ?? $this->ismultiLimit1;
            $highcount = max( $lowcount, $settings[self::PARAM_ISMULTI_LIMIT2] ?? $this->ismultiLimit2 );
            $values = $typeDef ? $typeDef->getEnumValues( $name, $settings, $options ) : null;
            if (
                // Only mention the limits if they're likely to matter.
                $values === null || count( $values ) > $lowcount ||
                !empty( $settings[self::PARAM_ALLOW_DUPLICATES] )
            ) {
                if ( $highcount > $lowcount ) {
                    $info[self::PARAM_ISMULTI_LIMIT1] = MessageValue::new( 'paramvalidator-help-multi-max' )
                        ->numParams( $lowcount, $highcount );
                } else {
                    $info[self::PARAM_ISMULTI_LIMIT1] = MessageValue::new( 'paramvalidator-help-multi-max-simple' )
                        ->numParams( $lowcount );
                }
            }
 
            $allSpecifier = $settings[self::PARAM_ALL] ?? false;
            if ( $allSpecifier !== false ) {
                if ( !is_string( $allSpecifier ) ) {
                    $allSpecifier = self::ALL_DEFAULT_STRING;
                }
                $info[self::PARAM_ALL] = MessageValue::new( 'paramvalidator-help-multi-all' )
                    ->plaintextParams( $allSpecifier );
            }
        }
 
        if ( isset( $settings[self::PARAM_DEFAULT] ) && $typeDef ) {
            $value = $typeDef->stringifyValue( $name, $settings[self::PARAM_DEFAULT], $settings, $options );
            if ( $value === '' ) {
                $info[self::PARAM_DEFAULT] = MessageValue::new( 'paramvalidator-help-default-empty' );
            } elseif ( $value !== null ) {
                $info[self::PARAM_DEFAULT] = MessageValue::new( 'paramvalidator-help-default' )
                    ->plaintextParams( $value );
            }
        }
 
        if ( $typeDef ) {
            $info = array_merge( $info, $typeDef->getHelpInfo( $name, $settings, $options ) );
        }
 
        // Put the default at the very end (the TypeDef may have added extra messages)
        $default = $info[self::PARAM_DEFAULT];
        unset( $info[self::PARAM_DEFAULT] );
        $info[self::PARAM_DEFAULT] = $default;
 
        // Filter out nulls
        return array_filter( $info );
    }
 
    public static function explodeMultiValue( $value, $limit ) {
        if ( $value === '' || $value === "\x1f" ) {
            return [];
        }
 
        if ( substr( $value, 0, 1 ) === "\x1f" ) {
            $sep = "\x1f";
            $value = substr( $value, 1 );
        } else {
            $sep = '|';
        }
 
        return explode( $sep, $value, $limit );
    }
 
    public static function implodeMultiValue( array $value ) {
        if ( $value === [ '' ] ) {
            // There's no value that actually returns a single empty string.
            // Best we can do is this that returns two, which will be deduplicated to one.
            return '|';
        }
 
        foreach ( $value as $v ) {
            if ( strpos( $v, '|' ) !== false ) {
                return "\x1f" . implode( "\x1f", $value );
            }
        }
        return implode( '|', $value );
    }
 
}