Using YAML for configuration? #440

olegstepura opened this Issue Mar 11, 2012 · 68 comments


None yet

Why didn't composer founders choose YAML? Json even does not support comments inside a file.
Yaml is proved to be the best choise for configuration and Symfony proved that.

But it's not too late to also allow yaml usage aswell. 4 example search for composer.json, if not found - for composer.yml


igorw commented Mar 11, 2012

See #159 and this blog post. Quoting the relevant section of the post:

Why JSON for packages?

It is a recurring question so I will answer it, hopefully for the last time. The short answer is because. The longer one is that there are many options (yaml, json, xml, php, ini, whatever.), each have their fan-base, and each have their haters. Whatever we would have picked, someone would be complaining. If you think it is a stupid decision, I am sorry to announce you are in the group selected to be the folks complaining, but it is not going to change. Please try not to focus on such a detail, and look at the bigger picture.

Seldaek closed this Mar 11, 2012


Seldaek commented Mar 11, 2012

Sorry but we will not change this now. It would create much more problems than it would solve. If you want comments you can always use a _something key in the json. It's a common pattern and works just fine.

Well, actually since it's based on Symfony components it's not clear why json and not yaml was the "because". And the thing that json does not support comments makes it a bad choice for configuratin files.see for example.

Why do I need comments? Currently I have some packages that are broken and cannot be installed from composer. But I believe it will be fixed and it would be very convinient to just comment that out temporarily.

Second - json's notation does not allow leaving a comma after the last item in the list. This is also very very annoing when editig settings file.
And the last - in yaml I would type for about 10% less to get the same result.

@Seldaek nope, _key in composer.json causes unresolved items errors.


Seldaek commented Mar 11, 2012

Most of those issues will go away in time. As for the 10% less typing, at least it's not XML :p Seriously this is such a trivial thing, please focus on real problems. Discussing this helps nobody. Having just one format is nicer for consistency and tooling (anything can just look in there for a composer.json, like does). Maybe it was a small mistake to pick json to you, but you will find lots of people also don't like yaml, etc. We can't make everyone happy, and we don't want multiple formats.


Seldaek commented Mar 11, 2012

As for _key in requires, yeah it breaks since it tries to require them, but you can move them in a _temp_require key for example. Another solution would be that we add support for comments in the JSON, some parsers already do that, but I don't like it because it makes it non standard, and the json files are potentially exposed to other services.

Well, actually you can see all the problems are real. Not that 10% typing less, and yes, at least not xml. But lack of comments and fixed structure makes it less flexible. =(


igorw commented Mar 11, 2012

If you really want to use YAML, feel free to use this tool which will convert a composer.yml file to composer.json:

Cool. It needs an option to first-time convert json to yaml to start working with yaml. Maybe making it a bundle (with only Command directory) is a better approach?


stof commented Mar 11, 2012

It has a --reverse option.
And why are you talking about making it a bundle ? It is totally overkill and the script has nothing specific to Symfony so it makes no sense to make it a bundle

well, you're right. Just thought it could be convinient to use Symfony's Console component. Anyways thanks for the script. Will try it and report issues if any found.


stof commented Mar 12, 2012

It is overkill to use the Console component for this. The script is 10 LOC


igorw commented Mar 12, 2012

Please discuss this on the composer-yaml repo.

c33s commented Mar 24, 2012

+1 comments in a config file.

i am presonally not a fan of yaml but i think, for a config file, it's a must to support comments (would even prefer to have single line and block comments).

if the decision to use json is already carved into stone (which i think is wrong), please at least use a json parser which is able to use comments (i mean real comments, not having to hack around with "temp").

Some non-standard implementations of JSON extend the grammar to include Javascript's /.../ comments. (Notes and references [8])

argue that the json file have to be "valid", feels like arguing for standardized tread depth of tires while having no steering wheel in the car.

please think practically. if you look at it from a daily use and agile development view, having no comments is not an option, is it?

supporting multiple formats would also be a solution.
also adding composer-yaml directly into composer would help.

composer should get the pear killer. the solution for php package management. there supporting mulitple formats is a good thing. saying "because" doesn't really help.

What about integrating composer-* converters into composer and adding a switch to composer.phar? The overhead in composer would be negligible as the current composer-yaml implementation shows.

php composer.phar --format=yml update (use YAML file)
php composer.phar --format=xml update (use XML file, whenever someone implements composer.xml)
php composer.phar update (use JSON file, default)

This would be a real help and end discussions once and for all.

@vworldat actually such syntax is only needed when there are composer files of multiple formats in the project root. If there is only one format composer file - composer can guess it's format by extension. Seem like not a big deal actually.

@c33s You can check my convert-config fork at
I made converter an app to not allow overriding target files when you do not want to and to be able to convert between different formats different files, not only composer ones


Seldaek commented Mar 26, 2012

I suppose time will tell, but the way I see it, composer files are not configuration. They do not need to be enabled/disabled partly. It used to be necessary for debugging of what dependency is wrong, but I think the more stable composer gets the less this will be required. I don't know which of you guys are Symfony2 users, but I've been working with that damned deps file + bin/vendors for a year and a half and if there is one thing I never had to do to it is commenting out some bits of it. These are just dependencies, if you comment one out, your project breaks. Done.

Please give it a good thought, give it a few months, and we will see if this is still needed down the line.

@Seldaek Since you use Symfony2 for a long time, your choice for json instead yaml is strange. Symfony2 uses yaml configurations all over the place (except for DI config, but xml with schema has autocompletion - that did the choice I suppose). The need for yaml for composer comes from working with personal project's composer.json (composer.yml), not from creating a bundle and editing it's composer.json (there json is ok).

P.S. Time already tells - here are 3 people already wanting yaml =)


