Are you writing script definitions in Composer?

When we join a project, we often face a lack of documentation. It could be the default Laravel README, or one that's been customized but is now out of date.

In addition, one thing we rarely see is documentation of what the various scripts in composer.json do.

Thankfully, Composer makes this documentation very easy to write. There is a built-in scripts-definition configuration key that lets you provide a brief description for each of the scripts that are defined. You can read these definitions by running composer list at the command line.

Sometimes it can seem super obvious as to what a script does, like composer run test, but it's still useful to document. There can be also be subtle things to know, even if the command seems straightforward. For example, we use PHP CS Fixer, but we don't like the default action to fix mistakes, only to report them. So our description for phpcs will explain that, and even mention the alternate phpcs-fix script if you do want auto-fixing.

Check out your composer.json and make a future developer happy by adding a scripts-definition block with one line for everything in your scripts block.

Here to help,

Joel

P.S. Could your Laravel project use better documentation? Book a free call with us to see how we can get you started.