README

This Composer plugin formats (sorts and normalizes) composer.json and other JSON files according to defined rules.

It provides composer format command for formatting and checking files, as well as reusable GitHub Workflows for automated formatting in CI/CD pipelines.

Installation

Install the plugin as a development dependency in your project:

composer require --dev piotrpress/composer-formatter

Usage

composer format [<input>] [--output|-o [OUTPUT]] [--format|-f [FORMAT]] [--check|-c]

Arguments

• input - Path to input JSON file (default: composer.json in current directory).

Options

• --output|-o - Path to output JSON file. If flag provided without value, outputs to STDOUT (default: overwrite input JSON file).
• --format|-f - Path to config JSON file with formatting rules or inline JSON string. Falls back to extra.format section in composer.json or default rules.
• --check|-c - Check if the file is properly formatted without making changes. Exits with code 0 if formatted, 1 otherwise.

Example

• Format composer.json in place:

composer format

• Format a custom JSON file:

composer format path/to/custom.json

• Check if file is properly formatted:

composer format --check

• Print formatted output to STDOUT:

composer format --output

• Write formatted output to a different file:

composer format --output path/to/output.json

• Format file using custom formatting rules:

composer format --format='{"order":{"require": false}}'

Configuration

Formatting rules can be defined via --format|-f option or composer.json under the extra.format key. Format option always takes precedence over JSON key.

Configuration options

• schema - path - Path to JSON schema used for key ordering (default: Composer schema).
• order - array - Custom order (default: empty array).
• breaker - cr,lf,crlf - Line breaker style (default: lf).
• indent.style - space,tab - Indentation style (default: space).
• indent.size - integer - Indentation size (default: 4).

Default configuration

{
    "extra": {
        "format": {
            "schema": "composer-schema.json",
            "order": [],
            "breaker": "lf",
            "indent": {
                "style": "space",
                "size": 4
            }
        }
    }
}

Custom order configuration

The order option accepts an object where each key is a dot-notation path or glob pattern pointing to a section of JSON file, and the value defines the sorting behavior for that section:

• [ "key1", "key2", ... ] - An array of keys that specifies the exact order of keys in that section. Keys not listed will be sorted alphabetically after the specified keys.
• false - Disables sorting for that section, preserving the original order of keys.
• null - Sorts all keys in that section alphabetically.

Wildcard * in the path matches any array index (e.g. authors.* applies rules to every item in the authors array).

Example

{
    "extra": {
        "format": {
            "order": {
              "root": [ "name", "type", "description" ],
              "authors.*": [ "name", "homepage" ],
              "require": false,
              "autoload.classmap": null
            }
        }
    }
}

GitHub Workflows

This plugin also comes with two GitHub Reusable Workflows that can be used to automatically check and fix formatting of JSON files in your project on GitHub:

• format.yml - Automatically formats the file and commits the changes if needed.
• check.yml - Checks if the file is properly formatted and fails if not.

and additionally two ready-to-use workflow files that utilize the above reusable workflows to check and fix formatting of composer.json file in your project:

• composer-format.yml - Automatically formats composer.json file and commits the changes if needed.
• composer-check.yml - Checks if composer.json file is properly formatted and fails if not.

Options for format.yml reusable workflow

• input - Path to input JSON file (default: composer.json in current directory).
• output - Path to JSON file to save formatted content (default: overwrite input file).
• format - Path to JSON file or string with formatting rules (default: use extra.format section in composer.json or default rules if not defined).
• message - Commit message for changes (default: chore: format composer.json).

Custom example usage of format.yml in your workflow

name: Composer format
on:
  push:
    paths:
      - 'composer.json'
  pull_request:
    paths:
      - 'composer.json'
  workflow_dispatch:
jobs:
  format:
    permissions:
      contents: write
    uses: piotrpress/composer-formatter/.github/workflows/format.yml@master
    with:
      input: composer.json
      output: composer.json
      format: '{"order":{"root":["name","description","type"]}}'
      message: 'Format composer.json file'

Options for check.yml reusable workflow

• input - Path to input JSON file (default: composer.json in current directory).
• format - Path to JSON file or string with formatting rules (default: use extra.format section in composer.json or default rules if not defined).

Custom example usage of check.yml in your workflow

name: Composer format check
on:
  push:
    paths:
      - 'composer.json'
  pull_request:
    paths:
      - 'composer.json'
  workflow_dispatch:
jobs:
  check:
    uses: piotrpress/composer-formatter/.github/workflows/check.yml@master
    with:
      input: composer.json
      format: '{"order":{"root":["name","description","type"]}}'

Recommendations

1. Install the plugin as a separate tool in your project:

mkdir -p tools/composer-formatter && \
composer require piotrpress/composer-formatter \
    --working-dir=tools/composer-formatter \
    --no-plugins \
    --no-interaction && \
composer config allow-plugins.piotrpress/composer-formatter true \
    --working-dir=tools/composer-formatter \
    --no-plugins

1. Add a script to project's composer.json file for easy access:

{
    "scripts": {
        "format:fix": "@composer format ../../composer.json --working-dir=tools/composer-formatter",
        "format:check": "@composer format ../../composer.json --working-dir=tools/composer-formatter --check"
    }
}

Requirements

• PHP >= 8.2
• Composer ^2.0

License

MIT