145 lines
4.6 KiB
PHP
145 lines
4.6 KiB
PHP
<?php
|
|
|
|
namespace Automattic\Jetpack\Schema;
|
|
|
|
use Automattic\Jetpack\Schema\Modifiers\Modifier_Fallback;
|
|
use Automattic\Jetpack\Schema\Types\Type_Any;
|
|
use Automattic\Jetpack\Schema\Types\Type_Any_JSON;
|
|
use Automattic\Jetpack\Schema\Types\Type_Array;
|
|
use Automattic\Jetpack\Schema\Types\Type_Assoc_Array;
|
|
use Automattic\Jetpack\Schema\Types\Type_Boolean;
|
|
use Automattic\Jetpack\Schema\Types\Type_Enum;
|
|
use Automattic\Jetpack\Schema\Types\Type_Float;
|
|
use Automattic\Jetpack\Schema\Types\Type_Number;
|
|
use Automattic\Jetpack\Schema\Types\Type_String;
|
|
use Automattic\Jetpack\Schema\Types\Type_Void;
|
|
|
|
/**
|
|
* The Schema class is a factory for creating and managing validation rules based on specific
|
|
* schema types. It is a central point for defining the structure of your data
|
|
* and ensuring that it conforms to the expected format.
|
|
*
|
|
* The class provides static methods for creating Schema instances with different data types,
|
|
* making it easy to build complex validation rules with a clean and readable syntax.
|
|
*
|
|
* The purpose of the Schema class is to provide a consistent way to parse structured data.
|
|
*
|
|
* Use this to ensure that your data adheres to the defined schema and avoid issues
|
|
* caused by incorrect data types or missing properties.
|
|
*
|
|
* How to use the Schema class:
|
|
*
|
|
* 1. Define your schema structure using the static methods provided by the Schema
|
|
* class, such as `as_string()`, `as_array()`, `as_boolean()`, `as_number()`,
|
|
* `as_float()`, and `enum()`. These methods return Schema instances
|
|
* for the respective data types.
|
|
*
|
|
* 2. Optionally, you can chain additional methods on the Schema instances
|
|
* to further customize the validation behavior. For example, you can use
|
|
* `fallback()` to specify a default value when the input data is invalid or
|
|
* `nullable()` to allow null values.
|
|
*
|
|
* 3. Parse your data using the Schema instances. Call the `parse()` method on the
|
|
* Schema instance, passing in the input data to be parsed.
|
|
* The method will return the parsed data or a default
|
|
* value (if specified) when the input data is invalid.
|
|
*
|
|
* Example:
|
|
*
|
|
* $my_schema = Schema::as_array(
|
|
* [
|
|
* 'name' => Schema::as_string(),
|
|
* 'age' => Schema::as_number()->fallback(0),
|
|
* 'is_active' => Schema::as_boolean()->nullable(),
|
|
* 'tags' => Schema::as_array(Schema::as_string())
|
|
* ]
|
|
* );
|
|
*
|
|
* $input_data = [
|
|
* 'name' => 'John Doe',
|
|
* 'age' => 30,
|
|
* 'is_active' => null,
|
|
* 'tags' => ['tag1', 'tag2']
|
|
* ];
|
|
*
|
|
* $parsed_data = $my_schema->parse($input_data);
|
|
*/
|
|
class Schema {
|
|
const PACKAGE_VERSION = '0.2.0';
|
|
|
|
public static function as_string() {
|
|
return new Schema_Parser( new Type_String() );
|
|
}
|
|
|
|
/**
|
|
* @param Parser $parser - The parser to apply to each array item when $data is parsed.
|
|
*
|
|
* @return Schema_Parser
|
|
*/
|
|
public static function as_array( Parser $parser ) {
|
|
return new Schema_Parser( new Type_Array( $parser ) );
|
|
}
|
|
|
|
/**
|
|
* @param array $assoc_parser_array - An associative array of ["key" => "Parser"] pairs
|
|
*
|
|
* @return Schema_Parser
|
|
*/
|
|
public static function as_assoc_array( $assoc_parser_array ) {
|
|
return new Schema_Parser( new Type_Assoc_Array( $assoc_parser_array ) );
|
|
}
|
|
|
|
public static function as_boolean() {
|
|
return new Schema_Parser( new Type_Boolean() );
|
|
}
|
|
|
|
public static function as_number() {
|
|
return new Schema_Parser( new Type_Number() );
|
|
}
|
|
|
|
public static function as_float() {
|
|
return new Schema_Parser( new Type_Float( true ) );
|
|
}
|
|
|
|
/**
|
|
* @param array $allowed_values - An array of values that are allowed for this enum.
|
|
*
|
|
* @return Schema_Parser
|
|
*/
|
|
public static function enum( $allowed_values ) {
|
|
return new Schema_Parser( new Type_Enum( $allowed_values ) );
|
|
}
|
|
|
|
public static function any_json_data() {
|
|
return new Schema_Parser( new Type_Any_JSON() );
|
|
}
|
|
|
|
/**
|
|
* Mark a schema as void - it should have no data worth keeping, and
|
|
* will always parse to null.
|
|
*/
|
|
public static function as_void() {
|
|
return new Schema_Parser( new Type_Void() );
|
|
}
|
|
|
|
/**
|
|
* Use With Caution! This will not parse the data - it will simply return it as-is.
|
|
* This is useful for delivering read-only data that we don't need to parse server-side.
|
|
*
|
|
* @see Type_Any
|
|
*/
|
|
public static function as_unsafe_any() {
|
|
return new Schema_Parser( new Type_Any() );
|
|
}
|
|
|
|
/**
|
|
* @var \Automattic\Jetpack\Schema\Parser $parser - The parser to apply to each array item when $data is parsed.
|
|
*/
|
|
public static function either( ...$parsers ) {
|
|
$or = new Modifier_Fallback();
|
|
foreach ( $parsers as $parser ) {
|
|
$or->add_fallback_parser( $parser );
|
|
}
|
|
return new Schema_Parser( $or );
|
|
}
|
|
}
|