Tidy Up composer.json with Composer Normalize

By Greg Nowak. Updated 6 August 2026.

A tidy composer.json will not fix weak dependency decisions. It will, however, make those decisions much easier to see. When formatting, key order and package lists vary from one edit to the next, a simple dependency update can produce a surprisingly noisy pull request.

For business owners and operations leads, that noise means slower reviews and less confidence in routine maintenance. For developers and agencies, it creates merge conflicts, inconsistent handovers and repeated discussions about formatting. The practical answer is to combine Composer’s own validation and sorting features with ergebnis/composer-normalize.

What each Composer tool actually does

These tools complement one another. Package sorting keeps future additions orderly, validation detects metadata and lock-file problems, and Composer Normalize applies consistent structure to the complete file.

Install Composer Normalize safely

For most applications and agency-maintained projects, install the normalizer as a development dependency. Composer plugins can execute code during Composer operations, so trust should be recorded explicitly through allow-plugins, reviewed like any other dependency and committed with the project configuration.

composer require --dev ergebnis/composer-normalize
composer config allow-plugins.ergebnis/composer-normalize true
composer normalize
composer validate --strict

The first command installs the plugin. The second allows that specific plugin instead of relying on an interactive prompt or a permissive wildcard. The final two commands normalize the file and then check its validity.

Review the proposed dependency and its source before allowing it. In an unattended build, Composer may otherwise reject an unlisted plugin rather than waiting for someone to answer a prompt. That is a useful security boundary, not an inconvenience to disable globally.

Enable package sorting for everyday work

Composer can sort package names whenever its require command changes the file. Enable that behavior in the shared project configuration:

{
  "config": {
    "sort-packages": true,
    "allow-plugins": {
      "ergebnis/composer-normalize": true
    }
  }
}

This reduces future churn, but it does not normalize the whole document. It will not impose a consistent top-level key order or clean up every manually edited section. That broader job belongs to Composer Normalize.

Enforce the result in CI

Once the initial cleanup is committed, add two non-interactive checks to the pipeline:

composer normalize --dry-run
composer validate --strict

The dry run should report the required changes and fail the job; it should not rewrite files inside CI. A developer can run composer normalize locally, review the diff and commit the result. This keeps repository changes intentional and avoids generated modifications disappearing with an ephemeral build environment.

Strict validation is useful because Composer’s normal validation can finish successfully when it finds only publishability warnings. With --strict, warnings also produce a non-zero status, which makes the command suitable for an enforced pipeline rule. For private applications, decide whether every publishability warning is relevant before making the check mandatory.

Treat composer.lock deliberately

If an application commits composer.lock, the file should remain consistent with composer.json. Composer Normalize can check that relationship and update the lock-file content hash after normalization. Review and commit that change with the normalized manifest.

The plugin also provides --no-update-lock and --no-check-lock. These are exceptions, not safer defaults. Use them only when another defined step owns lock-file validation or when a particular workflow must avoid modifying the lock file. Otherwise, suppressing both the update and the check can hide drift until installation or release.

Use the cleanup to review dependency policy

Normalization handles structure, not judgment. Once the file is easier to read, inspect the decisions that affect production:

• Keep test runners, static-analysis tools and other development-only packages in require-dev.
• Check PHP and extension constraints against the real production environment.
• Remove packages left behind by retired features or integrations.
• Prefer PSR-4 autoloading for new namespaced code where appropriate.
• Review scripts and custom repositories whose purpose or owner is unclear.
• Investigate platform overrides that make local dependency resolution differ from production.
• Avoid a manually maintained version field when Composer can infer releases from version-control tags.

A formatter cannot tell you whether a constraint is too broad, an abandoned package should be replaced or a post-install script still belongs in the delivery process. Those are maintenance and ownership decisions.

Roll it out without obscuring functional changes

Normalize an established project in a dedicated pull request. Do not combine the first large formatting diff with package upgrades, changed PHP constraints or new scripts. Review and approve the mechanical baseline once; later dependency pull requests should then show only meaningful decisions.

Agencies can carry the same rule into repository templates, CI definitions and handover checklists. For a portfolio of PHP sites, that small standard makes inherited projects easier to assess and reduces review work whenever responsibility moves between people.

If dependency hygiene, pipeline rules and technical handovers keep falling between teams, Greg can help turn them into a maintainable delivery workflow.

Related on GrN.dk

• JavaScript-Heavy Service Pages Still Lose Leads: What to Audit in 2026
• When AI writes JSON, one bad field can break the workflow
• Debugging PHP: A Practical Workflow for Faster Fixes

Need help with this kind of work?

Discuss your PHP delivery workflow Get in touch with Greg.

Sources

• Composer command-line interface: validate
• Composer configuration: sort-packages and allow-plugins
• Composer schema
• ergebnis/composer-normalize