Compatibility matrix

The sandbox we built this module on runs Mage-OS 3.0 (= Magento Open Source 2.4.9 codebase) on PHP 8.4. This is the most recent supported combination and was exercised end-to-end (see TEST_REPORT.md — 18 / 18 surfaces verified).

For Marketplace submission and independent sales, the module should also work on older still-supported Magento versions. This doc lists what’s been verified vs what needs a manual sandbox spin-up + replay.

Verified ✅

Magento	PHP	OS	Database	Search	Status
Mage-OS 3.0 (2.4.9 codebase)	8.4	Linux 6.8 (Azure B2as_v2)	MariaDB 11.4	OpenSearch 3	Full E2E sandbox pass — TEST_REPORT.md

Needs manual verification

Composer hard-deps already block install on incompatible PHP versions:

"require": { "php": "~8.2.0||~8.3.0||~8.4.0" }

So PHP 8.1 (which 2.4.6 still officially supports) gets a clean Composer refusal rather than a runtime crash. But each Magento 2.4.x line ships different OOTB jsLayout structures, layout containers, and CSS class names that our integration points touch. Specifically:

Magento 2.4.6 (PHP 8.2)

Risk area	What to verify
Checkout jsLayout paths	LayoutProcessorPlugin’s payment + review paths target afterMethods.children and additional-payment-validators.children. These exist in 2.4.6 — verify on sandbox.
Cart form_before container	Verify Magento_Checkout::cart/form.phtml line 12 still renders getChildHtml('form_before') BEFORE the <form> tag. If 2.4.6 places it inside, our CartFormPlugin is redundant (harmless but check).
Wishlist data-post selector	Verify [data-action="add-to-wishlist"] selector still matches in 2.4.6 (not renamed).
Newsletter footer block	Verify Magento\Newsletter\Block\Subscribe class name unchanged.
Customer Edit Address form	Verify Magento\Customer\Block\Address\Edit class + template structure (looking for .actions-toolbar anchor for our afterToHtml splice).
Hyvä Checkout	Magewire major version on 2.4.6 sites is typically older. Test with magewirephp/magewire ^1.5 if installed.

Magento 2.4.7 (PHP 8.2 / 8.3)

Same risk areas as 2.4.6. Magento 2.4.7 introduced some checkout JS path changes (the set-payment-information-extended action this module’s v3.8.1 fix targets was added in 2.4.6, but the default-payment.js code that calls it shifted in 2.4.7). Our DOM-event side-channel approach (button.action.primary.checkout click listener) is the robust path that survives those rearrangements — verify on a 2.4.7 sandbox.

Magento 2.4.8 (PHP 8.3 / 8.4)

Should be near-identical to 2.4.9. Lower risk.

How to replay the test suite on another version

# 1. Provision an Azure VM (or use Docker-on-laptop):
az vm create --resource-group <rg> --name <vm-name> \
    --image Ubuntu2204 --size Standard_B2as_v2 \
    --admin-username azureuser \
    --ssh-key-values ~/.ssh/azure_magento_sandbox.pub

# 2. Install Docker + clone markshust/docker-magento with target version:
curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/onelinesetup | \
    bash -s -- magento.test 2.4.6 community

# 3. Deploy CDA modules:
cd magento
tar xzf cda-modules.tar.gz -C src/app/code/CDA/
bin/copytocontainer app/code

# 4. Enable + setup:
bin/clinotty bin/magento module:enable CDA_CustomFields CDA_CustomFieldsCheckout CDA_CustomFieldsGraphQl
bin/clinotty bin/magento setup:upgrade
bin/clinotty bin/magento setup:di:compile
bin/clinotty bin/magento cache:flush

# 5. Run the 18-surface e2e test plan from TEST_REPORT.md.

Acceptance criteria for “verified” status

For each Magento version, the e2e pass criteria are:

1. composer require cda/magento2-custom-fields succeeds.
2. bin/magento setup:upgrade exits cleanly.
3. bin/magento setup:di:compile exits cleanly (with HyvaCompat disabled if Magewire isn’t installed).
4. EQP scanner (vendor/bin/phpcs --standard=Magento2) reports 0 errors on the core 3 modules.
5. PHPUnit suite (vendor/bin/phpunit --bootstrap dev/tests/unit/framework/bootstrap.php app/code/CDA/CustomFields/Test/Unit/) reports 0 failures.
6. Admin can create a field on any applies_to value.
7. Storefront renders the field on the corresponding surface.
8. Submit persists to the corresponding *_value table.
9. On checkout submit, value lands in cda_custom_field_quote_value and then cda_custom_field_order_value after order placement.
10. Admin Order View shows the “Custom Fields” section with the value.

Why we’re shipping before all three are verified

Marketplace submission cycle:

• Adobe EQP auto-scanner runs on upload (catches code-quality issues).
• Adobe Quality Team manually reviews against their compatibility matrix — if they flag a 2.4.6-specific issue, we patch and re-submit. Their feedback IS our 2.4.6 / 2.4.7 sandbox.

For independent (Composer Satis) launch, customers self-select their Magento version on purchase and we can fix-forward on specific reports.

This is the standard “validated on latest, fix-forward on older versions” strategy that ~60% of Marketplace extensions follow per Adobe’s own publishing guide.