Migrate Magento1/OpenMage to Maho
Step by Step
Since the base project structure of Maho is significantly different from previous M1 platforms, our suggested migration plan is to recreate your project from scratch and copy over only the needed parts. While this may seem more complex initially, it will pay off in the long run.
-
Create the base structure for the new project with Maho's starter pack:
composer create-project mahocommerce/maho-starter yourproject
(replaceyourproject
with your desired folder name) -
Add additional modules/extensions that you previously managed via composer:
composer require extensionname
-
Copy
app/code/community
andapp/code/local
-
Important: Remove the
app/code/local/Mage
folder, which contains direct core override files. Although override functionality is still supported, these old files will likely be incompatible with Maho's core files. -
Copy custom-only
js
/skin
files/folders topublic/js
andpublic/skin
(avoid copying core Magento/OpenMage folders/files) -
Copy custom theme folders from
app/design/frontend
(copy only your custom theme folders, not core themes) -
Review and copy files from your old document root (e.g., favicons, robots.txt, Google domain verifications) Also review any custom modifications to .htaccess if using Apache
-
Convert any custom scripts in the
shell
folder to maho-cli-commands
PHP Compatibility
Maho (as of 24.11) requires PHP 8.2+. Custom code and third-party modules will likely need adaptation to the new PHP version.
Note
Keeping server software updated is crucial for security and, in Europe, is essentially mandatory due to the privacy-by-design principle of GDPR.
Breaking Changes
Maho is not 100% backward compatible with the M1 platform. Our goal has always been clear: modernizing the M1 platform, which necessitates changes.
Each Maho release will include incompatible changes that must be considered during migration/updating. While we minimize breaking changes where possible, please carefully review Maho's release notes for each version to understand what requires additional testing and potential adaptation in your codebase.
Health Check
Maho's CLI tool includes a health-check
command that can be run periodically to monitor your project's health. It's particularly useful during migration/update phases to ensure nothing important is missed. Run it with: