Skip to content

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.15, 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 templates/cart-main.phtml file).

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 php-cart subdirectory.

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.

The 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.xml for the PHP Cart
  • hyva_checkout_cart_type_graphql.xml for 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 ifconfig attributes:

  • hyva_themes_cart/general/php_cart_enabled
  • hyva_themes_cart/general/graphql_cart_enabled

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"/>

Compatibility Modules

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 hyva_checkout_cart_index.xml file.
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
    "hyva-themes/magento2-default-theme": "<=1.1.14"
  • to support 1.1.15 and newer theme versions, declare a dependency on
    "hyva-themes/magento2-graphql-cart": "~1.0.1" in the composer.json

Note

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 hyva_checkout_cart_index.xml.
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.
Use the 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 hyva_checkout_cart_index.xml.

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>