Seldaek commented Mar 26, 2012

What I see is 3 people complaining and a lot more that are just happy to see new stuff happen in PHP and focus on the good parts. Again, please give it some time. If it really becomes a major issue we will see what we will do, but right now I don't think you can judge it objectively, and I sure as hell don't want to spend time addressing such issues when there is so much more important things that need to be done.

ok, anyhow composer is already cool.

@Seldaek thanks for taking your time listening to our comments. composer is a great project, I loved it right from the first time I heard about the idea (quite a while ago).

I want to give you a few examples of useful comments in deps/composer files:

  • when more than 1 person work on the same code, it might be helpful to state the reason for a specific library (which is not always obvious, think of embedding doctrine just for an annotation parser).
  • when you're using a specific version, or even a fork of a library, you might want to add a comment why you did this (e.g. to check back later if you can go stable or master-dev). This is extremely important when several people work on the same project and someone updates a library, not knowing it was pinned for a specific reason. Tests should catch something like this but not always will. Anyway it costs time unnecessarily.
  • when debugging/testing libraries or their versions, it's helpful to be able to "toggle" between 2 of them by commenting/uncommenting.
  • sometimes it's just helpful to group libraries and give those groups names for some reason.

I've had symfony1 projects with up to 30 or 40 external dependencies (lots of them in-company plugins). I used to integrate those mostly through svn externals (without comments) and I always wished for an easier way to manage them. It would be great if composer could provide this new level of manageability.

I agree that in many projects the composer.json file will hardly be touched at all, but especially for developers new to Symfony2 (I'm one at the moment), who just don't know which libraries they will need and in which versions, it would be extremely helpful to have the ability to comment stuff. Believe it or not, I did add comments to my deps file as soon as I made changes to it (e.g. when importing propel).


henrikbjorn commented Mar 26, 2012

The commenting thing, cant that be fixed by getting the json file contents and strip out \w+\#.+$ ?

The problem is that this wouldn't be compatible JSON anymore, so any other language/library loading the file would fail. IMHO this would be worse than the status quo, because if it's JSON on the outside, it should be JSON on the inside.

Imagine doing the same thing with XML. The project would be ranted to death immediately.

It is sad that the JSON specification lacks any kind of comment syntax. It's made for data, not configuration.

vworldat commented Apr 4, 2012

For now we are using composer-yaml and we are quite happy with it. The yaml format provides much better overview of what's going on (together with the IDE's validation and syntax highlighting). We're currently adding/modifying dependencies on a daily basis, so there's quite a lot of time spent in there.

