NEON 4 parses a file into a lossless syntax tree in which every comment and every space has its place, so you can edit a configuration and the diff shows only your change. Decoding and encoding stay as they were: Neon::decode() gives the same values as 3.4.

✨ New Features

• Lossless parsing – Neon::parse($text)->print() === $text holds for any input NEON accepts
• Format-preserving editing – setValue(), addItem() and removeItem() change only the tokens they edit: 0x0CEA stays hexadecimal, yes becomes no, a new key is indented like its siblings, and a removed item takes its comment along. A refused edit changes nothing at all, so installers, admin panels and AI agents can rewrite config.neon safely
• A navigable tree – nodes know their parent, their comments and their position (line, column, offset); find(), findAncestor(), siblings, and a public Traverser that can replace and remove nodes on the walk
• Evaluator – subclass it to turn literals, strings or entities into your own values, such as constants or parameters, the way the Nette DI container reads its configuration
• Neon::encode() accepts a closure as $blockMode to decide per array whether it is written as a block, e.g. fn($v, $path) => !$path for the first level only, and writes floats in the shortest form that reads back exactly
• Exception carries the position of the problem as an object and the bare message via getDescription()
• neon-lint reports one line per finding, --json for tools and --check to verify that a file prints back byte for byte; an AI agent can run it after saving a .neon file
• Runnable examples with their real output document the whole API
• The format, the tree and the editing semantics follow a language-neutral specification shared with the JavaScript implementation @nette/neon

💥 Breaking Changes

• Requires PHP 8.4 or newer and the mbstring extension
• The tree API is new: Neon::parse() returns a Nodes\DocumentNode, and the classes Decoder, Node\* and the old Traverser are gone. Code that walked the old nodes moves to the new tree, see examples/tree
• Neon::encode() throws Nette\Neon\Exception for a string that is not valid UTF-8 instead of replacing it with U+FFFD; its errors now name the path to the value
• Some error messages are more precise; code that matches their text may need an update
• neon-lint has a new command-line contract: --debug is gone, and a failure of the tool itself exits with 2
• Neon::BLOCK and Neon::CHAIN are deprecated, use blockMode: true and Neon::Chain

🐛 Bug Fixes

• Neon::encode() now quotes strings like -.5 and +.5, so they decode back as strings, not floats
• Multiline strings whose first line starts with whitespace, or with a line starting with ''', now survive an encode and decode round trip unchanged
• neon-lint no longer mistakes --debug for the path to check

🛡️ Robustness

• The parser holds up against hostile input: nesting deeper than 500 levels throws Too deep nesting instead of overflowing the stack, and deeply nested dash lists no longer take exponential time to parse
• Error messages count the column in characters rather than bytes, and their excerpts never cut a multibyte character in half

• PHP 8.6 is supported
• A literal shaped like a date that is not a valid one, such as 2024-02-30 or 2024-13-01, now decodes as a plain string
• The entity name !!chain is reserved for chained entities and can no longer be written in the input

• More precise phpDoc types across the codebase – better autocompletion and stricter static analysis
• Improved phpDoc descriptions for the public API

• Encoder: invalid UTF-8 sequences are replaced with U+FFFD #76
• improved neon-lint

• fixed mixed indents in block strings (#78)
• Nodes: removes null nodes after traversal
• adjusted exception message

• support for PHP 8.5
• optimized global function calls

• support for PHP 8.4
• Encoder: fixed encoding of control characters #72

• support for PHP 8.4
• Encoder: fixed encoding of control characters #72
• Neon::decodeFile() is atomic

• Decoder: fixed JSON parsing with \n before comma
• Decoder: big integers are decoded as strings #9