Resolving Composer Dependency Conflicts: A Step‑by‑Step Diagnostic Guide

Recognizable Condition

When you run composer update or composer require Composer aborts with:

Your requirements could not be resolved to an installable set of packages.
Conflict: ...

The conflict list shows the packages, the requested versions, and the derived constraints that cannot be satisfied.

Common Root Causes

Cause	Typical Symptom
Direct version conflict	Two packages require incompatible versions of a shared dependency.
Platform requirement mismatch	Package requires a PHP extension or version not present in the runtime or config.platform.
Replace/Provide confusion	A package replaces another but the constraint chain still pulls the replaced package.
Stability restrictions	Global minimum-stability or prefer-stable settings block needed dev versions.
Repository priority	Private repo metadata lags behind Packagist, causing missing tags.

Ordered Diagnostic Checks

1. Run composer why-not <package> <version> to see the exact constraint chain that fails.

2. Verify platform packages: composer show --platform lists the PHP version and extensions Composer sees.

3. Inspect composer.lock for pinned versions that may be forcing a conflict.

4. Check the replace and provide sections of the conflicting packages’ composer.json (use composer show -t <package>).

5. Test a relaxed stability: temporarily set minimum-stability: dev and prefer-stable: false in the root composer.json to see if the conflict disappears.

6. Clear Composer’s cache and rerun with verbose output: composer clear-cache && composer update -vvv. Search the output for the word "Conflict" to pinpoint the decision point.

Targeted Fixes

1. Direct Version Conflict

• Widen the version constraint in your composer.json (e.g., change ^1.2 to ~1.2.0).
• If the conflict is in a transitive dependency, fork the package and adjust its composer.json, then reference the fork via a VCS or path repository.

2. Platform Requirement Mismatch

• Install the missing PHP extension on the target machine.
• Or override the platform requirement in composer.json:

  "config": {
      "platform": {
          "php": "8.3.0",
          "ext-swoole": "5.0.0"
      }
  }

• Remember that config.platform only affects the resolver; the runtime must still provide the extension.

3. Replace/Provide Confusion

• Add a conflict entry to your root composer.json to suppress the replaced package:

  "conflict": {
      "vendor/old-package": "*"
  }

• Alternatively, add a replace entry to your root to explicitly replace the problematic package.

4. Stability Restrictions

• Prefer per‑package stability flags: "vendor/package": "@dev" instead of global minimum-stability changes.
• Only relax minimum-stability temporarily for a targeted update (e.g., composer update vendor/package --with-dependencies).

5. Repository Priority

• Run composer show --all --available <package> to verify the latest tags in the private repo.
• If the private repo is out of sync, bump the version or push the missing tag.
• As a last resort, remove the private repo entry and force a fresh install from Packagist, then re‑add the private repo with --no-cache.

Escalation Criteria

If the resolver trace shows a cycle involving packages you do not control and none of the above fixes resolve the conflict, file an issue against the upstream maintainer. Attach the full composer why-not output and the composer show -t dependency tree. Provide a minimal composer.json that reproduces the error if possible.

Practical Engineering Decisions

• Use explicit version constraints (e.g., ^1.2 or 1.2.*) instead of exact versions to allow safe upgrades.
• Run composer validate --strict in CI to catch schema or constraint errors early.
• Commit composer.lock to the repository to ensure reproducible installs.
• Schedule composer outdated --direct --strict weekly to detect drifting constraints before they break the resolver.
• In CI environments, use composer install --no-dev --dry-run after any change to verify resolution without side effects.
• Verify that the composer.lock hash matches across environments by running git diff composer.lock or using a checksum tool.

Checking Your Fix

1. Run composer update --lock to generate a new lock file.
2. Execute composer validate --strict --no-check-all to ensure the JSON is still valid.
3. Use composer why <conflicting-package> to confirm the conflict chain no longer appears.
4. If composer install --dry-run succeeds, merge the changes into your main branch.