I just want to recommend this to anyone who is unhappy about the json format: try if yml suits your needs and use

To the composer devs: I love the flexibility of composer, we use it to integrate every single external dependency we need (even non-php ones), making heavy use of custom packages. We were able to eliminate any git submodules and manual vendor/library copying!
Please continue your great work on it, and once it's finished, perhaps there will be some time to re-think the file format strategy. If done right, composer will be a game changer for project dependency management.

This is how our composer.yml looks at the moment (letting it speak for itself):

name:           foobar
description:    foobar app
        '': src/

  - name:       David
    homepage:   ''

  - name:       Julian
    homepage:   ''

  - type: package
        name:       twitter/bootstrap
        version:    2.0.1
        source:     { url: '', type: git, reference: v2.0.1 }

  - type: package
        name:       c33s/static-page-content-bundle
        version:    dev-master
        autoload:   { psr-0: { c33s\StaticPageContentBundle: '' } }
        target-dir: c33s/StaticPageContentBundle
        source:     { url: '', type: git, reference: origin/master }

  - type: package
        # requires manual autoloading
        name:       leafo/lessphp
        version:    0.3.3
        source:     { url: '', type: git, reference: v0.3.3 }

  - type: package
        name:       phingofficial/phing
        # do not use phing 2.5+, breaks the build process
        version:    2.4.9
        source:     { url: '', type: git, reference: 2.4.9 }

  - type: package
        name:       willdurand/typehintable-behavior
        version:    dev-master
        source:     { url: '', type: git, reference: origin/master }

  - type: package
        name:       jehu/fire-php-bundle
        version:    dev-master
        source:     { url: '', type: git, reference: origin/master }

  - type: package
        name:       modernizr/modernizr
        version:    2.5.3
        source:     { url: '', type: git, reference: v2.5.3 }

  - type: package
        name:       jquery/jquery
        version:    1.7.2
        source:     { url: '', type: git, reference: 1.7.2 }

  - type: package
        name:       yuicompressor/yuicompressor
        version:    2.4.7
        dist :      { url: '', type: zip }

    php:                                                '>=5.3.2'

# "official" symfony stuff
    symfony/symfony:                                    2.1.*
    doctrine/orm:                                       2.2.0
    doctrine/doctrine-bundle:                           dev-master
    twig/extensions:                                    dev-master
    symfony/assetic-bundle:                             dev-master
    symfony/swiftmailer-bundle:                         dev-master
    symfony/monolog-bundle:                             dev-master
    sensio/distribution-bundle:                         dev-master
    sensio/framework-extra-bundle:                      dev-master
    sensio/generator-bundle:                            dev-master
    jms/security-extra-bundle:                          dev-master

# other packagist packages
    propel/propel1:                                     1.6.5
    propel/propel-bundle:                               dev-master
    knplabs/knp-menu-bundle:                            dev-master
    pagerfanta/pagerfanta:                              dev-master
    raulfraile/LadybugBundle:                           dev-master
    friendsofsymfony/user-bundle:                       dev-master
    cedriclombardot/admingenerator-user-bundle:         dev-master
    fzaninotto/faker:                                   dev-master
    composer/composer:                                  dev-master
    white-october/pagerfanta-bundle:                    dev-master
    cedriclombardot/admingenerator-generator-bundle:    dev-master

# manually defined packages
    twitter/bootstrap:                                  2.0.1
    c33s/static-page-content-bundle:                    dev-master
    leafo/lessphp:                                      0.3.*
    phingofficial/phing:                                2.4.*
    willdurand/typehintable-behavior:                   dev-master
    jehu/fire-php-bundle:                               dev-master
    modernizr/modernizr:                                2.5.3
    jquery/jquery:                                      1.7.2
    yuicompressor/yuicompressor:                        2.4.7

        - 'Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::buildBootstrap'
        - 'Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::clearCache'
        - 'Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::installAssets'
        - 'Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::buildBootstrap'
        - 'Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::clearCache'
        - 'Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::installAssets'
    bin-dir: bin

    symfony-app-dir: app
    symfony-web-dir: web

