Skip to content

Updating to Venta Theme 1.8.0 (Hyvä Checkout 3 and Magewire 3) ​

1.8.0 moves Hyvä Checkout from 1.3.15 to 3.0.1 and the checkout from Magewire 1 to Magewire 3 (magewirephp/magewire ~3.7.2), and adds Hyvä's v1bc compatibility module (hyva-themes/magento2-hyva-checkout-v1bc ^1.0.1). If you use Mollie, Hyvä Checkout 3's Mollie integration requires mollie/magento2 ^3.2, mollie/magento2-hyva-checkout ^3.0.4 and mollie/magento2-hyva-compatibility 3.2.0 or newer. If you use Hyvä Commerce, Venta is built against Commerce 1.4. The theme pins Hyvä Checkout 3.0.1 exactly, so the update does not resolve while your root composer.json keeps the 1.7.4 pins. Hyvä PayPal has no Checkout 3 release yet and needs a temporary branch alias. The work is in your child theme's Hyva_Checkout overrides, in project Magewire code on the checkout, and in the root composer.json. Does this affect you? shows what applies to your project.

Recommended reading:

Released packages:

PackageContainsChanges
magento2-venta-theme 1.8.0Templates, layout XML, Tailwind CSS, JS bundle1.7.4...1.8.0
magento2-venta-theme-module 1.8.0PHP classes, plugins, config defaults, seeded content1.7.4...1.8.0
magento2-venta-theme-smile-elasticsuite-module 1.8.0Search templates and scripts1.7.4...1.8.0
magento2-venta-theme-paypal 2.0.0PayPal Express1.0.4...2.0.0
magento2-venta-theme-back-in-stock-module 1.2.0Back in Stock notifications1.1.3...1.2.0
magento2-venta-theme-user-type-switcher 1.1.0Private and Business customer switcher1.0.2...1.1.0

Known issues in 1.8.0

Theme fixes for 1.8.0 are available as an optional pre-release, and Hyvä PayPal needs a branch alias until Hyvä tags its Checkout 3 release. See Known issues.

Does this affect you? ​

ImpactChangeAffects you if
HighCheckout template overridesyour child theme overrides Hyva_Checkout or Magewirephp_Magewire templates
HighOwn Magewire componentsproject or third-party Magewire components run on the checkout
HighHyvä PayPalyou use PayPal Express or extend PaypalExpress
MediumCustom checkout JavaScriptyour scripts or Playwright tests use Magewire events or update URLs
MediumAddress and guest form customizationsyou have form modifiers, AbstractForm subclasses or required custom address attributes
MediumPayment and place-order integrationsa payment module has its own place-order endpoint or activates methods in the browser
MediumEvent observersyou observe magewire_* or hyva_checkout_layout_process_before
MediumRemoved Venta plugins and changed pluginsproject DI or plugins touch Venta's Magewire or checkout plugins
MediumRemoved template overrides and layout blocksyour child theme copied them or targets header-content or logo in the checkout
MediumIssuer block removedcode extends Magebit\VentaTheme\Block\Checkout\Payment\Issuer
MediumSearch plugin replacedcode extends or disables Plugin\CatalogSearch\ResultPlugin
MediumHyvä Enterprise checkoutyou run the Hyvä Enterprise or B2B checkout modules
MediumHyvä Commerce 1.4 theme buildyou run Hyvä Commerce and your child theme has its own Tailwind config or icons.css
LowRemoved Alpine component and eventscripts use hyvaCheckoutAddressListForm or check-terms
LowACL tree positionroles, fixtures or ADMIN_RESOURCE parents depend on the old Venta ACL position
LowHyvä email defaultsyou run Hyvä Commerce emails with product images or an SVG email logo

The pre-flight checklist finds most of these in your project.

Backward incompatible changes ​

Each entry starts with who is affected, then says what breaks and what to do. Upstream changes that a Venta project is not likely to hit are on Hyvä's upgrade page and are not repeated here.

Runtime and Composer ​

  • A root composer.json that pins the checkout stack - a pin of hyva-themes/magento2-hyva-checkout to 1.3.15 or of hyva-themes/magento2-hyva-checkout-paypal to ^1.2 keeps Composer from reaching Checkout 3 or the PayPal Checkout 3 branch. If you use Mollie, a locked mollie/magento2-hyva-checkout 1.x release, even under a * constraint, stays on Checkout 1.3 unless you raise it to ^3.0.4 and include it in the update, and a mollie/magento2 pin below ^3.2 (for example ~3.0.2) blocks Hyvä Checkout 3's Mollie integration. If you use Hyvä Commerce, raise a ~1.3.0 pin to ~1.4.0 with the update. composer update alone keeps Checkout at 1.3.15. Raise the pins with composer require --no-update in §1, then update with dependencies. Do not use -W.

Checkout templates and project code ​

  • Child-theme overrides of Hyva_Checkout templates - Venta ported its own overrides to Magewire 3. Copies in a child theme still use the Magewire 1 API (wire:model deferral changes, emitTo, Magewire.hook, deferred components) and no longer match the Checkout 3 templates. Upstream lists 12 new, 56 updated and 4 removed templates in its template changes. Compare each override with Venta's version and with Hyvä Checkout 3.0.1: use wire:model.live where you want live sync, and dispatchTo instead of emitTo. Also review overrides of magewire/component/form.phtml, Magento_Customer/form/login-component.phtml and the init JS templates. §2 has the routine.

  • Child copies of templates Venta no longer overrides - Venta drops its overrides of the Magewirephp_Magewire messenger, the Hyva_Checkout loader bindings, the Magewire error plugin, the multi-tabs compatibility template and the shipping method-activate scripts. Upstream deleted address-list/form.phtml and multi-tabs-compatibility.phtml. Delete your copies, or port them against the upstream template.

  • Layout XML that targets header-content or the default logo block in the Venta checkouts - both blocks are removed from hyva_checkout_venta.xml, and the children of header-content go with it. Target venta.checkout.header and venta.checkout.logo instead.

  • Templates or scripts that use hyvaCheckoutAddressListForm or listen to check-terms - the hyvaCheckoutAddressListForm Alpine component from address-view/address-list.phtml is no longer defined. The check-terms window event is no longer dispatched: the merged agreement checkbox accepts all agreements in one Magewire commit.

  • Project or third-party Magewire components on the checkout - Magewire 3 changes the component contract:

    • public properties are restored before boot(), so defaults assigned in boot() overwrite the browser state
    • the arguments of updating() and updated() swap order
    • redirect() returns nothing and drops $params
    • dispatchBrowserEvent() needs array data, and emit() takes one associative array
    • a template that starts with a condition or loop must render its root element unconditionally
    • a <script> added only by a re-render no longer runs
    • auto-save and canAutoSave() are gone
    • DataObject instances and models in public properties are refused

    Port migrated checkout components with #[HandleBackwardsCompatibility(enabled: false)], use updatedFoo($value), build redirect URLs with UrlInterface, and move defaults to the property declarations, mount() or booted(). Hyvä's Magewire 3 migration guide has the details.

  • Custom checkout JavaScript and Playwright tests - on plain Checkout 3, magewire:load and magewire:available are not dispatched; with v1bc they fire after Alpine. Positional Magewire.on() parameters arrive as one array. Updates post to /magewire/update with a components body, and Alpine components must register in alpine:init. Register hooks in magewire:init with the Magewire 3 names and send named payloads. In Playwright, match /magewire/update and JSON.parse(options.body).components instead of /livewire/message/<name>. Server-side detection reads getParam('components').

  • Form modifiers, AbstractForm subclasses and required custom address attributes - submit() refuses an empty required field on the server. Modifier listeners typed on 1.x address form classes are skipped. Plain wire:model stays deferred on the address and guest forms. The 1.3 signatures of AbstractEntityForm::init, AbstractAddressForm::edit, EvaluationResultFactory::createEvent and WithAttributes::removeAttributesStartingWith no longer load. Leave the listener's component parameter untyped, use wire:model.live for live fields, override requiresOnSubmit() to opt a field out, and update the signatures. See Hyvä's customizations that need a change.

  • Observers for magewire_<event> or hyva_checkout_layout_process_before - magewire_* events fire only while Hyva_CheckoutV1bc is enabled. hyva_checkout_layout_process_before is now dispatched, so existing observers of it start running. Venta keeps v1bc enabled. Move observers to hyva_checkout_* or component events before you ever disable it.

  • Payment modules with their own place-order endpoint, client-side method activation, REST totals readers, stepfirst or steplast step names, and Magewire components outside the checkout - Place Order reCAPTCHA applies to checkout placements and to carts whose checkout showed the challenge. The server activates the method saved on the quote after each method list refresh. REST cart totals no longer carry Hyvä's tax details. A checkout or step name ending in stepfirst or steplast is rejected, and Magewire starts only on checkout pages. Guard your own endpoints with PlaceOrderScope::run(), activate methods server-side, rename such steps, and add <update handle="hyva_checkout_magewire_startup"/> to module pages that render components.

  • Projects running hyva-themes/magento2-ee-hyva-enterprise-checkout or -b2b - their releases before the Checkout 3 ones need Checkout 1.3. Use the Checkout 3 compatible releases named on Hyvä's upgrade page.

