{"id":14965421,"url":"https://github.com/nette/neon","last_synced_at":"2025-05-13T18:14:29.670Z","repository":{"id":15215102,"uuid":"17943582","full_name":"nette/neon","owner":"nette","description":"🍸 Encodes and decodes NEON file format.","archived":false,"fork":false,"pushed_at":"2025-03-31T00:29:47.000Z","size":399,"stargazers_count":917,"open_issues_count":4,"forks_count":35,"subscribers_count":47,"default_branch":"master","last_synced_at":"2025-05-03T01:46:08.717Z","etag":null,"topics":["language","neon","neon-syntax","nette","nette-framework","parsing","php","yaml"],"latest_commit_sha":null,"homepage":"https://ne-on.org","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nette.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"dg","custom":"https://nette.org/donate"}},"created_at":"2014-03-20T13:30:11.000Z","updated_at":"2025-04-29T21:16:41.000Z","dependencies_parsed_at":"2023-02-19T11:31:18.674Z","dependency_job_id":"7d6d1b70-6278-49d8-bb25-c4e305dd4487","html_url":"https://github.com/nette/neon","commit_stats":{"total_commits":323,"total_committers":16,"mean_commits":20.1875,"dds":0.08359133126934981,"last_synced_commit":"9762109f344a7b0a892d8fcc9dde3e49cbeb3f75"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nette%2Fneon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nette%2Fneon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nette%2Fneon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nette%2Fneon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nette","download_url":"https://codeload.github.com/nette/neon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254000885,"owners_count":21997443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["language","neon","neon-syntax","nette","nette-framework","parsing","php","yaml"],"created_at":"2024-09-24T13:34:44.237Z","updated_at":"2025-05-13T18:14:29.642Z","avatar_url":"https://github.com/nette.png","language":"PHP","readme":"[![NEON](https://github.com/nette/neon/assets/194960/9d3c809d-0a60-4ff0-a54a-bbb25273a8a8)](https://ne-on.org)\n\n[![Downloads this Month](https://img.shields.io/packagist/dm/nette/neon.svg)](https://packagist.org/packages/nette/neon)\n[![Tests](https://github.com/nette/neon/workflows/Tests/badge.svg?branch=master)](https://github.com/nette/neon/actions)\n[![Coverage Status](https://coveralls.io/repos/github/nette/neon/badge.svg?branch=master)](https://coveralls.io/github/nette/neon?branch=master)\n[![Latest Stable Version](https://poser.pugx.org/nette/neon/v/stable)](https://github.com/nette/neon/releases)\n[![License](https://img.shields.io/badge/license-New%20BSD-blue.svg)](https://github.com/nette/neon/blob/master/license.md)\n\n \u003c!----\u003e\n\nIntroduction\n============\n\nNEON is a human-readable structured data format. In Nette, it is used for configuration files. It is also used for structured data such as settings, language translations, etc. [Try it on the sandbox](https://ne-on.org).\n\nNEON stands for *Nette Object Notation*. It is less complex and ungainly than XML or JSON, but provides similar capabilities. It is very similar to YAML. The main advantage is that NEON has so-called [entities](#entities), thanks to which the configuration of DI services is so sexy. And allows tabs for indentation.\n\nNEON is built from the ground up to be simple to use.\n\n \u003c!----\u003e\n\n[Support Neon](https://github.com/sponsors/dg)\n----------------------------------------------\n\nDo you like NEON? Are you looking forward to the new features?\n\n[![Buy me a coffee](https://files.nette.org/icons/donation-3.svg)](https://github.com/sponsors/dg)\n\nThank you!\n\n \u003c!----\u003e\n\nUsage\n=====\n\nInstall via Composer:\n\n```\ncomposer require nette/neon\n```\n\nIt requires PHP version 8.0 up to 8.4. Documentation can be found on the [website](https://doc.nette.org/neon).\n\n`Neon::encode()` returns `$value` converted to NEON. As the second parameter `$blockMode` you can pass true, which will create multiline output. The third parameter `$indentation` specifies the characters used for indentation (default is tab).\n\n```php\nuse Nette\\Neon\\Neon;\n\n$neon = Neon::encode($value); // Returns $value converted to NEON\n$neon = Neon::encode($value, true); // Returns $value converted to multiline NEON\n```\n\n`Neon::decode()` converts given NEON to PHP value:\n\n```php\n$value = Neon::decode('hello: world'); // Returns an array ['hello' =\u003e 'world']\n```\n\n`Neon::decodeFile()` converts given NEON file to PHP value:\n\n```php\n$value = Neon::decodeFile('config.neon');\n```\n\nAll methods throw `Nette\\Neon\\Exception` on error.\n\n \u003c!----\u003e\n\nIntegration\n===========\n\n- NetBeans (has built-in support)\n- PhpStorm ([plugin](https://plugins.jetbrains.com/plugin/7060?pr))\n- Visual Studio Code ([plugin](https://marketplace.visualstudio.com/items?itemName=Kasik96.latte))\n- Sublime Text 3 ([plugin](https://github.com/FilipStryk/Nette-Latte-Neon-for-Sublime-Text-3))\n- Sublime Text 2 ([plugin](https://github.com/Michal-Mikolas/Nette-package-for-Sublime-Text-2))\n\n\n- [NEON for PHP](https://doc.nette.org/neon)\n- [NEON for JavaScript](https://github.com/matej21/neon-js)\n- [NEON for Python](https://github.com/paveldedik/neon-py).\n\n\nYou can check for syntax errors in Neon files using the `neon-lint` console command:\n\n```shell\nvendor/bin/neon-lint \u003cpath\u003e\n```\n\n \u003c!----\u003e\n\nSyntax\n======\n\nA file written in NEON usually consists of a sequence or mapping.\n\n\nMappings\n--------\nMapping is a set of key-value pairs, in PHP it would be called an associative array. Each pair is written as `key: value`, a space after `:` is required. The value can be anything: string, number, boolean, null, sequence, or other mapping.\n\n```neon\nstreet: 742 Evergreen Terrace\ncity: Springfield\ncountry: USA\n```\n\nIn PHP, the same structure would be written as:\n\n```php\n[ // PHP\n\t'street' =\u003e '742 Evergreen Terrace',\n\t'city' =\u003e 'Springfield',\n\t'country' =\u003e 'USA',\n]\n```\n\nThis notation is called a block notation because all items are on a separate line and have the same indentation (none in this case). NEON also supports inline representation for mapping, which is enclosed in brackets, indentation plays no role, and the separator of each element is either a comma or a newline:\n\n```neon\n{street: 742 Evergreen Terrace, city: Springfield, country: USA}\n```\n\nThis is the same written on multiple lines (indentation does not matter):\n\n```neon\n{\n\tstreet: 742 Evergreen Terrace\n\t\tcity: Springfield, country: USA\n}\n```\n\nAlternatively, `=` can be used instead of \u003ccode\u003e: \u003c/code\u003e, both in block and inline notation:\n\n```neon\n{street=742 Evergreen Terrace, city=Springfield, country=USA}\n```\n\n\nSequences\n---------\nSequences are indexed arrays in PHP. They are written as lines starting with the hyphen `-` followed by a space. Again, the value can be anything: string, number, boolean, null, sequence, or other mapping.\n\n```neon\n- Cat\n- Dog\n- Goldfish\n```\n\nIn PHP, the same structure would be written as:\n\n```php\n[ // PHP\n\t'Cat',\n\t'Dog',\n\t'Goldfish',\n]\n```\n\nThis notation is called a block notation because all items are on a separate line and have the same indentation (none in this case). NEON also supports inline representation for sequences, which is enclosed in brackets, indentation plays no role, and the separator of each element is either a comma or a newline:\n\n```neon\n[Cat, Dog, Goldfish]\n```\n\nThis is the same written on multiple lines (indentation does not matter):\n\n```neon\n[\n\tCat, Dog\n\t\tGoldfish\n]\n```\n\nHyphens cannot be used in an inline representation.\n\n\nCombination\n-----------\nValues of mappings and sequences may be other mappings and sequences. The level of indentation plays a major role. In the following example, the hyphen used to indicate sequence items has a greater indent than the `pets` key, so the items become the value of the first line:\n\n```neon\npets:\n   - Cat\n   - Dog\ncars:\n   - Volvo\n   - Skoda\n```\n\nIn PHP, the same structure would be written as:\n\n```php\n[ // PHP\n\t'pets' =\u003e [\n\t\t'Cat',\n\t\t'Dog',\n\t],\n\t'cars' =\u003e [\n\t\t'Volvo',\n\t\t'Skoda',\n\t],\n]\n```\n\nIt is possible to combine block and inline notation:\n\n```neon\npets: [Cat, Dog]\ncars: [\n\tVolvo,\n\tSkoda,\n]\n```\n\nBlock notation can no longer be used inside an inline notation, this does not work:\n\n```neon\nitem: [\n\tpets:\n\t - Cat     # THIS IS NOT POSSIBLE!!!\n\t - Dog\n]\n```\n\nIn the previous case, we wrote a mapping whose elements were sequences. Now, let's try it the other way around and create a sequence containing mappings:\n\n```neon\n-\n\tname: John\n\tage: 35\n-\n\tname: Peter\n\tage: 28\n```\n\nIt's not necessary for the bullet points to be on separate lines; they can also be placed in this manner:\n\n```neon\n- name: John\n  age: 35\n- name: Peter\n  age: 28\n```\n\nIt's up to you whether you align the keys in a column using spaces or a tab.\n\nBecause PHP uses the same structure for mapping and sequences, that is, arrays, both can be merged. The indentation is the same this time:\n\n```neon\n- Cat\nstreet: 742 Evergreen Terrace\n- Goldfish\n```\n\nIn PHP, the same structure would be written as:\n\n```php\n[ // PHP\n\t'Cat',\n\t'street' =\u003e '742 Evergreen Terrace',\n\t'Goldfish',\n]\n```\n\n\nStrings\n-------\nStrings in NEON can be enclosed in single or double quotes. But as you can see, they can also be without quotes.\n\n```neon\n- A unquoted string in NEON\n- 'A singled-quoted string in NEON'\n- \"A double-quoted string in NEON\"\n```\n\nIf the string contains characters `# \" ' , : = - [ ] { } ( )` that can be confused with NEON syntax, it must be enclosed in quotation marks. We recommend using single quotes because they do not use escaping. If you need to enclose a quotation mark in such a string, double it:\n\n```neon\n'A single quote '' inside a single-quoted string'\n```\n\nDouble quotes allow you to use escape sequences to write special characters using backslashes `\\`. All escape sequences as in the JSON format are supported, plus `\\_`, which is an non-breaking space, ie `\\u00A0`.\n\n```neon\n- \"\\t \\n \\r \\f \\b \\\" \\\\ \\/ \\_\"\n- \"\\u00A9\"\n```\n\nThere are other cases where you need to enclose strings in quotation marks:\n- they begin or end with spaces\n- look like numbers, booleans, or null\n- NEON would understand them as [dates](#dates)\n\n\nMultiline Strings\n-----------------\n\nA multiline string begins and ends with a triple quotation mark on separate lines. The indent of the first line is ignored for all lines:\n\n```neon\n'''\n\tfirst line\n\t\tsecond line\n\tthird line\n\t'''\n```\n\nIn PHP we would write the same as:\n\n```php\n\"first line\\n\\tsecond line\\nthird line\" // PHP\n```\n\nEscaping sequences only work for strings enclosed in double quotes instead of apostrophes:\n\n```neon\n\"\"\"\n\tCopyright \\u00A9\n\"\"\"\n```\n\n\nNumbers\n-------\nNEON understands numbers written in so-called scientific notation and also numbers in binary, octal and hexadecimal:\n\n```neon\n- 12         # an integer\n- 12.3       # a float\n- +1.2e-34   # an exponential number\n\n- 0b11010    # binary number\n- 0o666      # octal number\n- 0x7A       # hexa number\n```\n\n\nNulls\n-----\nNull can be expressed in NEON by using `null` or by not specifying a value. Variants with a capital first or all uppercase letters are also allowed.\n\n```neon\na: null\nb:\n```\n\n\nBooleans\n--------\nBoolean values are expressed in NEON using `true` / `false` or `yes` / `no`. Variants with a capital first or all uppercase letters are also allowed.\n\n```neon\n[true, TRUE, True, false, yes, no]\n```\n\n\nDates\n-----\nNEON uses the following formats to express data and automatically converts them to `DateTimeImmutable` objects:\n\n```neon\n- 2016-06-03                  # date\n- 2016-06-03 19:00:00         # date \u0026 time\n- 2016-06-03 19:00:00.1234    # date \u0026 microtime\n- 2016-06-03 19:00:00 +0200   # date \u0026 time \u0026 timezone\n- 2016-06-03 19:00:00 +02:00  # date \u0026 time \u0026 timezone\n```\n\n\nEntities\n--------\nAn entity is a structure that resembles a function call:\n\n```neon\nColumn(type: int, nulls: yes)\n```\n\nIn PHP, it is parsed as an object [Nette\\Neon\\Entity](https://api.nette.org/3.4/Nette/Neon/Entity.html):\n\n```php\n// PHP\nnew Nette\\Neon\\Entity('Column', ['type' =\u003e 'int', 'nulls' =\u003e true])\n```\n\nEntities can also be chained:\n\n```neon\nColumn(type: int, nulls: yes) Field(id: 1)\n```\n\nWhich is parsed in PHP as follows:\n\n```php\n// PHP\nnew Nette\\Neon\\Entity(Nette\\Neon\\Neon::Chain, [\n\tnew Nette\\Neon\\Entity('Column', ['type' =\u003e 'int', 'nulls' =\u003e true]),\n\tnew Nette\\Neon\\Entity('Field', ['id' =\u003e 1]),\n])\n```\n\nInside the parentheses, the rules for inline notation used for mapping and sequences apply, so it can be divided into several lines and it is not necessary to add commas:\n\n```neon\nColumn(\n\ttype: int\n\tnulls: yes\n)\n```\n\n\nComments\n--------\nComments start with `#` and all of the following characters on the right are ignored:\n\n```neon\n# this line will be ignored by the interpreter\nstreet: 742 Evergreen Terrace\ncity: Springfield  # this is ignored too\ncountry: USA\n```\n\n\nNEON Versus JSON\n================\nJSON is a subset of NEON. Each JSON can therefore be parsed as NEON:\n\n```neon\n{\n\"php\": {\n\t\"date.timezone\": \"Europe\\/Prague\",\n\t\"zlib.output_compression\": true\n},\n\"database\": {\n\t\"driver\": \"mysql\",\n\t\"username\": \"root\",\n\t\"password\": \"beruska92\"\n},\n\"users\": [\n\t\"Dave\", \"Kryten\", \"Rimmer\"\n]\n}\n```\n\nWhat if we could omit quotes?\n\n```neon\n{\nphp: {\n\tdate.timezone: Europe/Prague,\n\tzlib.output_compression: true\n},\ndatabase: {\n\tdriver: mysql,\n\tusername: root,\n\tpassword: beruska92\n},\nusers: [\n\tDave, Kryten, Rimmer\n]\n}\n```\n\nHow about braces and commas?\n\n```neon\nphp:\n\tdate.timezone: Europe/Prague\n\tzlib.output_compression: true\n\ndatabase:\n\tdriver: mysql\n\tusername: root\n\tpassword: beruska92\n\nusers: [\n\tDave, Kryten, Rimmer\n]\n```\n\nAre bullets more legible?\n\n```neon\nphp:\n\tdate.timezone: Europe/Prague\n\tzlib.output_compression: true\n\ndatabase:\n\tdriver: mysql\n\tusername: root\n\tpassword: beruska92\n\nusers:\n\t- Dave\n\t- Kryten\n\t- Rimmer\n```\n\nHow about comments?\n\n```neon\n# my web application config\n\nphp:\n\tdate.timezone: Europe/Prague\n\tzlib.output_compression: true  # use gzip\n\ndatabase:\n\tdriver: mysql\n\tusername: root\n\tpassword: beruska92\n\nusers:\n\t- Dave\n\t- Kryten\n\t- Rimmer\n```\n\nYou found NEON syntax!\n\nIf you like NEON, **[please make a donation now](https://github.com/sponsors/dg)**. Thank you!\n","funding_links":["https://github.com/sponsors/dg","https://nette.org/donate","https://github.com/sponsors/dg)*"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnette%2Fneon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnette%2Fneon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnette%2Fneon/lists"}