This is the script we currently use for updating:

#! /usr/bin/sh

php bin/composer-yaml convert
php composer.phar update

I promise to stop bothering you about the file format from now on :-)

Edit: improved yaml list syntax, thx @olegstepura

@vworldat Just a hint for you
You can use hyphen on the same line as start of the array element like this:

    - type: package # <--- see here
          name: FortAwesome/Font-Awesome
          version: dev-master
              url: 'git://'
              type: git
              reference: origin/master

This way a list looks better

patcon commented Jul 17, 2012

Just a quick comment, but wanted to point out that the Drupal community likely has a small stake in this discussion as well. Our current de facto standard for build tools is Drush Make, which allows for a concise representation of a site's components:

If we were to consider moving toward using composer, communities like ours might want some degree of control at the parsing layer. I know that many folks would actively resist moving to a format that was so much more verbose and finicky than what we currently use, with no options to scratch our own itches :)


igorw commented Jul 17, 2012

@patcon If you want to use a ini-style format for drupal, you can always use composer as a library. It's really easy to do your own parsing and then handing the parsed objects off to composer.

It's also worth noting that composer is not a build tool, it really only cares about dependencies. So if you need to do more advanced things in your build, you'll have to do those yourself.

patcon commented Jul 17, 2012

Thanks @igorw, was thinking that might be my next approach for some weekend. Good to know it's the right track.

I guess I'm generalizing the term "build tool" too widely, but it still performs the same function as Drush Make :)


Seldaek commented Jul 19, 2012

Most of the core of composer just assumes an array of a given structure,
whether that comes from a json file or not doesn't matter much, so if
you wrap/integrate composer into drush itself, it should be no problem
to use any file format you like.


Seldaek commented Jul 19, 2012

And I guess @igorw already answered.. I'm going through old emails,
nevermind me :)

I too really wish Composer supported YAML natively (possibly via pluggable file formats with an included connector) since we think YAML is critical for our mostly non-technical target users. But since Composer doesn't we're going to build our own solution. Since we're targeting the WordPress space and since most of the probably 50k+ plugins and themes don't already have Composer files, hopefully we'll be able to establish an alternate packaging standard there; one that uses YAML as it's native file format. Too bad we couldn't just work with Composer. FWIW.


igorw commented Aug 12, 2012

@mikeschinkel Did you read the whole discussion in this ticket? You can easily use composer as a library, and build your own YAML-based frontend to it. It's just that the composer CLI utility does only support JSON.


fprochazka commented Aug 12, 2012

Check out Neon, its YAML & JSON compatible format :)

Hi @igorw; thanks for replying.

Yes I did read the whole discussion. Problem is that one of the benefits of something like Composer is the ecosystem, and the ecosystem doesn't support YAML. So while I could implement a YAML converter the maintainers of the ecosystem would not recognize it as first-class.

It's a shame we have to decide against Composer as we think it'll be better to move in a direction that can result in an ecosystem where YAML is a first-class citizen. We don't really want to go there, but without first-class YAML support in Composer, we don't really have a choice. (By first-class I would mean pluggable formats where Composer is shipped with plugin YAML format support.)

Hi @hosiplan,

Neon looks very interesting, but I don't completely understand what it is. Is it a YAML parser or a new format that is similar to YAML? PHP 5.2 is what WordPress supports so it might be a good fit to build on, assuming it is what I think it is.

But I don't want to hijack this thread so is there somewhere else we can discuss Neon?


fprochazka commented Aug 13, 2012

Neon is a new format, that is compatible with JSON and YAML. It can parse both, and both can be in one file tied together.
You can play with it in the sandbox at just edit the input on the left and see what it outputs :)

If you wan't to, you can discuss it on jabber chat (if you don't have jabber, here is a webclient). Most of us is from Czech Republic, so consider timezones ;)

Hi @hosiplan - So Neon isn't on GitHub and doesn't have a Google Groups mailing list for it? (real-time chat systems can be a huge productivity drain. :)

@mikeschinkel: Neon is part of Nette Framework. Nette is on GitHub and has forum

