nette/neon is a Backend project on GitHub, written primarily in PHP. It has 939 stars. šø Encodes and decodes NEON file format.
Snapshot summary built from the project's own GitHub metadata ā there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then ā see the READ ME tab for the original README in full.
ā A NEON parser that keeps every comment and space
ā Edit a configuration file and the diff is only your change
ā Your own values for entities, constants or parameters
ā neon-lint for editors, CI and AI agents
Ā
NEON parser, encoder and lossless editor for PHP. NEON is the human-friendly configuration
format of the Nette framework, a YAML alternative with entities. This library parses it into a
concrete syntax tree in which every character of the file has its place, so printing the tree
gives the file back byte for byte:
$document = Nette\Neon\Neon::parse($text);
$document->print() === $text; // true, for any input NEON accepts
That is what makes editing safe. Change a value, add a key, remove an item, and the rest of the
file stays as its author wrote it:
- host: localhost # the server
+ host: db.example.com # the server
On that you build configuration editors and admin panels, installers that register an extension
in config.neon, migrations that rename a service, and AI agents that change configuration
without wrecking it.
Ā
Support Neon
Do you like NEON? Are you looking forward to the new features?
Thank you!
Ā
NEON in one minute
# mappings and sequences, indented by tabs or spaces
database:
host: localhost
port: 3306
roles: [guest, member, admin] # inline arrays
# entities: a value with attributes, the way Nette writes services
mailer: App\Mailer(@smtp, timeout: 30)
note: '''
multiline strings
without escaping
'''
JSON is a subset of NEON, except for a colon at the start of a line glued to its value
("a" + new line + :1), which NEON reads as a literal. The format is described in the manual,
and you can try it in the sandbox.
ā¶ Runnable examples: examples/edge-cases
Ā
Installation
composer require nette/neon
It requires PHP 8.4 up to 8.6 with the json and mbstring extensions.
Ā
Decoding and encoding
use Nette\Neon\Neon;
$value = Neon::decode('hello: world'); // ['hello' => 'world']
$value = Neon::decodeFile('config.neon');
$neon = Neon::encode(['a' => [1, 2]]); // '{a: [1, 2]}'
$neon = Neon::encode(['a' => [1, 2]], true); // "a:\n\t- 1\n\t- 2\n\n"
$neon = Neon::encode($config, fn($v, $path) => !$path); // blocks for the first level only
NEON
PHP
null, true, yes ...
null, bool
integer
int, beyond the 64-bit range a string of its digits
float
float
string
string
date
DateTimeImmutable; an invalid date such as 2024-02-30 stays a string
entity, chain
Nette\Neon\Entity
list, map
array
Errors throw Nette\Neon\Exception with the position of the problem. What encode() cannot write
without loss, such as invalid UTF-8, INF or a cycle, is an error that names the path to the value.
Every edit changes the tokens it edits and nothing else, and the guarantees of the specification
(the file reads back as the same tree, with the expected value, with the change only where it was
made) are checked after every operation of a large corpus of edits.
use Nette\Neon\CommentPolicy;
use Nette\Neon\Neon;
$document = Neon::parse($text);
$document->setValue(['database', 'port'], 3307); // 0x0CEA stays hexadecimal: 0x0CEB
$document->setValue(['database', 'debug'], false); // yes becomes no, not false
$document->setValue(['timeout'], 30); // the same value: no change at all
$document->setValue(['parameters', 'admin'], '[email protected]'); // a new key, indented like its siblings
$document->addItem(['services'], 'App\OrderFacade'); // a new item of a list
$document->removeItem(['database', 'driver']); // with the comment that describes it
$document->removeItem(['mail'], CommentPolicy::MoveToNextToken);
file_put_contents('config.neon', $document->print());
A missing key in the middle of a path is an error, so a typo does not create a new section.
Removing the last item of a collection leaves it empty (services: []), because in a
configuration empty and missing often mean different things; an item marked nullable loses its
value instead. A refused edit changes nothing, not even half of itself.
$item = $document->findItem(['database', 'user']);
$item->getValue(); // 'root'
$item->getTrailingComments(); // the comment on its line
$item->value->getFirstToken()->text; // the text exactly as written
$item->getPosition(); // line, column and offset, computed from the current tree
Eight node classes (DocumentNode, BlockArrayNode, InlineArrayNode, ArrayItemNode,
EntityNode, EntityChainNode, StringNode, LiteralNode) with named slots, tokens with their
trivia (whitespace, line endings, comments), find(), findAncestor(), siblings, and
Traverser for a walk with replacements.
ā¶ Runnable examples: examples/tree
Ā
Your own values: the Evaluator
Neon::decode() is the tree projected onto PHP values by Nette\Neon\Evaluator. A subclass
changes how literals, strings, entities and items become values, while the keys and the order of
the arrays stay those of the document; that is how the DI container of Nette reads its
configuration.
final class ConstantEvaluator extends Nette\Neon\Evaluator
{
protected function evaluateLiteral(Nette\Neon\Nodes\LiteralNode $node, Nette\Neon\Place $place): mixed
{
$value = parent::evaluateLiteral($node, $place);
return is_string($value) && defined($value) ? constant($value) : $value;
}
}
$config = new ConstantEvaluator()->evaluate(Nette\Neon\Neon::parse($text)->value);
ā¶ Runnable examples: examples/evaluator
Ā
For editors, CI and AI agents
vendor/bin/neon-lint config/
config/local.neon:3:2: Duplicated key 'user'
One line per finding, the exit code as the verdict (0 valid, 1 findings, 2 a failure of the tool),
--json for tools, --check to verify that the file reads back byte for byte. An AI agent that
runs it after it saves a .neon file fixes a broken one before it goes on.
ā¶ Runnable examples: examples/linting
Ā
One format, one specification
The format, the value model, the tree and the semantics of editing are written down in a
language-neutral specification with a conformance corpus,
and every implementation runs that corpus in its tests. The same specification is implemented
for JavaScript and TypeScript by @nette/neon; the two
implementations were checked against each other and against nette/neon 3.4 over tens of
thousands of real-world files.
Ā
Upgrading from 3.x
Neon::decode(), decodeFile() and encode() work as before and give the same values. What
changed:
it requires PHP 8.4 or newer with the mbstring extension;
some error messages are more precise, so code that matches their text may need a change;
the tree is new: Neon::parse() gives a lossless DocumentNode; Decoder,
Node\* and the old Traverser are gone; the constants Neon::BLOCK and Neon::CHAIN are
deprecated (use blockMode: true and Neon::Chain);
encode() refuses invalid UTF-8 instead of replacing it, and writes floats and dates without
loss;
a subclass of Evaluator that projects two different keys of one array onto the same key gets
an error, not a silently overwritten value.
Ā
Limits
No formatter: the library keeps your formatting, it does not impose one.
No schema or validation of values.
No error recovery: an invalid file is reported, not partially parsed.
Positions are computed on request, from the current tree.
Ā
Documentation
The examples are the documentation of the API, each chapter with the real output of
its programs. The format itself is documented in the Nette manual.
The most recent commit recorded on nette/neon was 12 days ago, based on the GitHub push timestamp. The repository has 36 forks ā one of the better signals of community interest.
Is nette/neon open source?
TopGit's metadata for nette/neon does not record a license. Most public repositories on GitHub ARE open source, but the exact terms vary ā verify by opening the LICENSE file directly.
What topics is nette/neon associated with?
GitHub's repository topics for nette/neon: "language", "neon", "neon-syntax", "nette", "nette-framework", "parsing", "php", "yaml". TopGit's editorial category is Backend.
Where can I see nette/neon in action?
The project maintains a homepage at https://neon.nette.org. The README tab on this page also usually contains screenshots and a quickstart.
Where do I read more about nette/neon?
This TopGit page is a snapshot ā the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/nette/neon is the definitive source.
Read full README in the tab above.
Curious whether neon is right for you?
Let ChatGPT, Claude, or Perplexity look into it ā click below and see what AI actually says about neon.