Supporting both the PHP and the GraphQL Cart
Up to Hyvä 1.1.14, Hyvä used the "GraphQL Cart" page. It requested the cart data with GraphQL and rendered the cart page with Alpine.js.
Since release 1.1.5, Hyvä uses a "PHP Cart" page, which renders the cart server side with PHP, and uses Alpine.js for user interaction only.
Backward compatibility is provided by a hyva-themes/magento2-graphql-cart extension.
The extension allows selecting the cart type to use in the system configuration at
"Hyva Themes > Cart Page > General Settings".
Because of this, compatibility modules ideally support both cart pages.
Dealing with two cart page types
There are two aspects that can cause conflicts:
- Template file names
- Layout XML block and container names
Template file names
In the PHP Cart there are no template file names that conflict with the GraphQL Cart.
All PHP Cart related template files can be found in a subdirectory
templates/php-cart/ (in addition to the
The GraphQL Cart template files are not collected within a single subdirectory, because at the time it was written, it was the only cart page, and the need to distinguish them from another cart was yet unknown.
We suggest you follow the same convention and place any PHP Cart related templates in a
Block and Container names
Block and Container names in Layout XML have to be unique within a page.
Unfortunately, there is one block called
checkout.cart.methods with a "special" meaning in Magento.
This block can't be renamed depending on the active cart type.
It is used by the core and many extensions to add checkout methods, and is assumed to be in a different location within the Layout XML structure by the two carts.
hyva-themes/magento2-graphql-cart extension takes care of this by moving the block to the appropriate parent and assigning the appropriate template depending on the selected cart.
For custom extensions and compatibility modules it should be possible to avoid name conflicts. Should it not be possible for some reason, the issue can be resolved as described below.
Declaring Layout XML depending on the cart type
When the hyva-themes/magento2-graphql-cart extension is installed, an additional layout handle, depending on the configured cart page, is included.
hyva_checkout_cart_type_php.xmlfor the PHP Cart
hyva_checkout_cart_type_graphql.xmlfor the GraphQL Cart
Also, a system configuration flag is available for the configured cart type. With this it is possible to declare blocks to render only if a given cart is selected using the
For example, the following block is only instantiated if the PHP Cart is used:
<block name="php-cart-checkout-button" template="My/Module::php-cart/my-checkout.phtml" ifconfig="hyva_themes_cart/general/php_cart_enabled"/>
For most compatibility modules it will be enough to declare the blocks and templates for each cart type and hook them into the appropriate containers in the
Only the appropriate templates will be shown depending on the active cart page, because only the containers for the active cart type will be rendered.
Compatibility with only one cart type
Compatibility modules that are only compatible with the GraphQL Cart should do one of the following:
- to support older theme versions, declare a version constraint on
- to support 1.1.15 and newer theme versions, declare a dependency on
"hyva-themes/magento2-graphql-cart": "~1.0.1"in the
It is not possible to do both of the above at once. Two releases with different constraints are required.
Please consider supporting both cart types, rather than maintaining two release branches.
Compatibility modules that are only compatible with the PHP Cart should declare a version constraint on
"hyva-themes/magento2-default-theme": ">= 1.1.15".
Do not declare a conflict with
hyva-themes/magento2-graphql-cart, because the extension allows to configure the PHP Cart for any store view.
New compatibility modules
For new compatibility modules, choose block names and templates names that are unique for each cart type in
For most compat modules that already is enough to "just work".
If necessary, use the
hyva_checkout_cart_type_graphql.xml layout file to make any required changes to cart page to enable GraphQL Cart compatibility.
In rare cases it might also be necessary to declare Layout XML that is only evaluated when the PHP Cart is enabled.
hyva_checkout_cart_type_php.xml layout file for that purpose.
Upgrading compatibility modules to support the PHP Cart
Existing compatibility modules assume the GraphQL cart as the default.
In this case, first try adding the new blocks and templates to also support the PHP Cart to
If a conflict arises, either use the
hyva_checkout_cart_type_php.xml layout file or use the
ifconfig="hyva_themes_cart/general/php_cart_enabled" attribute to conditionally declare blocks when the PHP Cart is active.
Example layout XML supporting both cart pages
As an example, here is the
hyva_checkout_cart_index.xml file for the
Magento_GiftCard compatibility module.
Both cart types are supported:
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"> <body> <!-- GraphQL Cart --> <referenceContainer name="additional.cart.item.options"> <block name="giftcard-item-options" template="Hyva_MagentoGiftCard::cart/item/giftcard-options.phtml"/> </referenceContainer> <referenceContainer name="additional.cart.information"> <block name="giftcard-form" template="Hyva_MagentoGiftCard::cart/giftcard/form.phtml"/> </referenceContainer> <referenceContainer name="additional.cart.totals"> <block name="giftcard-totals" template="Hyva_MagentoGiftCard::cart/giftcard/totals.phtml"/> </referenceContainer> <!-- PHP Cart --> <referenceContainer name="cart.discount"> <block name="giftcard-form.php-cart" class="Magento\GiftCardAccount\Block\Checkout\Cart\Giftcardaccount" template="Hyva_MagentoGiftCard::php-cart/giftcard/form.phtml"/> </referenceContainer> <referenceContainer name="checkout.cart.totals"> <block name="giftcard-totals.php-cart" class="Magento\GiftCardAccount\Block\Checkout\Cart\Total" template="Hyva_MagentoGiftCard::php-cart/giftcard/totals.phtml"/> </referenceContainer> </body> </page>