Neon vs. Yaml and How to Migrate Between Them

This post was updated on April 2018
Updated with ECS 4.0, Neon to Yaml migration and checkers to services migration.

Do you know *.neon format? It's config file format created in Czech Republic by David Grudl (author of Nette) and if you're foreigner, you might know it from or EasyCodingStandard and PHPStan. Even suggested as composer.neon.

And *.yaml is similar format used almost everywhere else.

You spot the suffix is different, but what about syntax differences? And which one is better?

None of them is perfect, they both have strong parts and weak parts. But the more I travel to abroad conferences, meetups or repositories, the more I hear nobody understand differences between them or their advantages to each other. Since I meet mainly with Symfony and Nette code, I had to investigate them a bit deeper.

There are no solutions. There are only trade-offs.
Thomas Sowell, author of A Conflict of Visions: Ideological Origins of Political Struggles

Here is a summary of what I found and how to migrate to each other. I'll write about differences and places, where syntax fail me the most.

How is Syntax Differ?

70 % of syntax is similar:

# easy-coding-standard.yml
    Symplify\CodingStandard\Fixer\Import\ImportNamespacedNameFixer: ~

But what about?

    - { key: value }

Of course you can Google documentation and try to understand it. But documentation is incomplete or for older version than you use. The best way to learn it for me is with online parsers:

1. Tabs vs. Spaces


As neon was born as free format, it allows to use both spaces and tabs.


Only spaces are allowed. Since most of projects have coding standards, I prefer using one format in whole code.

2. Magic List Combination vs. Single Type

    - SomeService
    SomeService: ~


Could you guess the output? 1 item? Syntax error?

array (1)
    services => array (2)
        0 => "SomeService" (11)
        SomeService => "~"

Neon allows to combine indexed arrays and lists. And do you work with or create with such lists in PHP?


Parsing would fail there, because Yaml allows only one approach:

    - SomeService
    - SomeService

# with 2 items in array


    SomeService: ~
    SomeService: ~

# with 1 item

This difference is one of the biggest WTFs, because I had to think about format and possible merge error every time I used lists... or indexed arrays... or is it arrays? Uff.

3. Content on Multi-lines

I write posts in Statie, where you can use Yaml to configure per-post variables (@todo linn to post), like perex:


perex: '''
    This is long multiline perex,
that takes too much space.

Note it can be aligned to left side.


perex: |
    This is long multiline perex,
    that takes too much space.

But here it must be indented on every line.

4. Very Complex Syntax


In Neon you can use entities and do this:

someValue: Column(type=int, nulls=true)

Could you guess what it is? Parameters, arguments, service decoration?

array (1)
    someValue => Nette\Neon\Entity
        value => "Column" (6)
        attributes => array (2)
            type => "int" (3)
            nulls => true

Personally I prefer explicit, clear naming combined with easier scalability:

    value: "Column"
        type: "int"
        nulls: true


You can do similar shenaniganz with Yaml as well thanks to Symfony\ExpressionLanguage

# easy-coding-standard.yml
        arguments: ["@=service('App\\\\Mail\\\\MailerConfiguration').getMailerMethod()"]

If you want to see real-life example, I tried it once. But went quickly back because I could not remember what exactly that means and how it work.

How is the Ecosystem Support?

This is the most important question when it comes to open-source code. You can create your own natural language, that is smart, easy to learn, context aware and super fast. But what if 1.39 billion people speaks English already?

PHPStorm Support


You can install Neon Plugin, that handles param and class autocomplete very nicely. It's enabled for every *.neon file by default.


Yaml support is included in Symfony Plugin. It needs to by enabled per project. It works great, there is just one last thing I miss. It already completes services for Symfony 3.2- format:

        class: AutocompletedClass

But since Symfony 3.3 there is short syntax for services:

    ManuallyTypedService: ~

And it is missing autocomplete in time being. Do you want autocomplete for this case too? Upvote this issue or send PR in Java to the plugin.

Also Github lacks of Neon support.

Who is the Winner?

Which one to pick? It depends on what is important to you. If you use Nette and work in Czech company and Neon is weapon of choice for you - it's ok.

But what if you're making open source for the whole world?

Why are Standards so Important?

I was on a train trip in Hungary and I was thirsty. I went to classic food shop and pick first bottle with still water I saw. I wanted still water cause gas hurts me and wanted to drink a lot. And I'm drunk when it comes to water in summer.

At least I though I picked the right one until I opened it. In every single country I've been to so far, the blue is always still water. But not in Hungary!

As Chris says: "In Hungary the color code is reversed where blue means sparkling and red means flat." And there is even question on Tripadvisor on this topic.

For all the reasons above (thirsty-human-friendly-bottle-colors included), after looking at problem from various points of view and discussing with my Github and PHP friends, I came to conclusion that Yaml is better for me.

How to Migrate from Neon to Yaml?

But EasyCodingStandard was running on Neon that was loaded by my few classes to Symfony Kernel, so how to migrate to Yaml?


-    - packages/EasyCodingStandard/config/psr2.neon
+    - { resource: 'packages/EasyCodingStandard/config/psr2.yml' }

-    - common/array.neon
-    - common/control-structures.neon
-    - common/docblock.neon
+    - { resource: 'common/*.yml' }


     # class should be Abstact or Final
-    - SlamCsFixer\FinalInternalClassFixer
+    SlamCsFixer\FinalInternalClassFixer: ~
     ArrayFixer: ~

Quoting parameters

-            - *packages/CodingStandard/src/Sniffs/*/*Sniff.php
+            - '*packages/CodingStandard/src/Sniffs/*/*Sniff.php'


-perex: '''
+perex: |
     Do you know `*.neon` format? It's config file
-format created in Czech Republic...
+    format created in Czech Republic...

And from *.yml to *.neon? Just revert - and + :).

To see what code exactly had to change:

Which format do you prefer and why? Do you have some other WTF examples or migration tips? Let me know in the comments!

Happy coding!

  Continue Learning

This Post is Tested, Make it Last Forever

The final code is tested (see it on Github) and is the best solution in time being.

Thanks to tests this code:

  • always run against the most recent dependencies
  • will get updates with just a little work
  • will be useful for as long as possible

Read more about tested posts as they're essential for post's lifetime.

Without tests the post won't make it through next major release and it's long tail effect would spread obsolete practise.

What do you think?

GitHub RSS @votrubaT Runs on Statie Hosted on GitHub

Like what I write about? Hire me & we can work together