We are working on extract some cool parts (Neon, Latte, Debugger, Database, etc) of Nette to separate project / repos in near future.

@Vrtak-CZ Thanks. You don't have issues enabled on GitHub? And looking at the code looks if we use it we'd need to maintain a fork since it requires PHP 5.3 (WordPress is currently 5.2 as lowest common denominator.)

@mikeschinkel: Nette is fully compatible with PHP 5.2 (with Nette Build Tools). Here is last stable packages


fprochazka commented Aug 14, 2012

We might wanna move this disscussion to Nette Forum :)


frosas commented Oct 16, 2012

I also appreciate to be able to comment the configuration. It's a shame YAML wasn't chosen in the first place (@vworldat example is so much human friendly).

Anyway, if you don't wan't to depend on the YAML <-> JSON conversor there are still some options:

  • Create a composer.json-comments file and put there whatever you want, as you want. Cons: no implicit context.

  • Make the own parser to overwrite your comments. For example:

    "require": {
        "kriswallsmith/assetic": "# Reference to kriswallsmith/assetic is because symfony/assetic-bundle requires the dev version but we are on stable",
        "kriswallsmith/assetic": "1.1.*@dev",
        "symfony/assetic-bundle": "2.1.*"

    Cons: comments will be deleted if the file is generated by some tool.

Bilge commented Dec 19, 2012

Since when doesn't JSON support comments? Surely this is just a bug in Composer.


Seldaek commented Dec 19, 2012

Blame the man. This is not a bug.


stof commented Dec 19, 2012

@bilgexa Since the spec was written

Bilge commented Dec 19, 2012

@Seldaek Then pipe it through JSMin before handing it to your JSON parser.


Seldaek commented Dec 19, 2012

@bilgexa read comments above, thank you.

Bilge commented Dec 19, 2012

@Seldaek Read this: Composer is shit.

patcon commented Dec 19, 2012

Note to all: Not worth replying.


fprochazka commented Dec 19, 2012


TomiS commented Feb 28, 2013

Well, this is kind of an interesting topic. I'd like to give one point of view that hasn't yet been discussed (at least in this thread). If we think about how a web project is built with Composer, we see that there's a root composer.json file in the project's root folder and then there are vendor packages that also have composer.json files in them.

Now, most of the time, the vendor packages are not a problem. From a project's point of view, one should never need to change or comment composer.json files of vendor packages. So a plain JSON is not a problem for them. However, at the moment the root composer.json must be maintained manually by multiple developers and that's where all the previously mentioned problems begin. I agree with previous writers about how terrible format JSON is when it needs to be maintained manually. On the other hand, it's obvious that composer.json files are designed to be primarily read by computers, not humans.

I guess next I'm going to try the composer-yaml plugin by @igorw and I guess it solves most of the problems. I don't know if it can be configured to run as a pre-deployment hook with Capifony but I really hope so because then we could just use YAML to maintain the root composer.json and there's no need to complain about weaknesses of JSON anymore.

Ps. I think people find this topic so important because most of us are really just trying to develop/maintain web projects with composer through the root composer.json package file and that's our 'user interface'. I guess no-one's denying how major step for PHP community this whole Composer thing is.


Seldaek commented Feb 28, 2013

@TomiS frankly I am fine with people composer-yaml, if you really think you need comments then go ahead and use it. I'm just against building that in composer because I think it'll unnecessarily mess with the tools built around composer. Some IDEs are integrating it, people wrote plugins for others, etc. Those things expect a composer.json, and json is a known and common format that's easy to parse in any language by now. If suddenly the file isn't there, assumptions are broken.

If the pain point is the json format though, composer require, composer config or perhaps some of those IDEs integrating it can help quite a bit to avoid touching it.

TomiS commented Feb 28, 2013

@Seldaek I definitely see your point. I actually was going to mention (but didn't) about the possibility of someone creating a specific tool for editing (root) package contents. It'd be so cool if it could be done with our favorite IDEs. I.e. Click composer.json and a special editor tool opens up instead of text editor.


stof commented Feb 28, 2013

@TomiS Sensio already did it. look at

vnagara commented Apr 6, 2013

@Seldaek 'composer require' execute too long, my last run took 56 sec (for 'symfony/symfony'), is It not too long? For now, it's faster to modify file manually.


stof commented Apr 6, 2013

@vnagara it does not only change the file but alos install the updated dependency (use the --no-update option if you only want to change the file)

vnagara commented Apr 6, 2013

@stof Did you try? About the same (57 seconds)


Seldaek commented Apr 6, 2013

$ time composer require --no-update symfony/symfony
Please provide a version constraint for the symfony/symfony requirement: dev-master
composer.json has been updated

real    0m3.101s

vnagara commented Apr 6, 2013

@Seldaek commands
/ $ mkdir /tmp/b
/ $ cd /tmp/b
/tmp/b $ composer require --no-update
Search for a package []: symfony/symfony

........ <- this time at least 30 sec. At first query reach to 55 sec.


Seldaek commented Apr 6, 2013

I don't think you're running the latest composer. Please run self-update
before reporting issues.

milesj commented Apr 6, 2013

I was under the impression that JSON was chosen simply because YAML is not a default standard library in PHP. Not everyone would be able to use YAML on their hosts, but I don't see a reason why it could not support both.


stof commented Apr 6, 2013

@milesj Because you would then need to support libraries containing any of the yaml or json files (and defining a rule for the case where both are provided), which means twice more calls to the github API to check it.

milesj commented Apr 6, 2013

Ah your right, forgot about that part. Thanks for the info.

vnagara commented Apr 7, 2013

Seems It's real alpha version. Update fixed it (was about 2 weeks old, composer provided no message yet).

Here is another vote for support for comments in composer files.

Problems are caused by Composer not supporting comments - it makes Composer much less useful.

There are real use cases for checked in comments.

  • It makes the code much easier to understand by grouping things together under comment headers.
    • It allows you to communicate to another developer why a specific dependency is there in the file.
    • It makes it easier to provide a note to a developer to uncomment out a specific dependency to enable it for local development in certain cases.
  • It makes it easier to troubleshoot by commenting out just one dependency or another without having to copy out to some separate file the dependencies you are comparing in your project.

It sure would be nice if there were some command line option that could be passed to composer to just have composer strip out comments out of the file - some 'commented' option where Composer would remove the comments before beginning to process the JSON. If composer has this as an option in its library it could then ensure it would work in all scenarios. Composer could even enforce the convention if it really wanted to by enforcing that the input file indicated it was commented in the filename such as composer.json.commented to ensure there would never be a confusion over which files were commented and were not. Any sort of comment approach could be acceptable - /* */ style or double-slash // or # sign comments - any of them could work.

Every other major development language I'm aware of allows comments in their dependency management tools. For example, Maven in the Java world uses XML but since XML supports comments, XML supports all of those comment use cases above and makes the tool much more useful to developers by providing the ability to support comments. This actually makes Maven - even with its XML verbose syntax and Java background - more useful for inter-developer communication as a dependency management tool. RequireJS on the javascript side supports javascript comments that can be stripped.

Yaml which supports comment would also be a good way to go, it would just be nice if composer supported it as a command line option perhaps a 'yaml' option to indicate the format when composer commands are run. Or it could be done by naming convention. If the file ended in .yaml rather than .json, then Composer would use the Yaml version and process it when running commands.

vnagara commented May 28, 2013

I agree with @doliver3.
I think someone will create wrapper that will convert yaml config to json on fly and then transfer arguments to original composer.phar. It's the simplest way for me but I use global composer file so I had not created it yet.

vnagara commented May 28, 2013

"@milesj Because you would then need to support libraries containing any of the yaml or json files (and defining a rule for the case where both are provided), which means twice more calls to the github API to check it."

to @stof you can do supporting local commands to use yaml conf, please? Call API can be solved by adding hook on commit that will convert yaml to json (synchronize) before commit. But local command should be taken from yaml config. Then the same can be done for XML or even PHP arrays configs (I would prefer php arrays). It'll be nice for a lot of peoples.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment