PHPackages                             piotrpress/composer-formatter - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. piotrpress/composer-formatter

ActiveComposer-plugin[Validation & Sanitization](/categories/validation)

piotrpress/composer-formatter
=============================

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

v1.0.3(3mo ago)024↓88.6%MITPHPPHP >=8.2

Since Apr 2Pushed 3mo agoCompare

[ Source](https://github.com/PiotrPress/composer-formatter)[ Packagist](https://packagist.org/packages/piotrpress/composer-formatter)[ Docs](https://github.com/PiotrPress/composer-formatter)[ RSS](/packages/piotrpress-composer-formatter/feed)WikiDiscussions master Synced 4w ago

READMEChangelogDependencies (1)Versions (5)Used By (0)

Composer Formatter
==================

[](#composer-formatter)

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

[](#installation)

Install the plugin as a development dependency in your project:

```
composer require --dev piotrpress/composer-formatter
```

Usage
-----

[](#usage)

```
composer format [] [--output|-o [OUTPUT]] [--format|-f [FORMAT]] [--check|-c]
```

### Arguments

[](#arguments)

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

### Options

[](#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

[](#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
-------------

[](#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

[](#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

[](#default-configuration)

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

### Custom order configuration

[](#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

[](#example-1)

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

GitHub Workflows
----------------

[](#github-workflows)

This plugin also comes with two [GitHub Reusable Workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows) that can be used to automatically check and fix formatting of JSON files in your project on GitHub:

- [format.yml](.github/workflows/format.yml) - Automatically formats the file and commits the changes if needed.
- [check.yml](.github/workflows/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](.github/workflows/composer-format.yml) - Automatically formats `composer.json` file and commits the changes if needed.
- [composer-check.yml](.github/workflows/composer-check.yml) - Checks if `composer.json` file is properly formatted and fails if not.

### Options for `format.yml` reusable workflow

[](#options-for-formatyml-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

[](#custom-example-usage-of-formatyml-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

[](#options-for-checkyml-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

[](#custom-example-usage-of-checkyml-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
---------------

[](#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
```

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

[](#requirements)

- PHP `>= 8.2`
- Composer `^2.0`

License
-------

[](#license)

[MIT](license.txt)

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance82

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

4

Last Release

91d ago

PHP version history (2 changes)v1.0.0PHP >=8.1

v1.0.1PHP >=8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/10326736?v=4)[Piotr Niewiadomski](/maintainers/PiotrPress)[@PiotrPress](https://github.com/PiotrPress)

---

Top Contributors

[![PiotrPress](https://avatars.githubusercontent.com/u/10326736?v=4)](https://github.com/PiotrPress "PiotrPress (4 commits)")

---

Tags

jsonformatterplugincomposernormalizestylenewlineformatlinterrulescommandspacesindentordertabslinebreakscrlfcrlf

### Embed Badge

![Health badge](/badges/piotrpress-composer-formatter/health.svg)

```
[![Health](https://phpackages.com/badges/piotrpress-composer-formatter/health.svg)](https://phpackages.com/packages/piotrpress-composer-formatter)
```

###  Alternatives

[seld/jsonlint

JSON Linter

1.3k228.7M269](/packages/seld-jsonlint)[ergebnis/composer-normalize

Provides a composer plugin for normalizing composer.json.

1.1k40.0M2.8k](/packages/ergebnis-composer-normalize)[dragon-code/codestyler

A tool to automatically fix Coding Style Standards issues by The Dragon Code.

291.9M26](/packages/dragon-code-codestyler)[automattic/jetpack-autoloader

Creates a custom autoloader for a plugin or theme.

576.1M119](/packages/automattic-jetpack-autoloader)[leroy-merlin-br/coding-standard

The coding standard for PHP projects on LMBR

2138.8k17](/packages/leroy-merlin-br-coding-standard)[ellisio/laravel-phone

A phone validator for Laravel using the free Twilio phone lookup service.

1130.0k](/packages/ellisio-laravel-phone)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)