PHPackages                             aurabx/harmony-toml-validator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. aurabx/harmony-toml-validator

ActiveLibrary[Validation & Sanitization](/categories/validation)

aurabx/harmony-toml-validator
=============================

TOML validation library for Harmony Proxy configuration files against DSL schemas

0.2.0(4mo ago)037MITPHPPHP ^8.3

Since Nov 6Pushed 4mo agoCompare

[ Source](https://github.com/aurabx/harmony-toml-validator-php)[ Packagist](https://packagist.org/packages/aurabx/harmony-toml-validator)[ Docs](https://github.com/aurabx/harmony-toml-validator-php)[ RSS](/packages/aurabx-harmony-toml-validator/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (3)Used By (0)

Harmony TOML Validator
======================

[](#harmony-toml-validator)

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
------------

[](#installation)

```
composer require aurabx/harmony-toml-validator
```

Requirements
------------

[](#requirements)

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

Quick Start
-----------

[](#quick-start)

### Validate a Configuration File

[](#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

[](#validate-toml-content)

```
$content = getMessage() . "\n";
}
```

Schema Format
-------------

[](#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

[](#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
-------------------

[](#validation-coverage)

### Type Checking

[](#type-checking)

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

### Required Fields

[](#required-fields)

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

### Constraints

[](#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

[](#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
-------------------

[](#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

[](#specialized-exceptions)

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

Development
-----------

[](#development)

### Running Tests

[](#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

[](#static-analysis)

```
# Run PHPStan at level 8
composer analyse

# Run both analysis and tests
composer check
```

### Code Coverage

[](#code-coverage)

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

Architecture
------------

[](#architecture)

### Core Components

[](#core-components)

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

### Validation Flow

[](#validation-flow)

1. Load schema file using `SchemaLoader`
2. Parse TOML configuration using yosymfony/toml
3. Iterate through schema tables and fields
4. Apply validation rules to configuration values
5. Collect errors and report first validation exception

Limitations
-----------

[](#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
----------------

[](#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
-------

[](#testing)

```
composer test
```

License
-------

[](#license)

MIT

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance75

Regular maintenance activity

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~51 days

Total

2

Last Release

134d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/996e93220fb89bfaaa8bafad3ec296da3e6bb40acfcc2701fc8a7ed491848885?d=identicon)[xtfer](/maintainers/xtfer)

---

Top Contributors

[![xtfer](https://avatars.githubusercontent.com/u/40190?v=4)](https://github.com/xtfer "xtfer (4 commits)")

---

Tags

schemavalidationconfigurationDSLHarmonytoml

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/aurabx-harmony-toml-validator/health.svg)

```
[![Health](https://phpackages.com/badges/aurabx-harmony-toml-validator/health.svg)](https://phpackages.com/packages/aurabx-harmony-toml-validator)
```

###  Alternatives

[opis/json-schema

Json Schema Validator for PHP

64236.9M185](/packages/opis-json-schema)[romaricdrigon/metayaml

Using \[Yaml|Xml|json\] schemas files to validate \[Yaml|Xml|json\]

103306.5k8](/packages/romaricdrigon-metayaml)[evaisse/php-json-schema-generator

A JSON Schema Generator.

20298.5k1](/packages/evaisse-php-json-schema-generator)[romegasoftware/laravel-schema-generator

Generate TypeScript Zod validation schemas from Laravel validation rules

288.2k](/packages/romegasoftware-laravel-schema-generator)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)