Neon Laravel Package

Getting Started

Install the package via Composer: composer require nette/neon. Then use the two core static methods: Neon::decode(string $code) to parse NEON strings into PHP types, and Neon::encode(mixed $value, int $indentation = 2) to serialize PHP data back to NEON. For reading config files, use the atomic Neon::decodeFile(string $file) — it safely reads files without partial reads and returns the decoded structure directly. First-time users should validate PHP 8.2+ compatibility (v3.4.7 requires 8.2–8.5) and ensure ext-json is enabled. Start with a simple config.neon file like:

parameters:
    debugMode: true
    database:
        host: localhost
        port: 5432

Then load it with Neon::decodeFile('config.neon') — no manual file I/O or regex parsing needed.

Implementation Patterns

• Configuration Management: Use decodeFile() in Laravel config loaders (e.g., wrap in a NeonConfigLoader service) to replace JSON/YAML for Nette-dependent apps. It’s safe for concurrent deploys and handles atomic updates.
• AST-Level Processing: Parse NEON with Neon::decode() to get a typed AST (Neon\Ast\Node[]). Use Neon\Ast\Traverser with enter/leave callbacks to lint, validate (e.g., enforce schema rules), or transform values — e.g., inject environment variables by mutating scalar nodes.
• Pre-deployment Linting: Run vendor/bin/neon-lint config/*.neon in CI pipelines (v3.3.1+ includes this). It catches subtle issues like mixed indentation, trailing comments, or unclosed strings that decode() might silently accept.
• Clean Output Encoding: Use Neon::encode($config, indentation: 4) for readability in generated configs, or Neon::encode($data) for compact inline arrays. v3.3.0+ ensures consistent formatting via AST-based encoding.
• Interoperability Workarounds: For non-NEON pipelines (e.g., Symfony YAML), decode NEON → PHP array → encode via Symfony/Yaml. Avoid manual conversions — leverage the AST for correctness.

Gotchas and Tips

• Breaking Changes: v3.0+ removed on/off literals and \xAA escapes (use \u00AA). v3.3.x renamed Node::startPos to startTokenPos. Always update incrementally and run neon-lint after upgrades.
• UTF-8 Safety: Invalid UTF-8 is silently replaced with U+FFFD (v3.4.7+). If strict validation is needed (e.g., user uploads), pre-validate with mb_check_encoding() — don’t rely on Neon::decode() alone.
• Big Integers: Integers beyond PHP_INT_MAX (e.g., snowflake IDs) are decoded as strings to avoid precision loss. Cast with (string) only, and validate range before use.
• Encoding Limits: encode() throws on INF, NAN, and control characters (v3.4.4+). Pre-filter values (e.g., is_finite() for floats) or use fallback like json_encode($data) for edge cases.
• AST Traverser Gotchas: Returning null from a callback deletes nodes, but Traverser::DONT_TRAVERSE_CHILDREN (note the camelCase) skips descent without deleting. To avoid corruption, clone nodes before mutation or use immutable transformation patterns.
• Linter vs Decoder: neon-lint is stricter than Neon::decode() — e.g., it rejects trailing commas in block arrays and mixed indents. Always use neon-lint in CI, even if decodeFile() passes locally.
• Block Strings: Indentation errors in multi-line strings (e.g., text blocks) can cause parsing failures (v3.4.6 fixes some cases, but ensure consistent whitespace). Use encode(..., flags: Neon::BLOCK_LITERAL) only when necessary, and validate output with neon-lint.