Filament Json Yaml Editor Laravel Package

Getting Started

• Install the package as usual (composer require …) and, for the editor components, make sure the front-end assets are published/rebuilt — this release bumps the bundled esbuild to 0.28, so a stale published asset bundle will not pick up the new parser/format behaviour until you re-publish or re-run your asset build.
• Look first at the two entry points you will use daily:
  • Validation: YamlRule and JsonSchemaRule (including JsonSchemaRule::yaml()).
  • Authoring: the JsonEditor and YamlEditor form components.
• The Yaml facade (Yaml::parse(), Yaml::decodeToArrays()) is the low-level API; prefer the rules in request/form validation and only reach for the facade when you need the parsed payload for something other than validation.
• First use case: a settings JSON/YAML column on a model, edited in a form, validated on save.

// app/Models/Setting.php
protected $casts = ['payload' => 'array'];

// app/Http/Requests/UpdateSettingsRequest.php
public function rules(): array
{
    return [
        'payload' => ['required', new YamlRule()],        // YAML input
        // or, when the source is JSON Schema:
        // 'payload' => ['required', JsonSchemaRule::yaml($schema)],
    ];
}

Implementation Patterns

• Pair the cast with the editor. 'array' (built-in or a custom cast, including nested field names) is the expected storage shape; the JsonEditor/YamlEditor components read and write through it. A top-level string accidentally stored by an array cast ("123", "hello", a: b) is now shown as JSON/YAML text and saved back as the same string — handy for legacy rows, but don't rely on it as a design: it means a scalar can round-trip through a field you thought was an array.
• Validate then persist. Run YamlRule (or JsonSchemaRule::yaml($schema)) on the raw textarea value, then decode into the array cast. Keep the raw string out of the model; validate → Yaml::decodeToArrays() → assign.
• Schema-driven forms. JsonSchemaRule with opis/json-schema is the pattern for user-authored config: you get up to maxErrors() messages back, and an unresolvable $ref or a malformed schema keyword now surfaces as a validation error rather than a 500 — so bad schema shipped by an admin is a fixable form error, not an outage. Still wrap schema loading itself (file/DB fetch) in your own error handling.
• Format as a UI affordance, not a migration tool. The Format button only re-indents. Big integers, 1.0, duplicate keys and key order survive untouched. If you were relying on "Format" to normalise stored config (dedupe keys, coerce floats), do that server-side before comparing/diffing.
• Round-trip tests. Because the editor preserves author intent, snapshot tests over stored YAML/JSON are stable. Assert on the parsed array, not on exact whitespace, unless you're specifically testing the indent behaviour.
• Custom tags. If your YAML uses !!set or other non-core tags, resolve them before they reach the parser (pre-process to plain maps) — the bundled js-yaml 5 rejects them by default.

Gotchas and Tips

• Breaking: js-yaml 4 → 5 semantics. YAML timestamps now load as strings, not date objects. Any code doing $config['released_at']->format(...) on a parsed value must cast explicitly (Carbon::parse($value)).
• Breaking: non-core tags rejected. !!set and friends no longer parse by default. This will bite on imported YAML from other toolchains.
• Date keys. Unquoted YAML date keys (2024-12-25: x) now stay strings instead of becoming unix timestamps — good for config maps keyed by date. But note the documented gap: a date key inside a flow map ({2024-01-01: a}) is still rejected unless you pass PARSE_DATETIME. Use block style, or quote the key.
• Parser edge cases now handled (previously mis-parsed, worth knowing if you wrote workarounds): block-scalar text and continuation lines of multi-line quoted scalars (including after an anchor or tag) are no longer mistaken for keys; a comment ending in : | does not start a block scalar; a quote after a spaced -, : or ? inside plain text no longer opens a scalar. Remove any defensive quoting hacks you added for these.
• Security guard is now everywhere. The alias-bomb + merge-key expansion guard also runs on the fallback parse path (Yaml::parse(), Yaml::decodeToArrays(), YamlRule, JsonSchemaRule::yaml()). If you bypass the facade and call a parser directly, you lose that protection — route untrusted YAML through the package.
• Debugging parse errors. Parser messages are interpolated into the editor's error line, and $& / $' in a message no longer corrupts it. When reporting errors to users, log the raw message too; the on-screen line is display-safe but still terse.
• Error volume. maxErrors() bounds JsonSchemaRule output — tune it down for end-user forms (avoids a wall of red) and up in tests where you assert on all failures.
• Upgrade checklist: re-publish assets (esbuild bump), grep for DateTime/Carbon assumptions on parsed YAML, grep for !! tags in fixtures, and re-run any test that asserted on Format-normalised output.