Caring For Your Composer.json

The PHP landscape was changed forever with the release of the Composer package manager. Composer brought order and process to the ecosystem, and now it is a vital tool for any PHP application.

However, I feel that people take their Composer setup for granted (mostly because it’s so damn easy to use!), and I wanted to share some ways in which you can give it some love.

Composer Normalize

Composer Normalize is a Composer plugin that enforces a structure on your composer.json file. This means that you can automate the formatting of the file, in the same way you apply coding standards to your PHP code.

Once installed, all you have to do is run it once, and commit the result to Git.

composer normalize

This will put all the sections in a predefined order, fix indentation issues and more. Once this is done, you can add it to your CI build so that all future contributions that modify the composer.json file have to keep it formatted as per the normalization.

This means everything is standardised, and you can immediately see exactly what changed (e.g. a new dependency was added) in your Git history, without having any other changes in the file (such as different indentation etc).

It’s dead simple, and it just works.

Composer Unused

Composer Unused is a tool that scans your application for the use of each package in your composer.json, and reports on any packages that are installed but not actually used in your application.

This is of great benefit, as it’s very easy to lose track of what your application is actually using. Perhaps a legacy feature was removed some time ago, but the dependencies are still being needlessly installed, bloating your application, slowing down your CI, taking up server CPU and memory, not to mention the environmental impact of repeatedly downloading redundant packages.

Once installed, simply run the binary and get the report on any packages your app installs but does not use.

vendor/bin/composer-unused

All you need to do is remove the unused packages, run your test suite and boom, your app is a little more streamlined and efficient!

Composer Require Checker

Composer Require Checker is kind of the opposite of the Composer Unused tool. Instead of looking for unused dependencies, it scans your application code and finds packages that are in use, but that are not explicitly defined in your composer.json.

Imagine you use a feature of a package A in your application, but that package A is only installed as a dependency of some other package B that your application uses. If in the future package B is removed, say because it powered a legacy feature that has been removed, suddenly your app will be in need of package A but it will no longer be present.

The Composer Require Checker reports on these usages, and allows you to explicitly add every package dependency to your composer.json so that even if package A is removed, your composer.json will still require package B and your application will not break.

This does mean your composer.json lists every single package that your app uses, which might look a bit scary at first. However, it does not change in any way the set of packages that are actually installed, and being explicit about what the application actually needs is a way safer manner to operate in.

Adding Documentation

One final tip, that is not a tool but more a recommendation. Normally you cannot add comments to a json file - comments are not at all supported by the JSON specification.

In the composer.json you often make small changes such as pinning a specific version of a package, or using a fork with some changes you want to test. These changes can of course be documented in the Git commit messages, but this does not provide any hints on when these fixes can be reverted, or provide a list of all the “exceptional” settings in the composer.json file.

Various solutions have been proposed over the years, such as pre-processing the file, but I find they are all overkill for such a simple need. What I like to do is create a comments section inside the JSON document, and in here you can provide notes about any specific settings you have made to individual packages.

To do this, add a _comment section to the JSON - something like this:

{  
    "name": "benr77/my-project",  
    "license": "proprietary",  
    "type": "project",  
    "_comment": [  
        "ddeboer/data-import-bundle - use my fork to enable Symfony 5 support",  
        "backup-manager/backup-manager - use my fork to enable PHP 8 support"  
    ],  
    "require": {  
        "php": "8.1.*",  
        "ext-ctype": "*",  
        "ext-gd": "*",
    ...

This _comment section then provides an exhaustive list of specific tweaks and overrides in the file, and provides information about how and when these overrides can be removed.

A simple solution that just works.

I hope you enjoyed these suggestions, and will think about paying a little more attention to your composer.json in future. If you have any other suggestions please do leave a comment as I’m keen to hear them.