Venta classes and plugins ​

  • Code or DI that extends, disables or references Venta's Magewire 1 plugins - Plugin\Magewire\Component\EmitTotalsChangedEvent (DI name emit_totals_changed_event), Plugin\Magewire\InjectSvgSprite (DI name Magebit_VentaTheme::inject_svg_sprite_magewire) and Plugin\Hyva\Checkout\Magewire\Checkout\PriceSummary\RefreshOnTotalsChanged (DI name refresh_on_totals_changed) no longer exist. The page plugin Plugin\InjectSvgSprite stays. Totals refresh and sprite injection now live in Model/Magewire/Features/. Remove your references.

  • Your own plugins on the same targets as PreventGuestCheckoutPlugin, the shipping MethodList or TermsConditionsPlugin - PreventGuestCheckoutPlugin is now an around plugin. It stops the controller for a refused guest and defers to Hyvä's own refusal when one-page checkout is off. MethodList and TermsConditionsPlugin use the Checkout 3 method list and evaluation result API. Re-test your sibling plugins and their sort orders.

  • Projects that extend Magewire/Payment/Method/PaypalExpress.php or pin hyva-themes/magento2-hyva-checkout-paypal - Venta's PayPal Express component follows the Hyvä PayPal Checkout 3 branch: the constructor changes, and edit() and cancel() return void. The Hyvä plugin hyva-paypal-express-redirect-to-review is disabled in etc/frontend/di.xml, and the checkout express button sends button=1. Venta's PayPal module requires magewirephp/magewire ~3.7.2 and Hyvä Checkout ^3.0.1. The stock Hyvä PayPal 1.2.x requires Checkout ^1.3; Hyvä's Checkout 3 branch allows ^1.3 || ^3.0. Require the branch as described in §1 and port your override to the new constructor.

  • Code that extends Magebit\VentaTheme\Block\Checkout\Payment\Issuer or calls getListType() - the class and the method are gone. Mollie's own issuer block selects the template: a list, a dropdown or none, per the method's "Issuer List Type". Use Mollie's block and payment/mollie_methods_<method>/issuer_list_type.

  • Code that extends or disables Plugin\CatalogSearch\ResultPlugin - it is replaced by Plugin\Result\Index\RedirectSearchResult. The DI name magebit_redirect_if_one_result is kept on Magento's search controller (Magento\CatalogSearch\Controller\Result\Index) and points at the new class there. Venta's own search controller, the one that serves the search page, uses the new DI name magebit_redirect_search_result, so disabling magebit_redirect_if_one_result alone no longer turns the redirect off; disable both names. Smile's search_term_and_single_result_redirect is disabled next to redirect_if_one_result. Re-point your extensions to RedirectSearchResult.

  • Roles, fixtures or ADMIN_RESOURCE parents that depend on the old top-level ACL position - the Theme and Elasticsuite resources now sit under Magento_Backend::stores > Magento_Backend::stores_settings > Magento_Config::config > Magebit_Core::config (title "Magebit", declared by Venta in both acl.xml files). The resource ids are unchanged. Saved roles need nothing: the data patches KeepRoleAccessToThemeAcl and KeepRoleAccessToElasticsuiteAcl give them the rows they need on setup:upgrade.

Emails ​

  • Hyvä Commerce stores that show product images in emails built with the Hyvä editor - hyva_email_templates/email_template/show_product_images now defaults to 0, and Venta emails use Magento's classic items table. Set the path to 1 to bring the thumbnails back.

  • Stores whose only email logo is an SVG, or that have none - the "Venta - Email Logo" block never renders an SVG, because Gmail and Outlook ignore SVG: without a raster email logo or header logo it uses Magento_Email::logo_email.png. Hyvä's own Header block still falls back to the theme's logo.svg. Upload a raster email logo under Content > Design > Configuration: edit the store view, then Other Settings > Transactional Emails > Logo Image.

