README

PHP结构化数据验证。

需求

该项目不稳定，版本之间可能会有变化。

您需要 PHP >= 7.0 来使用这个库，然而，建议使用PHP的最新稳定版本。

安装

使用Composer安装sndsgd/form。

composer require sndsgd/form

用法

定义表单

<?php

use \sndsgd\form\field;
use \sndsgd\form\rule;

require __DIR__."/../vendor/autoload.php";

$form = (new \sndsgd\Form())
    ->addFields(
        (new field\StringField("name"))
            ->setDescription(_("The user's name"))
            ->addRules(
                new rule\RequiredRule()
            ),
        (new field\StringField("email"))
            ->setDescription(_("The user's email address"))
            ->addRules(
                new rule\RequiredRule(),
                new rule\EmailRule()
            )
    );

验证输入

$inputValues = [
    "name" => "",
    "email" => "asd@asd.com",
    "whoami" => "'whoami' should be unexpected",
];

$validator = new \sndsgd\form\Validator($form);
try {
    $values = $validator->validate($inputValues);
    $message = "all values were valid";
} catch (\sndsgd\form\ValidationException $ex) {
    $message = "validation errors encountered";
    $errors = $ex->getErrors();
}

echo json_encode([
    "message" => $message,
    "data" => $data ?? null,
    "errors" => $errors ?? [],
], \sndsgd\Json::HUMAN);

{
    "message": "validation errors encountered",
    "data": null,
    "errors": [
        {
            "message": "required",
            "code": 0,
            "field": "name"
        },
        {
            "message": "unknown field",
            "code": 0,
            "field": "whoami"
        }
    ]
}

获取文档详细信息

$detail = $form->getDetail();
echo json_encode($detail, \sndsgd\Json::HUMAN);

[
    {
        "name": "name",
        "type": "string",
        "signature": "string",
        "description": "your name",
        "default": null,
        "rules": {
            "values": [
                {
                    "description": "required",
                    "errorMessage": "required"
                },
                {
                    "description": "email",
                    "errorMessage": "must be a valid email address"
                }
            ]
        }
    },
    {
        "name": "email",
        "type": "string",
        "signature": "string",
        "description": "your email address",
        "default": null,
        "rules": {
            "values": [
                {
                    "description": "required",
                    "errorMessage": "required"
                },
                {
                    "description": "email",
                    "errorMessage": "must be a valid email address"
                }
            ]
        }
    }
]

字段类型

单值字段

`\sndsgd\form\field\ValueField`

此字段类型可用于存储各种类型的一个值。在大多数情况下，它将是您要创建的任何自定义字段的基类。

$ageField = (new field\ValueField("age"))
    ->setDescription(_("The user's age in years"))
    ->addRules(
        new rule\IntegerRule(),
        new rule\MinRule(0),
        new rule\MaxRule(150)
    );

我们已经为常用类型创建了几种ValueField的子类。请注意，每次您使用这些字段之一时，您都可以跳过添加相应的类型规则。

\sndsgd\form\field\BooleanField
\sndsgd\form\field\FloatField
\sndsgd\form\field\IntegerField
\sndsgd\form\field\StringField

多值字段

每次您需要一个具有多个值的字段时，您需要定义一个字段，该字段将包含一个或多个用于每个值的字段。这允许对每个不同的值进行单独验证，然后对所有值进行相互验证。

`\sndsgd\form\field\ArrayField`

在需要同一类型多个值时使用ArrayField。

# this field defines what is expected for each value in the array
$nicknamesValue = (new field\StringField())
    ->addRules(
        new rule\MaxLengthRule(64),
        (new rule\RegexRule("/^[a-z0-9 ]+$/i"))
            ->setErrorMessage(_("must contain only letters, numbers, or spaces"))
    );

# create an array field as the parent of the value field
# note: the rules are for validating all values as a group; if you need to
# validate each value, add the relevant rules to the value field
$nicknamesField = (new field\ArrayField("nicknames", $nicknamesValue))
    ->setDescription(_("The user's nicknames"))
    ->addRules(
        new rule\MaxValueCountRule(5)
    );

`\sndsgd\form\field\MapField`

在需要验证对象键和值时使用MapField。

# define what is expected for a key in the map
$phoneKey = (new field\StringField())
    ->setDescription(_("A label for a phone number"))
    ->addRule(new rule\AlphaNumRule());

# define what is expected for a value in the map
$phoneValue = (new field\StringField())
    ->setDescription(_("A phone number"))
    ->addRule(new rule\MinLengthRule(10));

# create a map field using the key and value fields
# as with the array field, any rules added to a map field are used for
# validating all the values as a group
$phonesField = (new field\MapField("phoneNumbers", $phoneKey, $phoneValue))
    ->setDescription(_("The user's phone numbers"))
    ->addRule(new rule\MaxValueCountRule(5));

`\sndsgd\form\field\ObjectField`

在您需要仅验证对象值时使用ObjectField。它将任何添加到其中的字段的名称用作键。

$field = (new field\ObjectField())
    ->addFields(
        $ageField,
        $nicknamesField,
        $phonesField
    );

文档

$detail = $field->getDetail();
echo json_encode($detail, \sndsgd\Json::HUMAN);

[
    {
        "name": "age",
        "type": "int",
        "signature": "int",
        "description": "The user's age in years",
        "default": null,
        "rules": {
            "values": [
                {
                    "description": "type:integer",
                    "errorMessage": "must be an integer"
                },
                {
                    "description": "min:0",
                    "errorMessage": "must be at least 0"
                },
                {
                    "description": "max:150",
                    "errorMessage": "must be no greater than 150"
                }
            ]
        }
    },
    {
        "name": "nicknames",
        "type": "array",
        "signature": "array<string>",
        "description": "The user's nicknames",
        "default": [],
        "rules": {
            "values": [
                {
                    "description": "max-length:64",
                    "errorMessage": "must be no more than 64 characters"
                },
                {
                    "description": "regex:/^[a-z0-9 ]+$/i",
                    "errorMessage": "must contain only letters, numbers, or spaces"
                },
                {
                    "description": "max-values:5",
                    "errorMessage": "must be no more than 5 values"
                }
            ]
        }
    },
    {
        "name": "phoneNumbers",
        "type": "map",
        "signature": "map<string,string>",
        "description": "The user's phone numbers",
        "default": null,
        "rules": {
            "keys": [
                {
                    "description": "alphanumeric",
                    "errorMessage": "must contain only alphanumeric characters"
                }
            ],
            "values": [
                {
                    "description": "min-length:10",
                    "errorMessage": "must be at least 10 characters"
                },
                {
                    "description": "max-values:5",
                    "errorMessage": "must be no more than 5 values"
                }
            ]
        }
    }
]

sndsgd / form

维护者

详细信息