JSON Schema for PHP 技术文档

安装指南

通过 Git 克隆

git clone https://github.com/jsonrainbow/json-schema.git

通过 Composer 安装

首先，确保你已经安装了 PHP Composer。如果尚未安装，可以参考 Composer 官方文档 进行安装。

然后，使用以下命令安装 json-schema 包：

composer require justinrainbow/json-schema

项目使用说明

基本使用

以下是一个基本的 JSON 验证示例：

<?php

$data = json_decode(file_get_contents('data.json'));

// 验证
$validator = new JsonSchema\Validator;
$validator->validate($data, (object)['$ref' => 'file://' . realpath('schema.json')]);

if ($validator->isValid()) {
    echo "The supplied JSON validates against the schema.\n";
} else {
    echo "JSON does not validate. Violations:\n";
    foreach ($validator->getErrors() as $error) {
        printf("[%s] %s\n", $error['property'], $error['message']);
    }
}

类型强制转换

如果你需要验证通过 HTTP 传递的数据，并且希望将字符串和布尔值转换为预期的类型，可以使用以下代码：

<?php

use JsonSchema\SchemaStorage;
use JsonSchema\Validator;
use JsonSchema\Constraints\Factory;
use JsonSchema\Constraints\Constraint;

$request = (object)[
    'processRefund'=>"true",
    'refundAmount'=>"17"
];

$validator->validate(
    $request, (object) [
        "type"=>"object",
        "properties"=>(object)[
            "processRefund"=>(object)[
                "type"=>"boolean"
            ],
            "refundAmount"=>(object)[
                "type"=>"number"
            ]
        ]
    ],
    Constraint::CHECK_MODE_COERCE_TYPES
); // 验证通过！

is_bool($request->processRefund); // true
is_int($request->refundAmount); // true

默认值

如果你的 schema 包含默认值，可以在验证过程中自动应用这些默认值：

<?php

use JsonSchema\Validator;
use JsonSchema\Constraints\Constraint;

$request = (object)[
    'refundAmount'=>17
];

$validator = new Validator();

$validator->validate(
    $request,
    (object)[
        "type"=>"object",
        "properties"=>(object)[
            "processRefund"=>(object)[
                "type"=>"boolean",
                "default"=>true
            ]
        ]
    ],
    Constraint::CHECK_MODE_APPLY_DEFAULTS
); // 验证通过，并为缺失的属性设置默认值

is_bool($request->processRefund); // true
$request->processRefund; // true

内联引用

<?php

use JsonSchema\SchemaStorage;
use JsonSchema\Validator;
use JsonSchema\Constraints\Factory;

$jsonSchema = <<<'JSON'
{
    "type": "object",
    "properties": {
        "data": {
            "oneOf": [
                { "$ref": "#/definitions/integerData" },
                { "$ref": "#/definitions/stringData" }
            ]
        }
    },
    "required": ["data"],
    "definitions": {
        "integerData" : {
            "type": "integer",
            "minimum" : 0
        },
        "stringData" : {
            "type": "string"
        }
    }
}
JSON;

// Schema 必须先解码才能用于验证
$jsonSchemaObject = json_decode($jsonSchema);

// SchemaStorage 可以解析引用，根据需要从文件加载其他 schema 等
$schemaStorage = new SchemaStorage();

// 这做了两件事：
// 1) 修改 $jsonSchemaObject 以规范化引用（例如 file://mySchema#/definitions/integerData 等）
// 2) 告诉 $schemaStorage 引用 file://mySchema... 应通过查看 $jsonSchemaObject 来解析
$schemaStorage->addSchema('file://mySchema', $jsonSchemaObject);

// 将 $schemaStorage 提供给 Validator，以便在验证期间解析引用
$jsonValidator = new Validator(new Factory($schemaStorage));

// JSON 必须先解码才能验证
$jsonToValidateObject = json_decode('{"data":123}');

// 进行验证（使用 isValid() 和 getErrors() 检查结果）
$jsonValidator->validate($jsonToValidateObject, $jsonSchemaObject);

项目 API 使用文档

验证器配置选项

验证器提供了多个标志来改变其行为。这些标志可以作为 Validator::validate() 的第三个参数传递，或者作为 Factory::__construct() 的第三个参数传递，以便在多个 validate() 调用中保持一致。

标志	描述
Constraint::CHECK_MODE_NORMAL	以 'normal' 模式验证 - 这是默认模式
Constraint::CHECK_MODE_TYPE_CAST	为关联数组和对象启用模糊类型检查
Constraint::CHECK_MODE_COERCE_TYPES	在可能的情况下将数据类型转换为与 schema 匹配的类型
Constraint::CHECK_MODE_EARLY_COERCE	尽早应用类型强制转换
Constraint::CHECK_MODE_APPLY_DEFAULTS	如果未设置，则从 schema 应用默认值
Constraint::CHECK_MODE_ONLY_REQUIRED_DEFAULTS	应用默认值时，仅设置必需的值
Constraint::CHECK_MODE_EXCEPTIONS	如果验证失败，立即抛出异常
Constraint::CHECK_MODE_DISABLE_FORMAT	不验证 "format" 约束
Constraint::CHECK_MODE_VALIDATE_SCHEMA	验证 schema 以及提供的文档

请注意，使用 CHECK_MODE_COERCE_TYPES 或 CHECK_MODE_APPLY_DEFAULTS 将修改原始数据。

CHECK_MODE_EARLY_COERCE 除非与 CHECK_MODE_COERCE_TYPES 一起使用，否则无效。如果启用，验证器将使用（并强制转换）它遇到的第一个兼容类型，即使 schema 定义了另一个直接匹配且不需要强制转换的类型。

项目安装方式

通过 Git 克隆

git clone https://github.com/jsonrainbow/json-schema.git

通过 Composer 安装

composer require justinrainbow/json-schema

运行测试

composer test                            # 运行所有单元测试
composer testOnly TestClass              # 运行特定的单元测试类
composer testOnly TestClass::testMethod  # 运行特定的单元测试方法
composer style-check                     # 检查代码风格错误
composer style-fix                       # 自动修复代码风格错误