Hyvä Commerce 1.4 ​

Venta covers only the three items below. Everything else is in Hyvä's Commerce 1.4.0 upgrade notes.

  • Commerce 1.4 deploy - setup:upgrade can fail with Error while checking if topic "hyva.ai_worker.job.chunk" is synchronous. Run bin/magento cache:flush first, see §3.

  • Commerce 1.4 with a child theme that has its own web/tailwind/utilities/icons.css - the Tailwind build fails with Cannot apply unknown utility class `after:icon-asterisk` . Copy the @utility icon-asterisk block from the theme's icons.css.

  • Commerce 1.4 with Hyva_LinkedProducts enabled and a child theme that has its own web/tailwind/hyva.config.json - the module's unscoped .swatch-option styles turn text swatches in the grid listing into bordered boxes. Venta's theme build excludes the module's CSS. Add the same entry to exclude in your file, then rebuild:

    json
    { "src": "vendor/hyva-themes/commerce-module-linked-products/src", "keepSource": true }

Prerequisites ​

  • Venta Theme 1.7.4 with Hyvä Checkout 1.3.15. If you are further back, work through Updating to 1.7.4 first.
  • hyva-themes/magento2-hyva-checkout 3.0.1 and hyva-themes/magento2-hyva-checkout-v1bc 1.0.1 installable from your Composer repositories.
  • Hyvä Commerce 1.4 (hyva-themes/commerce ~1.4.0) if your project runs Hyvä Commerce.
  • Checkout 3 compatible releases of the Hyvä Enterprise and B2B checkout modules, if you use them.

Pre-flight checklist ​

Run this while the project is still on 1.7.4, from the project root. Replace app/design and app/code with your theme and module paths if they differ, and include packages installed under vendor/<client>/. The patterns are built from Venta's and Hyvä's sources, not from a client project, so review each hit. Checks 3, 5 and 11 are heuristics and produce false positives.

1. Check your root Composer pins ​

bash
grep -n -e 'magento2-hyva-checkout' -e 'hyva-themes/commerce' -e 'mollie/' -e 'magewirephp' composer.json

A pin on Checkout 1.3.15 or Hyvä PayPal ^1.2 blocks the update. With Mollie, a mollie/magento2 pin below ^3.2 or a locked mollie/magento2-hyva-checkout 1.x blocks it too. With Hyvä Commerce, raise a ~1.3.0 pin with the update. Root Composer pins has the fix.

2. Inventory your checkout and Magewire template overrides ​

bash
find app/design -path '*Hyva_Checkout/*' -type f; find app/design -path '*Magewirephp_Magewire/*' -type f

Every hit is a template to port or delete. See checkout template overrides and removed template overrides. Snapshot the Venta theme package now, before the Composer update, so §2 can list every changed file you override:

bash
cp -R vendor/magebitcom/magento2-venta-theme /tmp/venta-theme-1.7.4

3. Find Magewire 1 API in project code ​

bash
grep -rn -e 'emitTo' -e 'emitUp' -e '$wire.emit' -e 'Magewire.hook(' -e 'Magewire.emit' -e 'magewire:load' -e 'magewire:available' -e 'wire:model.defer' -e 'wire:model.lazy' -e 'x-defer' -e 'canAutoSave' -e 'dispatchBrowserEvent' app

A hit is code to port. See checkout template overrides, own Magewire components and custom checkout JavaScript.

4. Find references to the removed Venta plugins ​

bash
grep -rn -e 'Plugin\\Magewire\\Component\\EmitTotalsChangedEvent' -e 'Plugin\\Magewire\\InjectSvgSprite' -e 'RefreshOnTotalsChanged' -e 'emit_totals_changed_event' -e 'inject_svg_sprite_magewire' -e 'refresh_on_totals_changed' app

The page plugin Plugin\InjectSvgSprite is not matched on purpose. A hit is a reference to remove. See removed Venta plugins.

5. Find layout updates on the removed checkout blocks ​

bash
grep -rn -e 'name="header-content"' -e 'name="logo"' app --include='hyva_checkout*.xml'

