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.

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 http://stackoverflow.com/a/2464744 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.

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 knpbundles.com 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.

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. =(

If you really want to use YAML, feel free to use this tool which will convert a composer.yml file to composer.json: https://github.com/igorw/composer-yaml

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?

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.

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

Please discuss this on the composer-yaml repo.

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").

• http://stackoverflow.com/questions/244777/can-i-comment-a-json-file
• http://blog.getify.com/json-comments/

Some non-standard implementations of JSON extend the grammar to include Javascript's /.../ comments.

https://en.wikipedia.org/wiki/Yaml (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?

edit:
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 https://github.com/olegstepura/convert-config
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

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 =)

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).

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.

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 https://github.com/igorw/composer-yaml.

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
autoload:
    psr-0:
        '': src/

authors:
  - name:       David
    email:      [email protected]
    homepage:   'http://web-emerge.com'

  - name:       Julian
    email:      [email protected]
    homepage:   'http://consistency.at'

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

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

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

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

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

  - type: package
    package:
        name:       jehu/fire-php-bundle
        version:    dev-master
        source:     { url: 'https://github.com/Jehu/FirePHPBundle.git', type: git, reference: origin/master }

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

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

  - type: package
    package:
        name:       yuicompressor/yuicompressor
        version:    2.4.7
        dist :      { url: 'http://yui.zenfs.com/releases/yuicompressor/yuicompressor-2.4.7.zip', type: zip }

require:
    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

scripts:
    post-install-cmd:
        - 'Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::buildBootstrap'
        - 'Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::clearCache'
        - 'Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::installAssets'
    post-update-cmd:
        - 'Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::buildBootstrap'
        - 'Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::clearCache'
        - 'Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::installAssets'
config:
    bin-dir: bin

extra:
    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:

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

This way a list looks better

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:
http://drupalcode.org/project/drush_make.git/blob_plain/refs/heads/6.x-2.x:/EXAMPLE.make

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 :)

@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.

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 :)

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 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.

https://gist.github.com/vnagara/5327086

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

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.

@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.

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

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.

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.

quote:
"@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.

@vnagara see https://github.com/igorw/composer-yaml

An another implementation as composer plugin https://github.com/webuni/composer-yaml-plugin

A slightly different approach: https://github.com/sandfoxme/composer-yaml
A wrapper command that allows composer to use yaml config directly instead of explicit conversion

another one. a fork of gorw/composer-yaml with example scripts for composer, yarn and box. i am using yaml over json many times.

Something that should have mentioned here is that Composer is not just reading composer.json file but also writing in it, for instance in composer require command. The symfony/yaml component does not support comments yet (symfony/symfony#22516).

I was one of the ones calling for this. Since then we have decided to give up and just embrace JSON. So no remaining interest in YAML from me.

So far there is no Composer plugin that allows seamlessly replace composer.json with composer.yml. All above mentioned solutions offer a way to convert the file manually which is kind of tedious. If Composer team strongly against Yaml format it would be nice to have an abstraction over the process of reading and writing data. So that third party plugins could provide an implementation for other configuration formats (yml, xml, neon, etc).

Nowadays PHP projects tend to have a complex composer.json file with lots of dependencies and configuration options so the need of annotations has became increasingly critical.

I didn't see it mentioned but _comment has been supported for many years as an "official workaround".

I'm using this and TBH, in practice I found this sufficient and all one needs.

Sure, "true inline" comments sound nice on paper.

But I honor and actually to prefer the stance of the project: do one thing, do it good. As in: use one format, use it well.

The arguments about pluggable engines for these file formats are laudable but IMHO it's also a narrow view: whilst using composers PHP API to access the data I imagine the actual format wouldn't matter, however there are enough tools in eco system directly building on the file format.

This would fragment these cases and, the way I see it, tools directly building one the file format slowly or not at all.

I'm glad the project leader have a vision with a strong focus and I support this. The project has better areas where developer muscle is needed and I'm glad they're not getting distracted.

I didn't see it mentioned but _comment has been supported for many years as an "official workaround".

_comment is only supported on the top level of JSON structure. Composer will fail if you try to put a note inside require section.

The project has better areas where developer muscle is needed and I'm glad they're not getting distracted.

That's just a personal preference. Isn't it? For many people this issue is the most critical one ever.

Every person's time is limited. So maintainers need to decide which features are worth to maintain and which are not. The Composer developers decided that being able to use different formats to configure your dependencies is not one of their priorities. IMO it's time to accept that and if that's really a critical missing feature for you, find other solutions around it.

For many people this issue is the most critical one ever.

That's just a personal preference. Isn't it?

@chr-hertel, of course it is. People may use Composer in different ways and that's why "better areas" vary for them. While for someone this feature is critical for others it makes no sense. The issue was closed almost 8 years ago and a lot has changed since than. People are free to put more arguments in favor of this and project maintainers are free to decline this once again as well. That's I think the right way to keep good communication in any open source project.

I don't see any linked pull requests on this issue. If this is really important for folks, create one. If the code is there (say adding support for YAML as well as JSON), the maintainers would be much more likely to merge it. If you're not interested in doing the work, or paying someone else to do it, please stop complaining.

Please don't send a pull request, and please everyone stop wasting everyone else's time here.
…

Maybe stop wasting developers' time by forcing us to do obnoxious workarounds for comments? After umpteen years, one would think you all would get that this is something we actually need? The current JSON format is not sufficient or we wouldn't keep bringing this up. Period. Just because you never comment your code or have to temporarily comment out a line but keep it for future use, etc...

Two years later the latest complaint and 10 from the initial request, and here I am, managing and updating a mono-repo of sorts, with 78 dependencies. Those vary from major requirements, third-party packages, optional peer-dependencies, and stuff used in a dark corner or two. Comments are VERY needed for any organized codebase, and a dependency file is not different. On the big task of bringing most forgotten dependencies to their current versions, I'm having to do a lot of digging, because there's not a single hint on which one is used for what.
YAML would do wonders here, as would any sort of official support for comments - e.g. allowing _comment keys in any place of the JSON file.

That said, as a summary of the hundred replies above, there's no way Composer would support a second format (be it officially or via pluggable converters), simply because lots of tools out there expect a single JSON file and that must be readable according to normal JSON and according to expected dependency repositories - that's why a _comment key breaks in the require section.
It's impossible to have another file, another file format, or a different syntax without breaking the rest of the environment. Allowing you to get rid of a JSON file in place of an auto-converted YAML would break the Composer ecosystem.
And then, converters are just that - you must always keep your composer.json around, and they must go both ways, since there are composer commands that write to composer.json, besides our manual changes.

This is a decision that should've been taken 10 years ago, when this issue was first raised - and possibly even earlier than that, on the Composer inception. It wasn't, and thus it definitely won't happen now - no matter what's the community need for organizing their dependencies.
Be glad that Composer isn't like NPM which also rewrites your file, removing all blank likes you left. It could be worse.

I wonder if there's some very dirty solution for, say, Composer 3 (lol) which could allow this without breaking BC. I can't see any, and I guess Seldaek can't either, given his insistence on refusing this idea for so long. Notice he never locked the issue and neither ignored it.

The only idea I can see is a replacement tool that "wraps up" Composer and yet, lives side by side. But that's definitely too much trouble just to have a somewhat cleaner syntax and comments. No wonder why the best solutions so far are manual converters - it's not worth the hassle, different from what Yarn was with NPM for some time.