includes/Settings/Source/JsonSchemaTrait.php
<?php
namespace MediaWiki\Settings\Source;
use InvalidArgumentException;
/**
* Trait for dealing with JSON Schema structures and types.
*
* @since 1.39
*/
trait JsonSchemaTrait {
/**
* Converts a JSON Schema type to a PHPDoc type.
*
* @param string|string[] $jsonSchemaType A JSON Schema type
*
* @return string A PHPDoc type
*/
private static function jsonToPhpDoc( $jsonSchemaType ) {
static $phpTypes = [
'array' => 'array',
'object' => 'array', // could be optional
'number' => 'float',
'double' => 'float', // for good measure
'boolean' => 'bool',
'integer' => 'int',
];
if ( $jsonSchemaType === null ) {
throw new InvalidArgumentException( 'The type name cannot be null! Use "null" instead.' );
}
$nullable = false;
if ( is_array( $jsonSchemaType ) ) {
$nullIndex = array_search( 'null', $jsonSchemaType );
if ( $nullIndex !== false ) {
$nullable = true;
unset( $jsonSchemaType[$nullIndex] );
}
$jsonSchemaType = array_map( [ self::class, 'jsonToPhpDoc' ], $jsonSchemaType );
$type = implode( '|', $jsonSchemaType );
} else {
$type = $phpTypes[ strtolower( $jsonSchemaType ) ] ?? $jsonSchemaType;
}
if ( $nullable ) {
$type = "?$type";
}
return $type;
}
/**
* @param string|string[] $phpDocType The PHPDoc type
*
* @return string|string[] A JSON Schema type
*/
private static function phpDocToJson( $phpDocType ) {
static $jsonTypes = [
'list' => 'array',
'dict' => 'object',
'map' => 'object',
'stdclass' => 'object',
'int' => 'integer',
'float' => 'number',
'bool' => 'boolean',
'false' => 'boolean',
];
if ( $phpDocType === null ) {
throw new InvalidArgumentException( 'The type name cannot be null! Use "null" instead.' );
}
if ( is_array( $phpDocType ) ) {
$types = $phpDocType;
} else {
$types = explode( '|', trim( $phpDocType ) );
}
$nullable = false;
foreach ( $types as $i => $t ) {
if ( str_starts_with( $t, '?' ) ) {
$nullable = true;
$t = substr( $t, 1 );
}
$types[$i] = $jsonTypes[ strtolower( $t ) ] ?? $t;
}
if ( $nullable ) {
$types[] = 'null';
}
$types = array_unique( $types );
if ( count( $types ) === 1 ) {
return reset( $types );
}
return $types;
}
/**
* Applies phpDocToJson() to type declarations in a JSON schema.
*
* @param array $schema JSON Schema structure with PHPDoc types
* @param array &$defs List of definitions (JSON schemas) referenced in the schema
* @param string $source An identifier for the source schema being reflected, used
* for error descriptions.
* @param string $propertyName The name of the property the schema belongs to, used for error descriptions.
* @return array JSON Schema structure using only proper JSON types
*/
private static function normalizeJsonSchema(
array $schema,
array &$defs,
string $source,
string $propertyName,
bool $inlineReferences = false
): array {
$traversedReferences = [];
return self::doNormalizeJsonSchema(
$schema, $defs, $source, $propertyName, $inlineReferences, $traversedReferences
);
}
/**
* Recursively applies phpDocToJson() to type declarations in a JSON schema.
*
* @param array $schema JSON Schema structure with PHPDoc types
* @param array &$defs List of definitions (JSON schemas) referenced in the schema
* @param string $source An identifier for the source schema being reflected, used
* for error descriptions.
* @param string $propertyName The name of the property the schema belongs to, used for error descriptions.
* @param bool $inlineReferences Whether references in the schema should be inlined or not.
* @param array $traversedReferences An accumulator for the resolved references within a schema normalization,
* used for cycle detection.
* @return array JSON Schema structure using only proper JSON types
*/
private static function doNormalizeJsonSchema(
array $schema,
array &$defs,
string $source,
string $propertyName,
bool $inlineReferences,
array $traversedReferences
): array {
if ( isset( $schema['type'] ) ) {
// Support PHP Doc style types, for convenience.
$schema['type'] = self::phpDocToJson( $schema['type'] );
}
if ( isset( $schema['additionalProperties'] ) && is_array( $schema['additionalProperties'] ) ) {
$schema['additionalProperties'] =
self::doNormalizeJsonSchema(
$schema['additionalProperties'],
$defs,
$source,
$propertyName,
$inlineReferences,
$traversedReferences
);
}
if ( isset( $schema['items'] ) && is_array( $schema['items'] ) ) {
$schema['items'] = self::doNormalizeJsonSchema(
$schema['items'],
$defs,
$source,
$propertyName,
$inlineReferences,
$traversedReferences
);
}
if ( isset( $schema['properties'] ) && is_array( $schema['properties'] ) ) {
foreach ( $schema['properties'] as $name => $propSchema ) {
$schema['properties'][$name] = self::doNormalizeJsonSchema(
$propSchema,
$defs,
$source,
$propertyName,
$inlineReferences,
$traversedReferences
);
}
}
if ( isset( $schema['$ref'] ) ) {
$definitionName = JsonSchemaReferenceResolver::getDefinitionName( $schema[ '$ref' ] );
if ( array_key_exists( $definitionName, $traversedReferences ) ) {
throw new RefLoopException(
"Found a loop while resolving reference $definitionName in $propertyName." .
" Root schema location: $source"
);
}
$def = JsonSchemaReferenceResolver::resolveRef( $schema['$ref'], $source );
if ( $def ) {
if ( !isset( $defs[$definitionName] ) ) {
$traversedReferences[$definitionName] = true;
$normalizedDefinition = self::doNormalizeJsonSchema(
$def,
$defs,
$source,
$propertyName,
$inlineReferences,
$traversedReferences
);
if ( !$inlineReferences ) {
$defs[$definitionName] = $normalizedDefinition;
}
} else {
$normalizedDefinition = $defs[$definitionName];
}
// Normalize reference after resolving it since JsonSchemaReferenceResolver expects
// the $ref to be an array with: [ "class" => "Some\\Class", "field" => "someField" ]
if ( $inlineReferences ) {
$schema = $normalizedDefinition;
} else {
$schema['$ref'] = JsonSchemaReferenceResolver::normalizeRef( $schema['$ref'] );
}
}
}
return $schema;
}
/**
* Returns the default value from the given schema structure.
* If the schema defines properties, the default value of each
* property is determined recursively, and the collected into a
* the top level default, which in that case will be a map
* (that is, a JSON object).
*
* @param array $schema
* @return mixed The default specified by $schema, or null if no default
* is defined.
*/
private static function getDefaultFromJsonSchema( array $schema ) {
$default = $schema['default'] ?? null;
foreach ( $schema['properties'] ?? [] as $name => $sch ) {
$def = self::getDefaultFromJsonSchema( $sch );
$default[$name] = $def;
}
return $default;
}
}