Review each hit: a logo block also exists outside the checkout. See layout blocks.

6. Find the removed Alpine component and window event ​

bash
grep -rn -e 'check-terms' -e 'hyvaCheckoutAddressListForm' app

See removed Alpine component and event.

7. Find PayPal Express overrides ​

bash
grep -rn -e 'PaypalExpress' -e 'hyva-paypal-express-redirect-to-review' app

A hit is an override to port to the new constructor, or a reference to the disabled Hyvä plugin. See Hyvä PayPal.

8. Find uses of the removed Issuer block ​

bash
grep -rn -e 'Checkout\\Payment\\Issuer' -e 'getListType' app

See Issuer block removed.

9. Find extensions of the removed search plugin ​

bash
grep -rn -e 'CatalogSearch\\ResultPlugin' -e 'magebit_redirect_if_one_result' -e 'magebit_redirect_search_result' app

See search plugin replaced.

10. Find Magewire and checkout event observers ​

bash
grep -rn -e 'magewire_' -e 'hyva_checkout_layout_process_before' app --include=events.xml

See event observers.

11. Find ACL parents and fixtures tied to the Venta tree ​

bash
grep -rn -e 'Magebit_VentaTheme::' -e 'Magebit_VentaSmileElasticSuite::' app --include='*.xml' --include='*.php'

Template references match too. Look only at hits in an acl.xml parent, a fixture or an ADMIN_RESOURCE constant. Saved roles need nothing. See ACL tree position.

12. Check your theme build files for Hyvä Commerce 1.4 ​

bash
grep -n 'linked-products' app/design/frontend/*/*/web/tailwind/hyva.config.json; grep -n 'utility icon-asterisk' app/design/frontend/*/*/web/tailwind/utilities/icons.css

Only relevant with Hyvä Commerce. An empty result for a file your child theme has means the entry is missing. See icon-asterisk and Linked Products CSS.

What changed ​

Breaking changes are listed above and not repeated here.

Checkout ​

  • Theme, modules and extensions run on Hyvä Checkout 3.0.1 and Magewire 3. Venta's checkout templates are ported, and the header is the venta.checkout.header block.
  • Express payments show on the entry step only.
  • A zero tax line, a failure dialog, a merged agreement checkbox and a quote item notice follow Checkout 3.
  • Custom address attributes get placeholders and field overrides.
  • Magewire updates post to /<store_code>/magewire/update on store-code URLs.
  • The cart drawer has an extra_actions container, which holds the Mollie Apple Pay mini cart button.
  • Mollie is optional. Magebit_VentaTheme compiles without it. See Removing Mollie.

