README

PHP library for validating TOML configuration files against Harmony DSL schemas. This package provides a cross-language compatible validator that matches the schema validation implemented in harmony-proxy (Rust).

Installation

composer require aurabx/harmony-toml-validator

Requirements

PHP ^8.3 - Uses typed properties, named parameters, and modern type system
yosymfony/toml ^1.0 - TOML parsing library

Quick Start

Validate a Configuration File

use Runbeam\HarmonyTomlValidator\TomlValidator;
use Runbeam\HarmonyTomlValidator\Exceptions\ValidationException;

$validator = new TomlValidator();

try {
    $validator->validateFile(
        '/path/to/config.toml',
        '/path/to/harmony-config-schema.toml'
    );
    echo "✓ Configuration is valid\n";
} catch (ValidationException $e) {
    echo "✗ Validation failed\n";
    echo "Field: " . $e->getFieldPath() . "\n";
    echo "Error: " . $e->getFormattedError() . "\n";
}

Validate TOML Content

$content = <<<'TOML'
[proxy]
id = "gateway-01"
log_level = "info"
TOML;

try {
    $validator->validateContent($content, '/path/to/schema.toml');
    echo "✓ Configuration is valid\n";
} catch (ValidationException $e) {
    echo "✗ Validation failed: " . $e->getMessage() . "\n";
}

Schema Format

This validator uses the Harmony DSL schema format (TOML-based) that defines:

Tables - Configuration sections (e.g., [proxy], [network.default])
Fields - Table properties with type and constraint information
Types - string, integer, boolean, float, array, table
Constraints - enum, min/max, array bounds, regex patterns, required fields

Example Schema

[[table]]
name = "proxy"
required = true
description = "Core proxy configuration"

[[table.field]]
name = "id"
type = "string"
required = true
description = "Unique proxy identifier"

[[table.field]]
name = "log_level"
type = "string"
required = false
default = "error"
enum = ["trace", "debug", "info", "warn", "error"]
description = "Logging verbosity level"

Validation Coverage

Type Checking

All TOML types: string, integer, boolean, float, array, table
Type mismatches throw TypeValidationException

Required Fields

required = true - Field must be present
required_if = "condition" - Conditional requirements (e.g., backend == 's3')
Missing required fields throw RequiredFieldException

Constraints

enum = [...] - Value must be in allowed list
min / max - Numeric bounds checking
min_items / max_items - Array length validation
pattern - Regex pattern matching
Constraint violations throw ConstraintViolationException

Pattern-Based Tables

Tables with pattern = true match multiple instances (e.g., network.* matches network.default, network.management)
Supports pattern_constraint for regex validation of table names

Exception Hierarchy

All validation errors are exceptions extending ValidationException with detailed context:

try {
    $validator->validateFile($config, $schema);
} catch (ValidationException $e) {
    $e->getFieldPath();           // Dotted path: "network.default.bind_port"
    $e->getRuleName();            // Rule that failed: "min", "enum", "required"
    $e->getActualValue();         // The value that failed validation
    $e->getExpectedConstraint();  // What was expected
    $e->getMessage();             // Short error message
    $e->getFormattedError();      // Formatted error with full context
}

Specialized Exceptions

TypeValidationException - Type mismatches
RequiredFieldException - Missing required fields
ConstraintViolationException - Enum, min/max, pattern violations
SchemaLoadException - Schema file errors

Development

Running Tests

# Run all tests (unit + integration)
composer test

# Run specific test suite
vendor/bin/phpunit --testsuite=Unit
vendor/bin/phpunit --testsuite=Integration

Static Analysis

# Run PHPStan at level 8
composer analyse

# Run both analysis and tests
composer check

Code Coverage

# Generate HTML and text coverage reports
composer test:coverage
# HTML report available in coverage/ directory

Architecture

Core Components

SchemaLoader - Parses schema TOML files into internal representation
SchemaDefinition/SchemaTable/SchemaField - Internal schema data structures
ValidationContext - Tracks validation state and field paths
Validator Rules - Individual validation rule implementations
TomlValidator - Main orchestrator that coordinates validation

Validation Flow

Load schema file using SchemaLoader
Parse TOML configuration using yosymfony/toml
Iterate through schema tables and fields
Apply validation rules to configuration values
Collect errors and report first validation exception

Limitations

Nested field names (e.g., options.path) require special handling not yet implemented
Currently validates table-level and field-level constraints
For advanced conditional logic, consider extending RequiredValidator

Related Projects

harmony-dsl - Schema definitions and DSL specification
harmony-proxy - Rust-based gateway that consumes validated configurations
Runbeam Cloud API - Uses this library for configuration validation

Testing

composer test

License

MIT

aurabx / harmony-toml-validator

Maintainers

Details