Feature roadmap: potential enhancements

[dereuromark]

Overview

This issue tracks potential feature additions for future releases. The library has reached solid TOML 1.1 compliance. These are enhancements that could improve usability and expand use cases.

Strict TOML 1.0 parsing/encoding is being handled separately in PR #15, so the roadmap below now focuses on the remaining follow-up areas.

---

1. Extended Encoder Options

Problem: The encoder produces canonical output but users may want control over formatting.

Current options:

• sortKeys - alphabetically sort keys
• skipNulls - omit null values instead of throwing
• documentFormatting - source-aware vs normalized
• version - strict TOML 1.0 vs default TOML 1.1-compatible behavior

Proposed additions:

Integer formatting

• integerBase - Output integers as hex/octal/binary (0xFF, 0o77, 0b1010)
• integerGrouping - Output as 1_000_000 (Add encoder formatting options: integerGrouping, trailingComma, dottedKeys #19)

String formatting

• stringStyle - Use literal strings ('single quotes')
• multilineThreshold - Use multiline for long strings

Array formatting

• arrayStyle - Always use multiline arrays
• trailingComma - Add trailing commas (Add encoder formatting options: integerGrouping, trailingComma, dottedKeys #19)

Table formatting

• inlineTableThreshold - Inline tables with <=N keys
• dottedKeys - Use a.b.c = 1 instead of [a.b] \n c = 1 (Add encoder formatting options: integerGrouping, trailingComma, dottedKeys #19)

---

2. Schema Validation

Problem: Users want to validate TOML structure against expected types and constraints.

Use cases:

• Config file validation
• Editor/IDE integration
• CI/CD pipelines

Proposed approach:

Option A: PHP-native schema

use PhpCollective\Toml\Schema\Schema;
use PhpCollective\Toml\Schema\Types as T;

$schema = new Schema([
    'database' => T::table([
        'host' => T::string()->required(),
        'port' => T::integer()->range(1, 65535)->default(5432),
        'ssl' => T::boolean()->default(false),
    ]),
    'servers' => T::arrayOf(T::table([
        'name' => T::string()->required(),
        'ip' => T::string()->pattern('/^\d+\.\d+\.\d+\.\d+$/'),
    ])),
]);

$result = $schema->validate($config);
if (!$result->isValid()) {
    foreach ($result->getErrors() as $error) {
        echo "{$error->path}: {$error->message}\n";
    }
}

Option B: JSON Schema compatibility

$schema = Schema::fromJsonSchema('/path/to/schema.json');
$result = $schema->validate($config);

Scope:

• Define type system (string, integer, float, boolean, datetime, array, table)
• Add constraints (required, default, range, pattern, enum, arrayOf)
• Implement validation with path-aware error messages
• Consider JSON Schema subset compatibility

---

Priority

Feature	Complexity	Value	Suggested Priority
Extended encoder options	Low	Medium	P2
Schema validation	High	High	P3

---

Discussion

Feedback welcome on:

• Which features are most needed?
• API design preferences?
• Additional features not listed?