Why My Magento Patch Didn't Apply – and How PhpStorm Was the Culprit

Why My Magento Patch Didn't Apply – and How PhpStorm Was the Culprit

I needed to apply a patch using composer-patches. I created a .diff file, declared it in composer.json, and ran composer install -v.

But the patch wouldn’t apply. Even manually applying it failed:

Hunk #1 FAILED at line XX
1 out of 1 hunk FAILED

The issue? PhpStorm on macOS changed line endings and formatting behind the scenes.

The Problem: PhpStorm

When saving the patch, PhpStorm may:

• Change line endings (\n → \r\n)
• Add a UTF-8 BOM (Byte Order Mark)
• Alter indentation or whitespace

The Fix: Use CLI Tools and Correct Paths

Create the patch from inside the module folder using CLI tools like vim or diff. For example:

cd vendor/vendorname/module-name
cp Setup/InstallData.php Setup/InstallData.php.bak
vim Setup/InstallData.php
diff -u Setup/InstallData.php.bak Setup/InstallData.php > ../../../patches/fix.diff

Then in composer.json:

"extra": {
  "patches": {
    "vendorname/module-name": {
      "Fix": "patches/fix.diff"
    }
  }
}

Final Tips

• Avoid editing patch files in GUI editors
• Use patch -p0 < file.diff to test
• Run file patches/fix.diff to confirm no BOM

CLI tools = reliable patches. GUI editors = hidden landmines.