Install

Compatibility

Component	Supported versions
Magento Open Source	2.4.6, 2.4.7, 2.4.8, 2.4.9
Adobe Commerce	2.4.6, 2.4.7, 2.4.8, 2.4.9
Mage-OS	1.x, 2.x, 3.x (= Magento 2.4.6 → 2.4.9 codebase)
PHP	8.2, 8.3, 8.4
Database	MariaDB 10.6+, MySQL 8.0+
Search	OpenSearch 2.x / 3.x, Elasticsearch 7.x / 8.x
Themes	Luma (full), Hyvä (full — companion package required)

Before you start

You need:

1. A license key (CDA-XXXX-XXXX-XXXX) and Composer token (cda_tok_…) — both arrive by email after purchase.
2. SSH or terminal access to your Magento project root.
3. PHP and Composer installed in that environment.

1 · Configure Composer auth

Add the CDA private repository and your bearer token. Composer reads bearer tokens from auth.json:

composer config repositories.cda composer https://magento.creativdigital.ro
composer config bearer.magento.creativdigital.ro YOUR_COMPOSER_TOKEN

Or paste the token into auth.json directly:

auth.json

{
    "http-basic": {
        "magento.creativdigital.ro": {
            "username": "YOUR_COMPOSER_TOKEN",
            "password": ""
        }
    }
}

Tip

auth.json belongs in your project root (not committed to git — Magento’s default .gitignore already excludes it). Keep your Composer token secret; never paste it into a public repo or pastebin.

2 · Install the modules

Luma-only stores

composer require cda/magento2-custom-fields
bin/magento module:enable CDA_CustomFields CDA_CustomFieldsCheckout CDA_CustomFieldsGraphQl
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Hyvä Checkout stores

Add the Hyvä compatibility module — it ships separately because it hard-requires Magewire and Hyvä Checkout, and pulling those into a Luma-only project would break setup:di:compile.

composer require cda/magento2-custom-fields cda/module-custom-fields-hyva-compat
bin/magento module:enable CDA_CustomFields CDA_CustomFieldsCheckout CDA_CustomFieldsHyvaCompat CDA_CustomFieldsGraphQl
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

3 · Activate your license

1. Open Magento Admin → Stores → Configuration → CDA → Custom Fields → Licensing
2. Paste your license key (CDA-XXXX-XXXX-XXXX) into License Key
3. Click Save Config
4. Click Verify Now — you should see “License verified — status: ACTIVE.”

If you don’t click Verify Now, the daily cron job will pick the key up on its next run (03:30 UTC by default).

Verify the install worked

After setup:upgrade, you should see:

1. Admin menu — a new top-level CDA Custom Fields entry in the sidebar, with sub-items Fields / Layout Builder / Templates / Settings.
2. Database — bin/magento setup:db:status reports isUpToDate: true. The following tables exist:
   • cda_custom_field (and its child binding tables)
   • cda_custom_field_quote_value and cda_custom_field_order_value
   • Six per-surface value tables: _customer_value, _address_value, _contact_value, _review_value, _subscriber_value, _wishlist_item_value
3. Routes — hitting POST /cda_customfields_checkout/checkout/save returns {"success":false,"message":"No active cart."} rather than a 404. This is the side-channel persistence endpoint and confirms routing works.

Network resilience

The heartbeat cron retains your previous ACTIVE status on transient network failures — a single missed cron run, DNS hiccup, or our server outage will never flip a healthy install into a locked state. Only an explicit non-ACTIVE response from our licensing server (e.g. a refunded license) downgrades you. See License & updates → Heartbeat for the full policy.

Uninstall

bin/magento module:disable CDA_CustomFields CDA_CustomFieldsCheckout \
    CDA_CustomFieldsHyvaCompat CDA_CustomFieldsGraphQl
bin/magento setup:upgrade
composer remove cda/magento2-custom-fields cda/module-custom-fields-hyva-compat

Customer order history

By default, uninstalling keeps the DB tables intact so historical orders preserve their custom-field values. If you also want to drop the data — irreversible — run:

DROP TABLE IF EXISTS
    cda_custom_field_wishlist_item_value,
    cda_custom_field_subscriber_value,
    cda_custom_field_review_value,
    cda_custom_field_contact_value,
    cda_custom_field_address_value,
    cda_custom_field_customer_value,
    cda_custom_field_order_value,
    cda_custom_field_quote_value,
    cda_custom_field_product_exclude,
    cda_custom_field_product_include,
    cda_custom_field_attribute_set,
    cda_custom_field_customer_group,
    cda_custom_field_store,
    cda_custom_field;

Common install issues

Class "Magewirephp\Magewire\Component" not found at setup:di:compile

You installed cda/module-custom-fields-hyva-compat on a store without Hyvä Checkout. Either install Hyvä:

composer require hyva-themes/magento2-hyva-checkout

Or disable the compat module:

bin/magento module:disable CDA_CustomFieldsHyvaCompat
bin/magento setup:upgrade

401 Unauthorized when running composer require

Your Composer token isn’t being picked up. Check:

composer config -l | grep bearer

You should see [bearer.magento.creativdigital.ro] = <token>. If not, re-add with composer config bearer.magento.creativdigital.ro YOUR_TOKEN.

License is already bound to <other-domain>

One license = one production domain. To transfer the license to a new domain, email office@creativdigital.ro with your license key — we reset the binding immediately. The next heartbeat from your new domain will re-bind automatically.

Loopback / private-network hosts (localhost, 127.*, 10.*, 192.168.*, 172.16-31.*) are exempt from binding and can be used freely for dev/staging.