# ampersand/magento2-upgrade-patch-helper > A script to help identify local overrides and preferences which need to be reviewed when upgrading magento2 `composer require ampersand/magento2-upgrade-patch-helper` Canonical URL: https://packagento.com/ampersand/magento2-upgrade-patch-helper ## At a glance - **Vendor**: ampersand (https://packagento.com/ampersand.md) - **Latest version**: v1.19.5 — released 2024-11-11 - **Pricing**: Free - **Package type**: Magento 2 module - **Status**: active, accepting new buyers ## Installation Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them. 1. **Sign in or create an account** at https://packagento.com/customer/account/. 2. **Add the package to your account.** Open https://packagento.com/ampersand/magento2-upgrade-patch-helper and complete the free checkout. A licence is minted automatically. 3. **Create or pick a project, then activate the licence on it.** - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/. - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project. 4. **Add the project credentials to your Magento codebase.** Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`: ```json { "http-basic": { "packagento.com": { "username": "ppk_live_...", "password": "psk_live_..." } } } ``` Add the Packagento Composer repository to `composer.json`: ```json { "repositories": [ { "type": "composer", "url": "https://packagento.com" } ] } ``` 5. **Install and apply.** ```bash composer require ampersand/magento2-upgrade-patch-helper:* bin/magento setup:upgrade bin/magento setup:di:compile bin/magento cache:flush ``` ## What it does A script to help identify local overrides and preferences which need to be reviewed when upgrading magento2 ## README Helper scripts to aid upgrading magento 2 websites, or when upgrading a magento module [![Build Status](https://travis-ci.org/AmpersandHQ/ampersand-magento2-upgrade-patch-helper.svg?branch=master)](https://app.travis-ci.com/github/AmpersandHQ/ampersand-magento2-upgrade-patch-helper) This tool looks for files which have been modified as part of an upgrade and highlights any overrides for those specific files in your magento instance. This allows you to focus in on only the things that have changed, and gives you an actionable list of things to review specifically for your site. This tool does a number of checks split into three categories - `WARN` - Warning level items are something that you should review and often require direct code changes. Something you or a third party have customised may need adjustment or no longer be valid based on the upgraded codebase. - `INFO` - Information level items are something that you may want to know, but there is not always direct action necessary. These items are hidden by default and exposed with `--show-info`. - `IGNR` - Ignore level items are something that you can ignore. The vendor file change which triggered the analysis was actually a comment/whitespace or other non functional change so there is nothing to check. These items are hidden by default and exposed with `--show-ignore`. This tool checks for the following - Preferences (in global/frontend/adminhtml di.xml) - Overrides - phtml / js - layout xml - html (knockout templates) - Plugins for methods which have been affected by the upgrade. - Queue consumers which were added or removed - Declarative schema - db_schema.xml table additions/removals/changes - Setup Patch Data patches - Setup Schema Data patches - Setup Scripts For a detailed breakdown of each check, an example, and the recommended actions please see [docs/CHECKS_AVAILABLE.md](./docs/CHECKS_AVAILABLE.md) If you have any improvements please raise a PR or an Issue. ### Supplementary tooling - Gui https://github.com/elgentos/magento2-upgrade-gui - Github action https://github.com/convenient/magento2-upgrade-patch-helper-github-action ### How to use All the below should be used on a local setup, never do any of this anywhere near a production website. It is most reliable if you use this when the instance has been built and is plugged into a database just in case you have theme configuration stored there. Running this without it being plugged into a database could cause some of the theme analysis to be missed. #### Step 1 - Composer update the dependencies then generate a patch In your project `composer install` and move the original vendor directory to a backup location ``` cd /path/to/magento2/ composer install mv vendor/ vendor_orig/ ``` Update your magento version (or third party module) to the one required, with b2b or other extensions if applicable. ```bash composer install composer require magento/product-enterprise-edition 2.2.6 --no-update composer require magento/extension-b2b 1.0.6 --no-update composer require thirdparty/some-module "^2.0" composer update magento/extension-b2b magento/product-enterprise-edition thirdparty/some-module --with-dependencies ``` At this point you may receive errors of incompatible modules, often they are tied to a specific version of magento. Correct the module dependencies and composer require the updated version until you can run `composer install` successfully. Once you have a completed the composer steps you can create a diff which can be analysed. ```bash diff -ur -N vendor_orig/ vendor/ > vendor.patch ``` By generating the diff in this manner (as opposed to using `wget https://github.com/magento/magento2/compare/2.1.15...2.1.16.diff`) we can guarantee that all enterprise and magento extensions are also covered in one patch file. #### Step 2 - Parse the patch file In a clone of this repository you can analyse the project and patch file. ```php git clone https://github.com/AmpersandHQ/ampersand-magento2-upgrade-patch-helper cd ampersand-magento2-upgrade-patch-helper composer install php bin/patch-helper.php analyse /path/to/magento2/ ``` This will output a grid of files that need to be reviewed and possibly updated to match the changes defined in the newly generated `vendor_files_to_check.patch`. For those of you who would prefer to work over these results in a GUI rather than a CLI you may want to check out [elgentos/magento2-upgrade-gui](https://github.com/elgentos/magento2-upgrade-gui) _(README truncated for .md surface. Full README on https://packagento.com/ampersand/magento2-upgrade-patch-helper.)_ ## Recent Versions | Version | Released | |---|---| | v1.19.5 | 2024-11-11 | | v1.19.4 | 2024-11-06 | | v1.19.3 | 2024-06-05 | | v1.19.2 | 2024-04-11 | | v1.19.1 | 2024-02-09 | | v1.19.0 | 2023-11-09 | | v1.18.1 | 2023-10-06 | | v1.18.0 | 2023-08-04 | | v1.17.4 | 2023-07-13 | | v1.17.3 | 2023-07-11 | Showing 10 of 48 versions. Full release history on https://packagento.com/ampersand/magento2-upgrade-patch-helper. ## Dependencies ### Require | Package | Constraint | |---|---| | ext-libxml | * | | php | ~7.2\|~7.3\|~7.4\|~8.1\|~8.2 | | symfony/console | ^3.4\|^4.0 | ### Require (dev) | Package | Constraint | |---|---| | friendsofphp/php-cs-fixer | ^3.0 | | phpunit/phpunit | ^8.5\|^9.5 | | squizlabs/php_codesniffer | ^3.7 | ## Licence and pricing Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step. Refundable within 14 days of first purchase via https://packagento.com/account/refunds/. ## Install via Claude Code or any MCP client The Packagento MCP server can run the licence + project + Composer steps above in one tool call: ``` purchase_and_install_packages( composer_names=["ampersand/magento2-upgrade-patch-helper"], project_id="proj_xxx" ) ``` This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup. ## Vendor ampersand is a Magento 2 vendor on Packagento. See https://packagento.com/ampersand.md for their full catalogue.