ParamValidator.php

Go to the documentation of this file.

<?php
 
namespace Wikimedia\ParamValidator;
 
use DomainException;
use InvalidArgumentException;
use Wikimedia\Assert\Assert;
use Wikimedia\ObjectFactory;
 
class ParamValidator {
 
    const PARAM_DEFAULT = 'param-default';
 
    const PARAM_TYPE = 'param-type';
 
    const PARAM_REQUIRED = 'param-required';
 
    const PARAM_ISMULTI = 'param-ismulti';
 
    const PARAM_ISMULTI_LIMIT1 = 'param-ismulti-limit1';
 
    const PARAM_ISMULTI_LIMIT2 = 'param-ismulti-limit2';
 
    const PARAM_ALL = 'param-all';
 
    const PARAM_ALLOW_DUPLICATES = 'param-allow-duplicates';
 
    const PARAM_SENSITIVE = 'param-sensitive';
 
    const PARAM_DEPRECATED = 'param-deprecated';
 
    const PARAM_IGNORE_INVALID_VALUES = 'param-ignore-invalid-values';
 
    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 ],
    ];
 
    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(
            implode( '|', [ 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(
            implode( '|', [ 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;
    }
 
    public function normalizeSettings( $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 );
        }
 
        $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] );
        if ( $typeDef ) {
            $settings = $typeDef->normalizeSettings( $settings );
        }
 
        return $settings;
    }
 
    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] ) ) {
                $this->callbacks->recordCondition(
                    new ValidationException( $name, $value, $settings, 'param-sensitive', [] ),
                    $options
                );
            }
 
            // Set a warning if a deprecated parameter has been passed
            if ( !empty( $settings[self::PARAM_DEPRECATED] ) ) {
                $this->callbacks->recordCondition(
                    new ValidationException( $name, $value, $settings, 'param-deprecated', [] ),
                    $options
                );
            }
        } elseif ( isset( $settings[self::PARAM_DEFAULT] ) ) {
            $value = $settings[self::PARAM_DEFAULT];
        }
 
        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( $name, $value, $settings, 'missingparam', [] );
            }
            return null;
        }
 
        // Non-multi
        if ( empty( $settings[self::PARAM_ISMULTI] ) ) {
            return $typeDef->validate( $name, $value, $settings, $options );
        }
 
        // Split the multi-value and validate each parameter
        $limit1 = $settings[self::PARAM_ISMULTI_LIMIT1] ?? $this->ismultiLimit1;
        $limit2 = $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 = count( $valuesList ) > $limit1 && $this->callbacks->useHighLimits( $options )
            ? $limit2
            : $limit1;
        if ( count( $valuesList ) > $sizeLimit ) {
            throw new ValidationException( $name, $valuesList, $settings, 'toomanyvalues', [
                'limit' => $sizeLimit
            ] );
        }
 
        $options['values-list'] = $valuesList;
        $validValues = [];
        $invalidValues = [];
        foreach ( $valuesList as $v ) {
            try {
                $validValues[] = $typeDef->validate( $name, $v, $settings, $options );
            } catch ( ValidationException $ex ) {
                if ( empty( $settings[self::PARAM_IGNORE_INVALID_VALUES] ) ) {
                    throw $ex;
                }
                $invalidValues[] = $v;
            }
        }
        if ( $invalidValues ) {
            $this->callbacks->recordCondition(
                new ValidationException( $name, $value, $settings, 'unrecognizedvalues', [
                    'values' => $invalidValues,
                ] ),
                $options
            );
        }
 
        // Throw out duplicates if requested
        if ( empty( $settings[self::PARAM_ALLOW_DUPLICATES] ) ) {
            $validValues = array_values( array_unique( $validValues ) );
        }
 
        return $validValues;
    }
 
    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 );
    }
 
}