Fix PHP Composer Dependency Conflict

What's Actually Happening

Composer fails to resolve package dependencies. Different packages require incompatible versions of the same dependency.

The Error You'll See

```bash $ composer install

Problem 1 - PackageA v2.0 requires packageC ^3.0 - PackageB v1.5 requires packageC ^2.0 - packageC is locked to version 3.0.0 and cannot be updated ```

Version conflict:

```bash $ composer update

Your requirements could not be resolved to an installable set of packages. Problem 1 - Root composer.json requires packageX ^1.0 - packageX ^1.0 requires packageY ^2.0 - You have packageY 1.5.0 which does not match ```

Lock file conflict:

```bash $ composer install

Warning: The lock file is not up to date with the latest changes in composer.json ```

Why This Happens

1. 1.Version constraint mismatch - Packages require different major versions
2. 2.Outdated lock file - composer.lock doesn't match composer.json
3. 3.Minimum stability - Stability requirements conflict
4. 4.Platform requirements - PHP version or extensions missing
5. 5.Circular dependency - Package depends on itself
6. 6.Repository issues - Package not found or wrong repository

Step 1: Check Dependency Tree

```bash # Show dependency tree: composer show --tree

# Show dependencies of specific package: composer show package/name --tree

# Show why package is installed: composer why package/name

# Show all installed packages: composer show

# Check package details: composer show package/name

# Show dependencies only: composer depends package/name

# List outdated packages: composer outdated

# Check for security issues: composer audit ```

Step 2: Update Lock File

```bash # Update lock file to match composer.json: composer update --lock

# Full update: composer update

# Update specific package: composer update package/name

# Update with no scripts: composer update --no-scripts

# Dry run update: composer update --dry-run

# Check what would be updated: composer outdated --direct

# If lock file corrupt: rm composer.lock composer install ```

Step 3: Analyze Version Conflicts

```bash # Understand version constraints: # ^1.2.3 = >=1.2.3 <2.0.0 # ~1.2.3 = >=1.2.3 <1.3.0 # 1.2.* = 1.2.0 to 1.2.x # >=1.0 <2.0 = range

# Check what versions are available: composer show package/name --all

# Check version requirements: composer why-not package/name ^2.0

# Show available versions: composer show package/name --available

# Find compatible version: composer require package/name:^2.0 --dry-run

# Use specific version: composer require package/name:2.0.0 ```

Step 4: Resolve Version Conflicts

```bash # Option 1: Use alias for different versions: # In composer.json: { "require": { "package/a": "^2.0", "package/b": "^1.0", "internal/package-c": "3.0.0 as 2.0.0" } }

# Option 2: Update one package: composer update package/name --with-all-dependencies

# Option 3: Allow specific version: composer require package/name:^3.0 --no-update composer update package/name --with-dependencies

# Option 4: Fork and fix: # If no resolution, fork conflicting package and update dependencies

# Option 5: Use replace: { "replace": { "package/conflicting": "1.0.0" } } ```

Step 5: Check Platform Requirements

```bash # Check PHP version requirement: composer check-platform-reqs

# Output shows: # ext-json 8.2.0 success # ext-pdo 8.2.0 success # php 8.2.0 success

# Check PHP version: php -v

# Check loaded extensions: php -m

# Check required extensions: composer show --platform

# Install missing extension: # On Ubuntu: sudo apt install php8.2-pdo sudo apt install php8.2-mbstring

# On Windows, enable in php.ini: extension=pdo extension=mbstring

# Ignore platform requirements (not recommended): composer install --ignore-platform-reqs ```

Step 6: Fix Stability Issues

```bash # Check minimum stability: # In composer.json: { "minimum-stability": "stable", "prefer-stable": true }

# Change stability to allow dev packages: { "minimum-stability": "dev", "prefer-stable": true }

# Or allow specific dev package: composer require package/name:dev-main

# Force dev stability for one package: { "require": { "package/name": "dev-main as 1.0.0" } }

# Check stability requirements: composer show package/name | grep stability ```

Step 7: Clear Composer Cache

```bash # Clear cache: composer clear-cache

# Or: rm -rf ~/.composer/cache

# Clear global cache: rm -rf ~/.cache/composer

# Clear vendor and reinstall: rm -rf vendor composer.lock composer install

# Diagnose issues: composer diagnose

# Output: # Checking composer.json: OK # Checking composer.lock: OK # Checking platform settings: OK # Checking git settings: OK ```

Step 8: Use Private Repositories

```bash # Add private repository: # In composer.json: { "repositories": [ { "type": "vcs", "url": "https://github.com/company/private-package" }, { "type": "path", "url": "../local-package" }, { "type": "composer", "url": "https://repo.example.com" } ] }

# Or add via CLI: composer config repositories.private vcs https://github.com/company/private-package

# Authenticate private repository: composer config --global --auth http-basic.repo.example.com username password

# Or use token: composer config --global --auth bearer.token repo.example.com token

# Check configured repositories: composer config --list | grep repositories ```

Step 9: Handle Circular Dependencies

```bash # Error: Circular dependency detected

# Example: A requires B, B requires A

# Fix option 1: Refactor packages to remove circular dependency

# Fix option 2: Use require-dev: # In package A: { "require-dev": { "package/b": "^1.0" } }

# Fix option 3: Use suggest: { "suggest": { "package/b": "Required for feature X" } }

# Fix option 4: Split packages # Create package C with shared functionality # A and B both require C ```

Step 10: Composer Verification Script

```bash # Create verification script: cat << 'EOF' > /usr/local/bin/check-composer.sh #!/bin/bash

echo "=== Composer Version ===" composer --version

echo "" echo "=== PHP Version ===" php -v | head -1

echo "" echo "=== Check composer.json ===" composer validate --strict 2>&1

echo "" echo "=== Platform Requirements ===" composer check-platform-reqs 2>&1

echo "" echo "=== Installed Packages (direct) ===" composer show --direct 2>&1 | head -30

echo "" echo "=== Outdated Packages ===" composer outdated --direct 2>&1 | head -20

echo "" echo "=== Security Audit ===" composer audit 2>&1 | head -20

echo "" echo "=== Dependency Issues ===" composer install --dry-run 2>&1 | grep -A5 "Problem" | head -30

echo "" echo "=== Cache Status ===" composer diagnose 2>&1 | grep -E "cache|composer" EOF

chmod +x /usr/local/bin/check-composer.sh

# Usage: /usr/local/bin/check-composer.sh

# Quick fix: alias composer-fresh='rm -rf vendor composer.lock && composer install' ```

Composer Dependency Checklist

Verify the Fix

```bash # After fixing dependency conflict

# 1. Validate composer.json composer validate // composer.json is valid

# 2. Check install composer install --dry-run // No conflicts

# 3. Run install composer install // Lock file written

# 4. Check dependencies composer show // All packages installed

# 5. Test application php artisan test # Or php vendor/bin/phpunit // Tests pass

# 6. Check outdated composer outdated // Up to date ```

Related Issues

• [Fix PHP Application Error](/articles/fix-php-application-error)
• [Fix NPM Dependency Conflict](/articles/fix-npm-dependency-conflict)
• [Fix Python ImportError](/articles/fix-python-import-error)