README

Unified, testable, and extensible validation for any PHP project

A lightweight, framework-agnostic validation contract package that provides generic validator and validation result interfaces. It is designed to help developers build consistent, testable, and easily extensible validation logic, suitable for scenarios such as upload validation, form validation, and custom rule implementation.

✨ 特性

轻量级与无依赖：独立于任何框架或外部库，易于集成到现有项目中
基于抽象类的验证器：提供 AbstractValidator，子类只需实现 validate() 方法
构造注入对象：验证器接收目标对象，避免类型不确定问题
保留 ValidationResult 和 ValidationResultInterface，提供统一的验证结果封装
灵活集成与扩展：适合各种业务对象和自定义规则实现

📦 安装

composer require hizpark/validation-interface

📂 目录结构

src
├── Result
│   └── ValidationResult.php
├── Validator
│   └── AbstractValidator.php
├── ValidationResultInterface.php
└── ValidatorInterface.php

🚀 用法示例

示例 1：自定义 Email 验证器

use Hizpark\ValidationInterface\Result\ValidationResult;
use Hizpark\ValidationInterface\Validator\AbstractValidator;

class EmailValidator extends AbstractValidator
{
    public function validate(): ValidationResult
    {
        if (!is_string($this->target) || !filter_var($this->target, FILTER_VALIDATE_EMAIL)) {
            return $this->fail('Invalid email address', 'INVALID_EMAIL');
        }

        return $this->ok();
    }
}

示例 2：执行验证并处理结果

$email = 'user@example.com';
$validator = new EmailValidator($email);  // 目标对象通过构造传入
$result = $validator->validate();

if ($result->isValid()) {
    echo "Email is valid.";
} else {
    echo "Validation failed: " . $result->getError();
}

📐 接口与抽象类说明

AbstractValidator

验证器基类，每个子类接收目标对象并实现 validate() 方法返回 ValidationResult

namespace Hizpark\ValidationInterface\Validator;

use Hizpark\ValidationInterface\Result\ValidationResult;
use Hizpark\ValidationInterface\ValidatorInterface;

abstract class AbstractValidator implements ValidatorInterface
{
    protected object $target;

    public function __construct(object $target)
    {
        $this->target = $target;
    }

    abstract public function validate(): ValidationResult;

    protected function ok(): ValidationResult
    {
        return ValidationResult::ok();
    }

    protected function fail(string $error, ?string $code = null): ValidationResult
    {
        return ValidationResult::fail($error, $code);
    }
}

ValidationResultInterface & ValidationResult

用于表示验证结果，封装验证是否通过、错误信息与错误代码

namespace Hizpark\ValidationInterface\Result;

ValidationResult::ok();                   // 构造成功结果
ValidationResult::fail('error message');  // 构造失败结果

🔍 静态分析

使用 PHPStan 工具进行静态分析，确保代码的质量和一致性：

composer stan

🎯 代码风格

使用 PHP-CS-Fixer 工具检查代码风格：

composer cs:chk

使用 PHP-CS-Fixer 工具自动修复代码风格问题：

composer cs:fix

✅ 单元测试

执行 PHPUnit 单元测试：

composer test

执行 PHPUnit 单元测试并生成代码覆盖率报告：

composer test:coverage

🤝 贡献指南

欢迎 Issue 与 PR，建议遵循以下流程：

Fork 仓库
创建新分支进行开发
提交 PR 前请确保测试通过、风格一致
提交详细描述

📜 License

MIT License. See the LICENSE file for details.

hizpark / validation-interface

Maintainers

Details