Composer is how Magento 2 and Adobe Commerce manage code and dependencies. It resolves versions, tracks them in composer.lock so every environment installs identical code, and provides the mechanism for applying patches without ever editing the vendor directory. For patches on a modern Composer-based install, Adobe recommends the Composer approach, using the Quality Patches Tool or composer-patches, and falling back to manual patch files only when a Composer fix is not yet available. Adobe now ships security patches on a monthly cadence, so a disciplined patch and upgrade process is no longer optional.
Dependency management sounds like plumbing, but it is where a lot of Magento stores quietly go wrong: edited vendor files that vanish on the next update, a missing lock file that makes staging and production diverge, or a patch process so painful that security updates get skipped. This guide covers how to run Composer correctly so upgrades are safe and patches stick.
What Composer does for Magento
Composer is the PHP dependency manager Magento is built on. Your composer.json declares which packages your store needs, Magento core, extensions, libraries, and Composer resolves compatible versions of all of them and installs them into the vendor directory. It handles the dependency graph so you do not have to work out by hand which version of one package is compatible with another.
The critical output is the composer.lock file. While composer.json says what you want in loose terms, composer.lock records the exact version of every package that was resolved, down to the commit. That lock file is your reproducibility guarantee: install from the same lock file and every environment, developer laptop, staging, production, gets byte-identical code. Committing composer.lock to version control, and installing from it rather than re-resolving, is the single most important dependency-management habit, because it eliminates the whole class of works-on-staging-not-on-production bugs.
The golden rule: never edit vendor directly
The most damaging Magento mistake is editing files in the vendor directory to fix a bug or change behavior. It works until the next composer install or update, which overwrites vendor with the packaged version and silently erases your change. Now the bug is back, no one remembers the fix, and the change is invisible in version control.
The correct approach is patches. A patch is a recorded diff applied to a package during installation, so your change is reproducible, visible in version control, and survives updates. Composer applies patches automatically as part of install, which means the fix is part of your build rather than a manual step someone has to remember. This discipline, patch instead of edit, is fundamental to sustainable Magento development, and its absence is why some stores are terrifying to update.
The three ways to apply patches
Magento stores deal with three kinds of patches, and each has a preferred mechanism.
| Patch type | Tool | When to use |
|---|---|---|
| Adobe quality and security patches | Quality Patches Tool | Official fixes for known Magento issues |
| Custom or vendor library patches | composer-patches | Your own fixes to a package, applied via composer.json |
| Version-specific manual patches | Manual patch file | Only when no Composer-based fix exists yet |
The Quality Patches Tool is Adobe’s package that manages official quality and security patches through a single command-line interface, letting you list, apply, and revert them cleanly. For your own fixes to a third-party or core package, a composer-patches setup records the patch in composer.json and applies it on install. Manual patch files are the fallback, used only when a Composer-based fix is not yet available for your exact version. Adobe recommends the Composer approach for anything on a modern Composer-based install, and reserving manual patches for the gaps.
Applying Adobe’s monthly security patches
Since Adobe moved to a monthly security-patch cadence, staying current is an ongoing routine rather than a once-a-year scramble. The reliable process:
- Track the release. Watch Adobe’s security bulletins so you know when a patch affects your version.
- Apply on staging first. Use the Quality Patches Tool or the appropriate Composer method to apply the patch in a staging environment.
- Test thoroughly. Run your regression tests and check the areas the patch touches, because even a security patch can interact with customizations.
- Deploy with a locked build. Commit the updated composer.lock and deploy the identical, tested build to production.
- Keep a rollback path. Know how to revert the patch if it causes a problem, which the Quality Patches Tool supports cleanly.
Skipping patches to avoid the testing effort is a false economy: an unpatched Magento store is a known target, and the cost of a breach dwarfs the cost of a monthly patch cycle. The discipline is what keeps the store both current and stable.
Safe upgrades: the lock file is your friend
Upgrading Magento or an extension is where dependency management earns its keep. The safe pattern relies on the lock file and staging:
- Upgrade in a branch, not production. Change the version constraints in composer.json and resolve in a development environment.
- Let Composer resolve conflicts. It will tell you if an extension is incompatible with the target version, which is exactly the information you need before, not after, upgrading.
- Test the resolved build. Deploy the new composer.lock to staging and test fully.
- Promote the exact build. Deploy the same lock file to production, so production runs precisely what you tested.
The alternative, upgrading directly on production and re-resolving there, is how stores end up with a version mismatch between staging and production and a broken site nobody can reproduce. The lock file exists to prevent exactly that.
Production install best practices
How you run Composer in production matters as much as what you install. A few practices separate a stable deployment from a fragile one.
Install, do not update, in production. Run composer install, which reads the committed lock file and installs exactly those versions, rather than composer update, which re-resolves and can pull in changes you never tested. Updating belongs in a development branch, never on a live server. Install production dependencies only, excluding development-only packages, so the production build is lean and does not carry testing tools it should not run. And compile and deploy the built artifact rather than running Composer on the production server mid-request, so a shopper never hits a half-installed state.
Authentication is another common snag. Magento packages require credentials, and those belong in an auth configuration that is kept out of the committed repository, not hardcoded. A deployment that fails on missing credentials during a release window is an avoidable outage. Treat the Composer step as a build-time concern, run it in your pipeline, produce a tested artifact, and deploy that artifact, so production installs are predictable and fast.
Managing extension dependencies and conflicts
Extensions are where dependency management gets tense. Each extension declares its own version requirements, and two extensions can demand incompatible versions of the same underlying library, which Composer will refuse to resolve. That refusal is frustrating in the moment but valuable: it stops you from installing a combination that would break at runtime.
When you hit a conflict, resolve it deliberately rather than forcing it. Check whether a newer version of one extension relaxes the requirement, contact the vendor, or replace the extension that has not kept pace. Forcing incompatible versions with override flags is a trap that produces subtle runtime failures far harder to debug than the original conflict message. Before adding any extension, it is worth checking its dependencies and its support for your Magento and PHP versions, the same vetting you would apply on a Hyva build. A store that curates its extensions and keeps them current has far fewer dependency headaches than one that accumulates abandoned packages, each pinning an old library version and quietly blocking the next upgrade.
Frequently asked questions
Why should I never edit files in the Magento vendor directory?
Because the next composer install or update overwrites vendor with the packaged version and erases your change silently. The bug returns, the fix is lost, and nothing in version control shows what happened. Use a patch instead, which is recorded, visible, and reapplied automatically on every install.
What is the composer.lock file for?
It records the exact resolved version of every package, so installing from it produces byte-identical code in every environment. That reproducibility is why you commit composer.lock to version control and install from it rather than re-resolving, which eliminates works-on-staging-not-on-production differences.
How should I apply Magento security patches?
For a modern Composer-based install, use the Quality Patches Tool for Adobe’s official patches and a composer-patches setup for your own, applying manual patch files only when no Composer fix exists. Apply on staging first, test, then deploy the locked build to production, and keep a rollback path.
How often does Adobe release security patches?
Adobe moved to a monthly security-patch cadence, so staying current is an ongoing routine. Track the bulletins, apply relevant patches to staging, test, and promote a locked build to production each cycle rather than batching many months of patches into one risky update.
What is the safest way to upgrade Magento?
Upgrade in a development branch by changing composer.json constraints and letting Composer resolve, which surfaces extension incompatibilities early. Test the resolved build on staging, then deploy the exact same composer.lock to production so it runs precisely what you tested. Never upgrade and re-resolve directly on production.
Where this fits
Composer is the backbone of a maintainable Magento store: commit the lock file so every environment matches, patch instead of editing vendor so fixes survive updates, apply Adobe’s monthly patches on a real cycle, and upgrade through staging with a locked build. Get these habits right and updates become routine rather than risky, which is the difference between a store you can improve and one you are afraid to touch.
Bemeir is the first US-based Hyva partner and a full Adobe Commerce agency, with a deep technology partner ecosystem across development tooling and hosting. We run disciplined Composer, patching, and upgrade processes on Hyva and Magento builds, and we also work across Shopify, Shopware, and BigCommerce. Read more about Bemeir and how we keep Magento stores maintainable.
External references: a guide to installing Magento 2 security patches, a walkthrough for applying patches with Composer and the command line, and a deep dive on patching vendor libraries with Composer.
