EnumDef.php

Go to the documentation of this file.

<?php
 
namespace Wikimedia\ParamValidator\TypeDef;
 
use Wikimedia\Message\DataMessageValue;
use Wikimedia\Message\ListParam;
use Wikimedia\Message\ListType;
use Wikimedia\Message\MessageParam;
use Wikimedia\Message\MessageValue;
use Wikimedia\Message\ParamType;
use Wikimedia\Message\ScalarParam;
use Wikimedia\ParamValidator\ParamValidator;
use Wikimedia\ParamValidator\TypeDef;
 
class EnumDef extends TypeDef {
 
    public const PARAM_DEPRECATED_VALUES = 'param-deprecated-values';
 
    public const PARAM_INTERNAL_VALUES = 'param-internal-values';
 
    public function validate( $name, $value, array $settings, array $options ) {
        $values = $this->getEnumValues( $name, $settings, $options );
 
        if ( in_array( $value, $values, true ) ) {
            // Set a warning if a deprecated parameter value has been passed
            if ( empty( $options['is-default'] ) &&
                isset( $settings[self::PARAM_DEPRECATED_VALUES][$value] )
            ) {
                $msg = $settings[self::PARAM_DEPRECATED_VALUES][$value];
                if ( $msg instanceof MessageValue ) {
                    $message = DataMessageValue::new(
                        $msg->getKey(),
                        $msg->getParams(),
                        'deprecated-value',
                        $msg instanceof DataMessageValue ? $msg->getData() : null
                    );
                } else {
                    $message = $this->failureMessage( 'deprecated-value' );
                }
                $this->failure( $message, $name, $value, $settings, $options, false );
            }
 
            return $value;
        }
 
        $isMulti = isset( $options['values-list'] );
        $this->failure(
            $this->failureMessage( 'badvalue', [], $isMulti ? 'enummulti' : 'enumnotmulti' )
                ->textListParams( array_map(
                    static fn ( $v ) => new ScalarParam( ParamType::PLAINTEXT, $v ),
                    $values
                ) )
                ->numParams( count( $values ) ),
            $name, $value, $settings, $options
        );
    }
 
    private const DISCOURAGED_VALUE_INFO = [
        [
            'param' => self::PARAM_DEPRECATED_VALUES,
            'name' => 'PARAM_DEPRECATED_VALUES',
            'info' => 'deprecatedvalues',
            'canBeMessage' => true,
            'allowedValues' => [ null, true ],
        ],
        [
            'param' => self::PARAM_INTERNAL_VALUES,
            'name' => 'PARAM_INTERNAL_VALUES',
            'info' => 'internalvalues',
            'canBeMessage' => false,
            'allowedValues' => [ false, true ],
        ],
    ];
 
    public function checkSettings( string $name, $settings, array $options, array $ret ): array {
        $ret = parent::checkSettings( $name, $settings, $options, $ret );
 
        foreach ( self::DISCOURAGED_VALUE_INFO as $vinfo ) {
            $ret['allowedKeys'][] = $vinfo['param'];
 
            $dv = $settings[$vinfo['param']] ?? [];
            if ( !is_array( $dv ) ) {
                $ret['issues'][$vinfo['param']] = "{$vinfo['name']} must be an array, got "
                    . gettype( $dv );
            } else {
                $values = array_map( function ( $v ) use ( $name, $settings, $options ) {
                    return $this->stringifyValue( $name, $v, $settings, $options );
                }, $this->getEnumValues( $name, $settings, $options ) );
                foreach ( $dv as $k => $v ) {
                    $k = $this->stringifyValue( $name, $k, $settings, $options );
                    if ( !in_array( $k, $values, true ) ) {
                        $ret['issues'][] = "{$vinfo['name']} contains \"{$k}\", which is not "
                            . 'one of the enumerated values';
                    } elseif ( $vinfo['canBeMessage'] && $v instanceof MessageValue ) {
                        $ret['messages'][] = $v;
                    } elseif ( !in_array( $v, $vinfo['allowedValues'], true ) ) {
                        $type = get_debug_type( $v );
                        $ret['issues'][] = "Values in {$vinfo['name']} has bad type for \"{$k}\": {$type}";
                    }
                }
            }
        }
 
        return $ret;
    }
 
    public function getEnumValues( $name, array $settings, array $options ) {
        return array_values( $settings[ParamValidator::PARAM_TYPE] );
    }
 
    public function stringifyValue( $name, $value, array $settings, array $options ) {
        if ( !is_array( $value ) ) {
            return parent::stringifyValue( $name, $value, $settings, $options );
        }
 
        return ParamValidator::implodeMultiValue( $value );
    }
 
    public function getParamInfo( $name, array $settings, array $options ) {
        $info = parent::getParamInfo( $name, $settings, $options );
 
        $info['type'] = $this->sortEnumValues(
            $name,
            $this->getEnumValues( $name, $settings, $options ),
            $settings,
            $options
        );
 
        foreach ( self::DISCOURAGED_VALUE_INFO as $vinfo ) {
            if ( !empty( $settings[$vinfo['param']] ) ) {
                $badValues = array_intersect(
                    array_keys( $settings[$vinfo['param']] ),
                    $this->getEnumValues( $name, $settings, $options )
                );
                if ( $badValues ) {
                    $badValues = $this->sortEnumValues( $name, $badValues, $settings, $options );
                    $info[$vinfo['info']] = array_values( $badValues );
                }
            }
        }
 
        return $info;
    }
 
    public function getHelpInfo( $name, array $settings, array $options ) {
        $info = parent::getHelpInfo( $name, $settings, $options );
 
        $isMulti = !empty( $settings[ParamValidator::PARAM_ISMULTI] );
 
        $values = $this->getEnumValuesForHelp( $name, $settings, $options );
        $count = count( $values );
 
        $i = array_search( '', $values, true );
        if ( $i === false ) {
            $valuesParam = new ListParam( ListType::COMMA, $values );
        } else {
            unset( $values[$i] );
            $valuesParam = MessageValue::new( 'paramvalidator-help-type-enum-can-be-empty' )
                ->commaListParams( $values )
                ->numParams( count( $values ) );
        }
 
        $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-enum' )
            ->params( $isMulti ? 2 : 1 )
            ->params( $valuesParam )
            ->numParams( $count );
 
        // Suppress standard ISMULTI message, it should be incorporated into our type message.
        $info[ParamValidator::PARAM_ISMULTI] = null;
 
        return $info;
    }
 
    protected function sortEnumValues(
        string $name, array $values, array $settings, array $options
    ): array {
        // sort values by deprecation status and name
        $flags = [];
        foreach ( $values as $k => $value ) {
            $flag = 0;
            if ( isset( $settings[self::PARAM_DEPRECATED_VALUES][$value] ) ) {
                $flag |= 1;
            }
            $flags[$k] = $flag;
        }
        array_multisort( $flags, $values, SORT_NATURAL );
 
        return $values;
    }
 
    protected function getEnumValuesForHelp( $name, array $settings, array $options ) {
        $values = $this->getEnumValues( $name, $settings, $options );
        $values = $this->sortEnumValues( $name, $values, $settings, $options );
 
        // @todo Indicate deprecated values in some manner. Probably that needs
        // MessageValue and/or MessageParam to have a generic ability to wrap
        // values in HTML without that HTML coming out in the text format too.
 
        return $values;
    }
 
}