Emails ​

  • Magebit_VentaTheme provides blocks and presets for the Hyvä email editor: the blocks "Venta - Email Logo", "Venta - Email Footer Links" and "Venta - Email Social Links", and Venta presets for a Header Template or Footer Template. An admin adds the blocks or starts a template from the preset. The Venta header and footer render the classic frame in Open Sans.
  • Magebit_VentaTheme::email/default_chrome.phtml draws the Venta header and footer that Hyvä uses as its default header and footer in the editor preview and in newsletters. Header and Footer Templates built from the Venta preset keep their own block tree; edit them in the Hyvä editor.
  • etc/module.xml - the module sequence gains Hyva_EmailTemplates. Stores without Hyvä Commerce stay on classic emails, and setup:upgrade and di:compile succeed.
  • Emails already built in the Hyvä editor change their look. No email is remapped and no stored content changes.
  • Classic footer - the social icons come from venta_theme/social/*_url, the Shipping Policy link opens shipping-policy, and footer link titles are translated.

Catalog and listing ​

  • Notify Me takes the Add To Cart slot on grid and widget cards, and in list view after an out-of-stock pick. Out-of-stock swatch combinations with no product are disabled, a pick in one card no longer leaks into other cards, and the image blur is fixed.
  • With Hyvä Commerce Linked Products, the product page swatches get Venta styling.
  • List-mode tier prices show the divider on mobile only and read <price> per piece. The grid keeps "each". The list layout, spacing and rating stars on loaded pages are fixed.
  • Infinite scroll uses the productListPagingState Alpine component and data-more-pages. The Show More button is centred, with new mobile spacing.
  • The product page zoom reuses the framed fullscreen renditions, so it keeps the slide's white frame while gallery white bars are on. Deferred slides use the desktop rendition from 768px unless a tablet row exists.
  • The single-result redirect follows Smile's "Redirect to product page if only one result" (on by default). Search term redirects reach the Elasticsuite tracker, the "only product matching" message shows only after that redirect, and the header search opens the search page directly.
  • The popular-term fallback needs Magebit_VentaSmileElasticSuite. Term links open the search page, and search_data.phtml changes.

Theme build and scripts ​

  • short: and medium: variants now compile (@custom-variant). The cart drawer hides the cross-sell slider at heights up to 674px, and the checkout summary column changes at 768px and wider when the window is up to 980px tall.
  • The browser JIT generator keeps its config after a quoted single-star @source glob.
  • SnapSlider - opt-in drag (x-snap-slider.drag, data-drag, the drag option), translatable pager marker labels and destroy() cleanup.
  • scroll-lock-bleed utility - the page no longer shifts sideways when a drawer, modal or the mobile menu hides the scrollbar.
  • Directory data (regions, country options, checkout regions and the directory-data section) is cached per store and locale.
  • Playwright - the MAGENTO_CSP_DEFAULT_STORE_CODE environment variable sets the store for the CSP twin store spec.

Smaller packages ​

  • Back in Stock - the "Venta - Back in Stock Products" Hyvä email block and the Stock Alert preset (greeting plus products block, with the same products, prices and unsubscribe links).
  • User Type Switcher - requires Hyvä Checkout ^3.0.1. The server also hides the business fields for a Private submission.
  • PayPal - follows the Hyvä PayPal Checkout 3 branch, see Hyvä PayPal.
  • Style Guide - version bump only.

1. Update Composer dependencies ​

Dev environment and production

Do steps 1 to 3 on a branch in a dev environment and commit composer.json, composer.lock, app/etc/config.php, app/etc/hyva-themes.json and your ported overrides. Deploy through your pipeline and run the sequence there: composer install, setup:upgrade, setup:di:compile, setup:static-content:deploy -f, cache:flush.

Run the commands of this step in one shell session. Each block raises its pins with composer require --no-update and adds the packages to PACKAGES, the list the final composer update moves. Run only the blocks that apply to your project: composer require adds a package the project does not have, and composer update refuses a package the project does not require.

Raise the Hyvä Checkout stack and the two core Venta packages. A plain composer update keeps the old 1.3.15 pin, so the pins change first:

bash
composer require --no-update \
  hyva-themes/magento2-hyva-checkout:^3.0.1 \
  hyva-themes/magento2-hyva-checkout-v1bc:^1.0.1 \
  hyva-themes/magento2-theme-module:^1.3.16 \
  magewirephp/magewire:~3.7.2 \
  magebitcom/magento2-venta-theme:1.8.0 \
  magebitcom/magento2-venta-theme-module:1.8.0
PACKAGES=(
  hyva-themes/magento2-hyva-checkout
  hyva-themes/magento2-hyva-checkout-v1bc
  hyva-themes/magento2-theme-module
  magewirephp/magewire
  magebitcom/magento2-venta-theme
  magebitcom/magento2-venta-theme-module
)

If the project uses Mollie:

bash
composer require --no-update \
  mollie/magento2:^3.2 \
  mollie/magento2-hyva-checkout:^3.0.4
PACKAGES+=(mollie/magento2 mollie/magento2-hyva-checkout)

If the project runs Hyvä Commerce:

bash
composer require --no-update hyva-themes/commerce:~1.4.0
PACKAGES+=(hyva-themes/commerce)

If the project uses the ElasticSuite module:

bash
composer require --no-update magebitcom/magento2-venta-theme-smile-elasticsuite-module:1.8.0
PACKAGES+=(magebitcom/magento2-venta-theme-smile-elasticsuite-module)

If the project uses Back in Stock:

bash
composer require --no-update magebitcom/magento2-venta-theme-back-in-stock-module:1.2.0
PACKAGES+=(magebitcom/magento2-venta-theme-back-in-stock-module)

If the project uses the Style Guide:

bash
composer require --no-update magebitcom/magento2-venta-theme-style-guide:1.0.4
PACKAGES+=(magebitcom/magento2-venta-theme-style-guide)

If the project uses the User Type Switcher:

bash
composer require --no-update magebitcom/magento2-venta-theme-user-type-switcher:1.1.0
PACKAGES+=(magebitcom/magento2-venta-theme-user-type-switcher)

If the project uses PayPal, require Hyvä's PayPal Checkout 3 branch, pinned to the commit Venta 1.8.0 was tested with (see Known issues):

bash
composer require --no-update \
  "hyva-themes/magento2-hyva-checkout-paypal:dev-feature/checkout-3-compat#89a3dd8374a8e73319d7ab98bdefc436a2d7673f as 3.0" \
  magebitcom/magento2-venta-theme-paypal:2.0.0
PACKAGES+=(hyva-themes/magento2-hyva-checkout-paypal magebitcom/magento2-venta-theme-paypal)

Update everything in PACKAGES with its dependencies. Do not use -W:

bash
composer update "${PACKAGES[@]}" --with-dependencies
composer show hyva-themes/magento2-hyva-checkout        # must report 3.0.1
composer show magewirephp/magewire                      # must report 3.7.2 or a later 3.7.x
composer show hyva-themes/magento2-hyva-checkout-v1bc   # must report 1.0.1 or newer

With Mollie, composer show mollie/magento2-hyva-compatibility must report 3.2.0 or newer. Review the composer.lock diff before you commit.

Removing Mollie ​

To remove Mollie, skip the Mollie block above, list hyva-themes/magento2-mollie-theme-bundle, mollie/magento2-hyva-compatibility and mollie/magento2 under replace in the root composer.json, and drop any requirement of your own on mollie/magento2-hyva-checkout. In Venta's own installation these packages provide the modules Hyva_MollieThemeBundle, Mollie_Payment, Mollie_HyvaCompatibility and Mollie_HyvaCheckout. Rebuild the theme afterwards (§3).

2. Port your overrides and project code ​

Compare the snapshot from pre-flight check 2 with the updated package, and keep the files that exist in your child theme:

bash
THEME=app/design/frontend/<Vendor>/<ProjectTheme>
git -C "$THEME" ls-files | sort > /tmp/overrides.txt
git diff --no-index --name-status /tmp/venta-theme-1.7.4 vendor/magebitcom/magento2-venta-theme \
  | awk '{print $NF}' | sed -e 's#^/tmp/venta-theme-1.7.4/##' -e 's#^vendor/magebitcom/magento2-venta-theme/##' \
  | sort -u | comm -12 - /tmp/overrides.txt

Every override that check 2 found goes on the list too, whether Venta changed the file or not, because Hyvä Checkout 3 changed the templates underneath it. Work through the list with the File Review routine. What each group needs:

  • Hyva_Checkout/** and Magewirephp_Magewire/** - port to Magewire 3 per checkout template overrides. Delete the copies listed under removed template overrides.
  • hyva_checkout_venta.xml - retarget header-content and logo per layout blocks.
  • List-mode product cards and tier prices, infinite scroll pager templates, search_data.phtml, SnapSlider and the cart drawer - rebase on the vendor files. What changed lists the changes in each.

Then port project PHP, JavaScript, observers and plugins from the checkout and project code entries that pre-flight checks 3 to 11 found.

Alternative: Venta Upgrade Tool

With access to the magebitcom GitHub organization, magebitcom/venta-upgrade-tool does this per file with a three-way merge.

3. Upgrade and deploy ​

bash
bin/magento cache:flush
bin/magento setup:upgrade
bin/magento setup:di:compile

Hyvä Commerce

Keep cache:flush before setup:upgrade in your deploy pipeline too.

setup:upgrade enables Hyva_CheckoutV1bc and adds it to app/etc/config.php and app/etc/hyva-themes.json. On a 1.7.4 project this is a new module. Commit both files and keep the module enabled: the Hyvä PayPal Checkout 3 branch renders its scripts in a Magewire 1 container. Projects that ran Hyvä Checkout 3.0.0 or the 1.4.0 beta have Hyva_CheckoutMwv1bc instead, which Hyvä renames to Hyva_CheckoutV1bc.

The same run applies Hyvä's ClearCompiledMagewireViews data patch, which deletes the storefront's compiled Magewire views once. If that fails, it logs a warning and the upgrade goes on. Clear them by hand then:

bash
bin/magento magewire:compile:clear --area=frontend

Run that command on every server whose var/magewire the setup:upgrade host does not share, and reset OPcache where it does not check file timestamps.

Rebuild the theme assets in your child theme. The build picks up the ported templates, so it runs after §2:

bash
cd app/design/frontend/<Vendor>/<ProjectTheme>/web/tailwind
npm run build-prod

Deploy the rebuilt assets:

bash
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

4. Review settings ​

  • Checkout address fields - the address field configuration is the same before and after setup:upgrade. Verification item 2 checks it.
  • Single-result search redirect - check Smile's redirect setting, see Search.
  • Mollie issuers - check each method's "Issuer List Type", see Issuer block removed.
  • Admin roles - nothing to do for saved roles, see ACL tree position.
  • Hyvä emails - decide on product thumbnails and the email logo, see email defaults and email logo.

Known issues ​

Venta Theme 1.8.0 has a few known issues:

  • Configurable product cards on category pages lose the tier price table and the quantity input in list mode, and read "each" instead of "per piece" in grid mode.
  • The checkout address grid throws an error for customers with two or fewer saved addresses.
  • Cart drawer product images shrink next to long product names.

They are fixed in the 1.8.1-rc.1 pre-release. Install it with Composer, or use its changes to build your own vendor patch. The next release includes the same fixes, so this step is optional.

bash
composer require --no-update magebitcom/magento2-venta-theme:1.8.1-rc.1
composer update magebitcom/magento2-venta-theme

Use the exact version: with minimum-stability: stable, Composer does not install a pre-release from a version range. Rebuild the theme afterwards (§3).

Hyvä PayPal on Checkout 3 ​

Venta PayPal 2.0.0 requires a Checkout 3 release of hyva-themes/magento2-hyva-checkout-paypal, and Hyvä has not tagged one yet. Until it does, install the Checkout 3 branch at commit 89a3dd8, the commit the Venta 1.8.0 demo runs:

bash
composer require --no-update \
  "hyva-themes/magento2-hyva-checkout-paypal:dev-feature/checkout-3-compat#89a3dd8374a8e73319d7ab98bdefc436a2d7673f as 3.0" \
  magebitcom/magento2-venta-theme-paypal:2.0.0
composer update hyva-themes/magento2-hyva-checkout-paypal magebitcom/magento2-venta-theme-paypal --with-dependencies

When Hyvä tags the release, switch to it:

bash
composer require --no-update hyva-themes/magento2-hyva-checkout-paypal:^3.0
composer update hyva-themes/magento2-hyva-checkout-paypal

Known limitations ​

These apply to emails built with the Hyvä editor:

  • Hyvä writes mapped templates to design/email/*_template.
  • Newsletters ignore a mapped Header or Footer Template.

Post-upgrade verification ​

  1. The checkout runs on Magewire 3. Open each checkout your stores use. The browser console has no errors, and Magewire requests go to /<store_code>/magewire/update on store-code URLs.
  2. Orders place. Place an order as a guest and as a customer with each payment method you offer. The same address fields show and are required as before.
  3. Totals refresh. Change the shipping method. The price summary updates and the checkout icons render.
  4. Agreements accept in one go. With terms and conditions on, one checkbox accepts all agreements.
  5. Express payments show on the entry step only. With PayPal and One-Click Express Checkout on, the express button places the order and shows the success page. With it off, an approved shortcut payment is no longer sent to the separate PayPal review page.
  6. Mollie issuers render. With Mollie, each method shows a list, a dropdown or nothing, per its "Issuer List Type".
  7. Hyva_CheckoutV1bc is enabled. bin/magento module:status Hyva_CheckoutV1bc reports it enabled, and app/etc/config.php and app/etc/hyva-themes.json are committed.
  8. Search redirects. A search with one result opens the product page while Smile's redirect setting is on, and the "only product matching" message shows once.
  9. Admin roles keep access. A restricted role that had Theme or Elasticsuite access still opens those sections under Stores > Configuration > Magebit.
  10. Emails render. Send a test order email. Classic emails keep their look, and with Hyvä Commerce an email built from the Venta header and footer presets shows them and a raster logo.
  11. The theme build passes. With Hyvä Commerce 1.4, npm run build-prod reports no icon-asterisk error. With Linked Products, grid listing text swatches are not bordered boxes.
  12. Listing behaves. On a category with out-of-stock products, Notify Me sits in the Add To Cart slot, and the Show More button loads the next page.