Cart - a TYPO3-native shop system

Extension key

cart

Package name

extcode/cart

Version

11.4

Language

en

Author

Daniel Gohlke & Contributors

License

This document is published under the Open Publication License.

Rendered

Fri, 12 Sep 2025 08:15:27 +0000

This extension is the base for a TYPO3-native shop solution.

Together with other existing extensions for products and payment solutions a shop using Extbase & Fluid can be implemented. This might be the best extendable shop solution for TYPO3.

Description

The extension is a small but powerful extension which "solely" adds a shopping cart to your TYPO3 installation and is well suited for content commerce.

The extension allows you to add products to a cart and handles the order process completely.

There are other awesome extensions to handle various types of products. Furthermore, you will find some payment provider extensions to add payment methods to the checkout process. Have a look at Other cart extensions.

Features

• Makes intensive use of the TYPO3 Core API functionality (is "TYPO3-native").

• Easily expandable:

  • Multiple PSR-14 events and interfaces
  • API (finisher pipeline) to process the order with possibility to register own tasks
  • API to add payment providers
  • API to connect your own product extensions
• Highly configurable through TypoScript
• Proved Bootstrap templates
• Backend module to show and utilize orders

Aspects to decide whether to choose EXT:cart or another shop solution

Showcases

Examples of websites which use this extension as e-commerce solution.

Table of contents

Slack

There is an own channel at the TYPO3 Slack. Please use this channel to contact us.

The URL is: https://typo3.slack.com/messages/ext-cart/

Support

If you need further support, please contact me.

This support is not always free!

Sponsors

Instructions

1. Install this extension:

   See Installation → Install the extension.

2. Include the TypoScript of this extension:

   See Installation → Include TypoScript.

3. Install a product database extension

   You need to install at least one more extension to get a working shop setup. This other extension will offer the products itself. This can be one of the existing extensions or a custom extension.

   See Other cart extensions.

   The next steps of this quick start use EXT:cart_products. Include the TypoScript of this second extension as described above or as described in the corresponding documentation.

4. Create the needed pages and directories in the TYPO3 backend.

   

   1. Create a page for cart. Here it's named Cart.
   2. Create a page for a list of products. Here it's named Products.
   3. Create a page for the detail view of a product. Here it's named Detail.
   4. Create a page of type "directory" where the products will be stored. Here it's named Products Storage.
   5. Create a page of type "directory" where the orders will be stored. Here it's named Orders.

   Tip

   You can create multiple, even nested, directories to organize your products in the backend.

   In this case you can even have multiple pages for lists and detail views.

5. Create Plugin for the cart

   

   On the page Cart:

   • Create a record of type plugin Cart: Cart.

6. Create Plugin for the list view

   

   On the page Products:

   • Create a record of type plugin Cart: Products and make the following settings:

     • Choose "Display Type" = "List (and Show) View".
     • In Product Detail Page choose the page Detail.
     • In Record Storage Page choose the page Products Storage.

7. Create Plugin for the detail view

   

   On the page Detail:

   • Create a record of type plugin Cart: Products.

     • Choose "Display Type" = "Show View".

8. Set TypoScript constants

   The following can be done in the TYPO3 backend in the TypoScript Module (as shown in the video) or better in your own sitepackage (which is preferred because it is under source control).

   See also Base Configuration.

   EXT:sitepackage/Configuration/TypoScript/constants.typoscript

   plugin.tx_cart.settings {
       cart {
           pid = # The PID of the page "Cart".
           isNetCart = # 0 or 1, depending on your needs.
       }
       order.pid = # The PID of the page "Orders".
   }

   Copied!

9. Set needed TypoScript setup

   You should set in your sitepackage/Configuration/TypoScript/setup.typoscript fitting values for:

   • email
   • payments
   • shippings
   • currencies (only needed when not only using €),

10. Link for consent checkboxes in the cart

    EXT:sitepackage/Configuration/TypoScript/constants.typoscript

    plugin.tx_cart.settings.cart {
        acceptTermsAndConditions.pid = # The PID of your terms and conditions page.
        acceptRevocationInstruction.pid = # The PID of your revocation instructions page.
        acceptPrivacyPolicy.pid = # The PID of your privacy policy page
    }

    Copied!

11. Create a product

    

    

    • Go to the page Product Storage, switch to the backend module "List".
    • Click on + Create a new record → Product for a product which is given from the database extension (which is EXT:cart_products in this quick start).
    • Fill in necessary product data and save.

12. Done

    You should now be able to see the product in the frontend and make an order.

Install the extension

Depending on your needs you have three options to install the extension.

composer require extcode/cart

git clone git@github.com:extcode/cart.git

Include TypoScript

The extension ships some TypoScript code which needs to be included. There are two valid ways to do this:

plugin.tx_cart.settings

plugin.tx_cart.settings.cart

plugin.tx_cart.settings.validation.orderItem.fields

Available validation options

The following examples show the available configuration options. The examples use the field salutation of the invoice address.

plugin.tx_cart.settings.validation.billingAddress.fields {
    salutation.validator = NotEmpty
}

plugin.tx_cart.settings.validation.billingAddress.fields {
    salutation.validator = Empty
}

plugin.tx_cart.settings.validation.billingAddress.fields {
    # !!! It is necessary to remove the whole address field,
    #     not only the `validator` configuration.
    salutation >
}

plugin.tx_cart.settings.showCartAction.showPartials

Currency Format

To make the templates a bit easier to use, TypoScript can be used to configure the format specifications for the price output. These TypoScript specifications are then used in the <cart:format.currency> ViewHelper.

plugin.tx_cart {
    settings {
        format {
            currency {
                currencySign       = €
                decimalSeparator   = ,
                thousandsSeparator = .
                prependCurrency    = false
                separateCurrency   = true
                decimals           = 2
            }
        }
    }
}

Currency Translation

If you want to allow the user to display the prices in a different currency in the store, you can configure this via TypoScript.

plugin.tx_cart {
    settings {
        currencies {
            preset = 1
            options {
                1 {
                    code = EUR
                    sign = €
                    translation = 1.00
                }
            }
        }
    }
}

plugin.tx_cart.mail

plugin.tx_cart.mail

Define which numbers are generated

plugin.tx_cart {
    settings {
        autoGenerateNumbers = order
    }
}

Format configuration

Order, invoice and delivery note numbers are created by EventListeners and stored at the order. These can be configured and thus customized via options when registering the EventListeners.

The options offer the possibility to

• add a prefix to the number,
• add suffix to the number,
• give an offset to let the first number start at e.g. 10001.
• define how many leading zeros should be used in the order number.

The respective counter is stored and updated in the sys_registry-table.

The configuration via the options is the same for all numbers using the generateNumber() method from the \Extcode\Cart\EventListener\Order\Create\Number.

services:

  Extcode\Cart\EventListener\Order\Create\OrderNumber:
    arguments:
      $persistenceManager: '@TYPO3\CMS\Extbase\Persistence\Generic\PersistenceManager'
      $options:
        prefix: 'DEMO-'
        suffix: '-SHOP'
        offset: 10000
        format: "%09d"
    tags:
      - name: event.listener
        identifier: 'cart--order--create--order-number'
        event: Extcode\Cart\Event\Order\NumberGeneratorEvent
        after: 'cart--order--create--order'

Let's assume that the current counter for the order number is 23. The generated order number would look like this: DEMO-000010023-SHOP.

Configuration given by this extension

plugin.tx_cart {
    settings {
        countries {
            preset = 1
            options {
                1 {
                    code = de
                    label = Deutschland
                }
                2 {
                    code = at
                    label = Österreich
                }
                3 {
                    code = ch
                    label = Schweiz
                }
            }
        }
    }

    payments {
        countries {
            de {
                preset = 1
                options {
                    1 {
                        title = Vorkasse
                        extra = 0.00
                        taxClassId = 1
                        status = open
                    }
                }
            }
            at < .de
            ch < .de
        }
    }
}

Country configuration

Zone configuration

plugin.tx_cart {
    payments {
        zones {
            1 {
                preset = 1
                countries = de,at,ch
                options {
                    1 {
                        title = Vorkasse
                        extra = 0.00
                        taxClassId = 1
                        status = open
                    }
                }
            }
        }
    }
}

Deactivate payment methods

At the moment, the existence of a payment method is required for the processing of an order. That means that at least one payment method must be specified. In this case the selection block for the payment can be hidden.

plugin.tx_cart {
     settings {
         showCartAction {
             showPartials {
                paymentMethodForm = false
             }
         }
     }
}

See plugin.tx_cart.settings.showCartAction.showPartials.paymentMethodForm

Configuration given by this extension

plugin.tx_cart {
    settings {
        countries {
            preset = 1
            options {
                1 {
                    code = de
                    label = Deutschland
                }
                2 {
                    code = at
                    label = Österreich
                }
                3 {
                    code = ch
                    label = Schweiz
                }
            }
        }
    }

    shippings {
        countries {
           de {
               preset = 1
               options {
                   1 {
                       title = Standard
                       extra = 0.00
                       taxClassId = 1
                       status = open
                   }
               }
           }
           at < .de
           ch < .de
        }
    }
}

Country Configuration

plugin.tx_cart {
    shippings {
        countries {
           de {
               options {
                   2 {
                       free {
                           from = 50
                           until = 100
                       }
                       available {
                           from = 20
                           until = 200
                       }
                       fallBackId = 1
                   }
               }
           }
        }
    }
}

Zone configuration

plugin.tx_cart {
    shippings {
        zones {
            1 {
                preset = 1
                countries = de,at,ch
                options {
                    1 {
                        title = Standard
                        extra = 0.00
                        taxClassId = 1
                        status = open
                    }
                }
            }
        }
    }
}

Deactivate shipping methods

At the moment, the existence of a shipping method is required for the processing of an order. That means that at least one shipping method must be specified. In this case the selection block for the payment can be hidden.

plugin.tx_cart {
     settings {
         showCartAction {
             showPartials {
                shippingMethodForm = false
             }
         }
     }
}

See plugin.tx_cart.settings.showCartAction.showPartials.shippingMethodForm

plugin.tx_cart.shipping.countries.de

plugin.tx_cart {
    shippings {
        countries {
           de {
               preset = 1
               options {
                   1 {
                       title = Standard
                       className = \\MyVendor\\MyExtension\\MyShippingService
                       taxClassId = 1
                       status = open
                   }
               }
           }
        }
    }
}

plugin.tx_cart.settings.search

plugin.tx_cart.settings

Product Database / Product Storages

Cart itself doesn't provide any product database or product storage.

You can use your own product table or one of the given product extensions which are adapted for special use cases.

Payment solutions

List of events

The following events exists:

How to listen for events

Every event comes with a detail object which contains data relevant for this specific event.

The following example shows how to listen for an event.

document.addEventListener("extcode:country-updated", (event) => {
  console.log("The event 'extcode:country-updated' was fired.");
  console.log("The event contains the following detail data:");
  console.log(event.detail);
});

Known Problems

• Creating a voucher of type "percentage" requires at the moment the definition of a tax class although this is not logical. That has historical reasons, see Feature 392 Add Percentage Discount.
• There might be bugs if the fixed discount is bigger than the cart amount.

Plugin "Cart: Cart"

This plugin shows the current status of the cart, the products it contains and the form to complete the order.

Plugin "Cart: Mini Cart"

This plugin can be included as mini cart and gives a shortened view of the cart.

For an example of an implementation see Integrate a MiniCart.

Plugin "Cart: Orders"

A logged in frontend user can see the orders with the help of this plugin. The plugin offers a list view and a detail view.

Breaking

Description

extcode/cart itself doesn't need any code from typo3/cms-form.

This extension provide an itemProcFunc to provide a list of the form definition for a selector filtered by a given prototype. This extension provide an AddToCartFinisher which extends the AbstractFinisher of typo3/cms-form.

Both classes can be used by product extensions, but are not used by extcode/cart itself.

To achieve this, the part concerning the form definitions had to be moved to a separate class \Extcode\Cart\Hooks\FormDefinitions.

Affected Installations

Own product extensions that link products with form_definitions and have used the itemProcFunc ‘Extcode\Cart\Hooks\ItemsProcFunc->user_formDefinition’ in the TCA.

Migration

Replace

'itemsProcFunc' => 'Extcode\\Cart\\Hooks\\ItemsProcFunc->user_formDefinition',
'itemsProcFuncConfig' => [
    'prototypeName' => 'cart-events',
],

with

'itemsProcFunc' => \\Extcode\\Cart\\Hooks\\FormDefinitions::class . '->getItems',
'itemsProcFuncConfig' => [
    'prototypeName' => 'cart-events',
],

Features

Description

Currency conversion is currently very strongly linked to the cart model and the way in which the currency conversion factor is loaded from TypoScript.

In order to be able to obtain the conversion factor from other sources, the calculation is carried out by the CurrencyTranslationService. This service is instantiated via the CurrencyTranslationServiceInterface interface so that a corresponding exchange via DI is possible.

The implementation should only be a start and does not yet offer a stable API because the behaviour must remain the same within the published versions. For this reason, the CurrencyTranslationServiceInterface is marked as @internal. Use is at your own risk! Changes to the service interface must be observed independently in the event of updates!

Impact

No direct impact.

Features

Description

To make the extension even more flexible, only the interfaces for Products and BeVariants are to be used in the shopping cart. This makes it easier to replace them with your own implementations of the interfaces. Furthermore, for Products, BeVariants and FeVariants corresponding Factories and FactoryInterfaces should offer the possibility to customize the products in the shopping cart even easier with own Factories.

Impact

No direct impact. XCLASSing for products, BeVariants and FeVariants should no longer be necessary. Instead, separate classes should implement the corresponding interfaces.

Breaking

Features

Description

Previously, a BeVariant had either another BeVariant or a Product as its parent element. These were passed in the constructor method.

Thanks to PHP's union types, this can now be resolved. A BeVariant now has a $parent that is either of type BeVariant or of type Product.

The individual methods have been adapted accordingly and it is checked of which class $parent is an instance. In some cases, the case differentiation could be omitted completely.

Affected Installations

All product extensions that use their own BeVariant in the products are affected. The provided extensions extcode/cart-products and extcode/cart-events will be adapted accordingly.

Migration

If a custom product extension is used, the constructor must be adapted accordingly. Furthermore, a few methods in BeVariant have been replaced or their behavior adapted.

Features

Description

The default FeVariant implementation cannot have a price. In order to be able to process own FeVariants with a price, the method arguments should use a FeVariantInterface instead.

The FeVariantWithPriceInterface extends the FeVariantInterface with a getPrice() method. The price calculation of a product then takes into account whether the FeVariant implements the FeVariantWithPriceInterface to add this price as well.

To create an own FeVariant for a Product, you have to replace the CreateCartFrontendVariants EventListener.

Extcode\CartProducts\EventListener\Create\CreateCartFrontendVariants: null

MyVendor\MyExtension\EventListener\Create\CreateCartFrontendVariants:
  tags:
    - name: event.listener
      identifier: 'cart-products--create--create-cart-frontend-variants'
      event: Extcode\CartProducts\Event\RetrieveProductsFromRequestEvent
      after: 'cart-products--create--load-product'

This is very flexible. You can implement FeVariants as checkboxes and add some surcharge for some options. Another idea is to calculate the price markup depending on the number of characters entered.How you can use this is up to you. However, you should test carefully whether the price calculation for the product price then fits, especially if you use more than one front-end variant with a price for a product.

Impact

No Impact.

Breaking

Description

Tests with newer versions of phpstan under newer php versions showed that the constructor method \Extcode\Cart\Domain\Model\Cart\BeVariant::__construct() uses required method parameters after optional parameters. This is deprecated since. PHP 8.0. (see https://php.watch/versions/8.0/deprecate-required-param-after-optional)

As this may lead to an error in a later PHP version, compatibility is restricted to PHP 8.1-8.4.

Affected Installations

All installations.

Migration

This restriction currently has no effect. No migration is necessary.

Features

Description

Adding your own buttons to the backend module is not so easy in controllers. In order to extend or replace the CSV export with an XML export, you need a way to insert your own buttons if you do not want to develop your own backend module.

The OrderController for the administration in the backend has been extended by the \Extcode\Cart\Event\Template\Components\ModifyButtonBarEvent. The buttons in the OrderController have been moved to the \Extcode\Cart\EventListener\Template\Components\ModifyButtonBar EventListener, which uses this event to decide which buttons should be displayed in which action based on the request.

Custom buttons can use the methods getRequest(), getSettings(), getSearchArguments() and in the case of the showAction also getOrderItem() to retrieve all the necessary information to insert custom buttons for custom tasks.

Impact

No impact is expected as only private methods have changed.

Description

Adding your own data to module templates is not so easy. In order to assign own data to the moduleTemplate, you need a way to assign your own data if you do not want to develop your own backend module.

The \Extcode\Cart\Event\Template\Components\ModifyModuleTemplateEvent event is dispached in the OrderController for the backend module.

An own EventListener can use the methods getRequest(), getSettings(), getModuleTemplate() to retrieve all the necessary information to assign custom data. The request object can be used to assign data for specific actions.

Impact

No impact is expected.

Description

Adding your own data to plugin templates is not so easy. In order to assign own data to the view, you need a lib in TypoScript and a f:cObject in the template with some JavaScript on top.

This \Extcode\Cart\Event\View\ModifyViewEvent event is dispached in all actions for which an output is generated via a template. Actions that are forwarded to another action do not require the event.

An own EventListener can use the methods getRequest(), getSettings(), getView() to retrieve all the necessary information to assign custom data. The request object can be used to assign data for specific actions. For example, saved addresses of a returning logged-in user can be displayed for selection instead of the form for the billing address.

Impact

No impact is expected.

Breaking

Features

Description

Using the jQuery library is outdated. Therefore jQuery in the existing JavaScript code is replaced with vanilla JavaScript. Furthermore is the JavaScript code splitted up and via [Asset Viewhelper](https://docs.typo3.org/other/typo3/view-helper-reference/12.4/en-us/typo3/fluid/latest/Asset/Script.html) included in the templates and partials where the corresponding JavaScript is needed.

For better development of the JavaScript a build process is added, using [esbuild](https://esbuild.github.io/). The original JavaScript files are now located in Build/Sources/ where you can find further information how to work with these files during development.

Affected Installations

Installations which use the default templates and partials from the extension just do no longer need to include jQuery. Installations which have individualized templates or partials might need to adapt templates or partials.

Migration

1. Remove old JavaScript It is no longer necessary to include jQuery for this extension.

The old JavaScript file /Resources/Public/JavaScripts/cart.js does no longer exist. If it was included in some JavaScript bundling then it must be removed.

2. Migrate to new JavaScript If you have individual templates and/or partials than you can migrate in two ways:

2. ALTERNATIVE A: Add JavaScript via TypoScript The easier but less performant migration is to include all JavaScript files with TypoScript, e.g. as follows:

page.includeJSFooter {
    tx_cart_add_to_cart = EXT:cart/Resources/Public/JavaScript/add_to_cart.js
    tx_cart_change_be_variant = EXT:cart/Resources/Public/JavaScript/change_be_variant.js
    tx_cart_prevent_multi_submit = EXT:cart/Resources/Public/JavaScript/prevent_multi_submit.js
    tx_cart_update_country = EXT:cart/Resources/Public/JavaScript/update_country.js
    tx_cart_update_currency = EXT:cart/Resources/Public/JavaScript/update_currency.js
    tx_cart_update_payment_shipping = EXT:cart/Resources/Public/JavaScript/update_payment_shipping.js
}

2. ALTERNATIVE B: Add JavaScript via Asset Viewhelper The more performant way requires more job some job in your partials and templates. Even templates of extensions like e.g. EXT:cart_products are affected.

It's necessary to include the [asset viewhelpers](https://docs.typo3.org/other/typo3/view-helper-reference/12.4/en-us/typo3/fluid/latest/Asset/Script.html) as they are included in the updated partials and templates.

The following partials are affected:

• Resources/Private/Partials/Cart/CouponForm.html → includes EXT:cart/Resources/Public/JavaScript/prevent_multi_submit.js
• Resources/Private/Partials/Cart/CurrencyForm.html → includes EXT:cart/Resources/Public/JavaScript/update_currency.js
• Resources/Private/Partials/Cart/OrderForm.html → includes EXT:cart/Resources/Public/JavaScript/prevent_multi_submit.js
• Resources/Private/Partials/Cart/OrderForm/Address/Shipping.html → includes EXT:cart/Resources/Public/JavaScript/update_country.js
• Resources/Private/Partials/Cart/OrderForm/PaymentMethod.html → includes EXT:cart/Resources/Public/JavaScript/update_payment_shipping.js
• Resources/Private/Partials/Cart/OrderForm/ShippingMethod.html → includes EXT:cart/Resources/Public/JavaScript/update_payment_shipping.js
• Resources/Private/Partials/Cart/ProductForm.html → includes EXT:cart/Resources/Public/JavaScript/prevent_multi_submit.js

The following templates are affected:

• Resources/Private/Templates/Cart/ShowStep2.html → includes EXT:cart/Resources/Public/JavaScript/prevent_multi_submit.js and EXT:cart/Resources/Public/JavaScript/update_country.js
• Resources/Private/Templates/Cart/ShowStep3.html → includes EXT:cart/Resources/Public/JavaScript/prevent_multi_submit.js
• Resources/Private/Templates/Cart/ShowStep4.html → includes EXT:cart/Resources/Public/JavaScript/prevent_multi_submit.js
• Resources/Private/Templates/Currency/Edit.html → includes EXT:cart/Resources/Public/JavaScript/update_currency.js

3. Update HTML

3.a) Replace inline JavaScript with hidden div (in another file) The inline JavaScript in your overrides of Resources/Private/Templates/Cart/Show.html can be removed, instead a hidden div has to be added in your overrides of Resources/Private/Partials/Cart/OrderForm/Address/Shipping.html

Remove the following script from your overrides of Resources/Private/Templates/Cart/Show.html and from Resources/Private/Templates/Cart/Cart/ShowStep2.html

## Delete the following in Resources/Private/Templates/Cart/Show.html and Resources/Private/Templates/Cart/Cart/ShowStep2.html
<script type="text/javascript">
    var update_country = '<f:format.raw><f:uri.action controller="Cart\Country" action="update" pageType="2278001"/></f:format.raw>';
</script>

Add the following div in your overrides of Resources/Private/Partials/Cart/OrderForm/Address/Shipping.html

## in Resources/Private/Partials/Cart/OrderForm/Address/Shipping.html
<div hidden data-ajax-update-country-action-url="{f:uri.action(controller: 'Cart\Country', action: 'update', pageType: '2278001') -> f:format.raw()}"></div>

3.b) Move checkbox for shipping address to partial The checkbox in the order form where the customer can choose whether billing and shipping address differ moved into a partial. `Resources/Private/Partials/Cart/OrderForm/Address/Shipping.html

Delete the following from your overrides of Resources/Private/Partials/Cart/OrderForm.html and Resources/Private/Templates/Cart/Cart/ShowStep2.html.

<div class="form-list shipping-same-as-billing-wrapper">
    <div class="control">
        <label for="shipping-same-as-billing">
            <f:form.checkbox property="shippingSameAsBilling"
                             id="shipping-same-as-billing"
                             value="1"
                             title="{f:translate(key:'tx_cart.same_address')}"
                             additionalAttributes="{f:if(condition:'{cart.shippingSameAsBilling}', then: '{checked: \'checked\'}')}"/>
            <span><f:translate key="tx_cart.same_address"/></span>
        </label>
    </div>
</div>

Add in your override of Resources/Private/Partials/Cart/OrderForm/ShippingMethod.html

<div class="form-list shipping-same-as-billing-wrapper">
    <div class="control">
        <label for="shipping-same-as-billing">
            <f:form.checkbox property="shippingSameAsBilling"
                             id="shipping-same-as-billing"
                             value="1"
                             title="{f:translate(key:'tx_cart.same_address')}"
                             additionalAttributes="{f:if(condition:'{cart.shippingSameAsBilling}', then: '{checked: \'checked\'}')}"/>
            <span><f:translate key="tx_cart.same_address"/></span>
        </label>
    </div>
</div>

4. Adapt JS in templates of other extensions (only needed when you chose step 2 ALTERNATIVE B) above) When using EXT:cart_products you need also to adapt /Resources/Private/Partials/Product/CartForm.html: You need to insert the following viewHelper:

<f:asset.script identifier="add-to-cart" src="EXT:cart/Resources/Public/JavaScript/add_to_cart.js" />
<f:asset.script identifier="change-be-variant" src="EXT:cart/Resources/Public/JavaScript/change_be_variant.js" />

Other extension which use a similar CartForm.html needs the same adaption.

Description

Up to now it was possible to set the country specific configuration of shippings and payments directly under plugin.tx_cart.shippings and plugin.tx_cart.payments. Until the implementation of forge#435 that's how it was done in the extension itself although the documentation already showed the new structure.

This breaking change does no longer allow the old structure. As a result the structure to set options is uniform in different places which makes it easier for Integrators to set up this extension.

The uniform structure are now given for options in:

• plugin.tx_cart.shippings - see below
• plugin.tx_cart.payment - see below
• plugin.tx_cart.settings.countries - see Breaking 437 (Allowed Countries)
• plugin.tx_cart.settings.currencies - see Breaking 437 (Currency)

Affected Installations

All installations which use the old structure ()which is shown below in the migration description) are affected. The TypoScript needs to be adapted as shown below.

Migration

The country configuration needs to be wrapper in a countries level.

The following two snippets show the BEFORE and AFTER implementation.

plugin.tx_cart {
   shippings {
      de {
         preset = 1
         options {
            1 {
               title = Standard
               extra = 0.00
               taxClassId = 1
               status = open
            }
         }
      }
   }
   payments {
      de {
         preset = 1
         options {
            1 {
               title = Pay in advance
               extra = 0.00
               taxClassId = 1
               status = open
            }
         }
      }
   }
}

plugin.tx_cart {
   shippings {
      countries {
         de {
             preset = 1
             options {
                 1 {
                     title = Standard
                     extra = 0.00
                     taxClassId = 1
                     status = open
                 }
              }
           }
        }
     }
   }
   payments {
       countries {
          de {
             preset = 1
             options {
                1 {
                   title = Pay in advance
                   extra = 0.00
                   taxClassId = 1
                   status = open
                }
             }
          }
       }
   }
}

Description

In Fluid, the SelectViewHelper has been changed to a final class so that the custom SelectViewHelper cannot extend it. Since the ViewHelper was only used in one place in the order form to output the countries configured in the TypoScript, the extended ViewHelper is removed.

Affected Installations

All installations are affected by this change.

Migration

If the selection of countries in the billing or shipping address needs to be translated, this can be solved using a separate partial. Instead of generating the list of options via the ViewHelper, the ViewHelper can also be used with custom options (see: Custom options and option group rendering). Since it is an array, the options can be inserted by iterating over all elements of the array and translating them with <f:translate>.

Description

Signal slots have been removed in TYPO3 v12. These have been replaced by EventListeners where possible. The extension offered following signal slots:

• updateCountry in \Extcode\Cart\Utility\CartUtility
• updateCurrency in \Extcode\Cart\Utility\CurrencyUtility
• addProductAdditionalData, addBeVariantAdditionalData, and changeOrderItemBeforeSaving in \Extcode\Cart\Utility\OrderUtility

Affected Installations

All installations that used the signal slots to programmatically adjust the behavior of the extension are affected.

Migration

• updateCountry in \Extcode\Cart\Utility\CartUtility can replaced with \Extcode\Cart\EventListener\Cart\UpdateCountry.
• updateCurrency in \Extcode\Cart\Utility\CurrencyUtility can replaced with \Extcode\Cart\EventListener\Cart\UpdateCurrency.
• addProductAdditionalData, addBeVariantAdditionalData, and changeOrderItemBeforeSaving in \Extcode\Cart\Utility\OrderUtility was used only directly in \Extcode\Cart\EventListener\Order\Create\Order. This class now dispatch the new \Extcode\Cart\Event\Order\PersistOrderEvent. Overwriting \Extcode\Cart\Utility\OrderUtility or using the signal slots of this class should thus be superfluous and can be replaced by your own EventListener. For more information check out the event documentation in the developer section.

Description

The extension does not use the ViewHelper for variables. In TYPO3 a ViewHelper is available for setting and reading variables. So the own implementation can be removed without disadvantages.

Affected Installations

All installations using \Extcode\Cart\ViewHelpers\Variable\GetViewHelper or \Extcode\Cart\ViewHelpers\Variable\SetViewHelper in templates or partials.

Migration

Replace all occurrences in the templates.

Description

In order to streamline the TypoScript configuration the configuration for allowedCountries was changed.

Affected Installations

All installations using an own configuration for plugin.tx_cart.setting.allowedCountries or override the Resources/Private/Partials/Cart/OrderForm/Address/Billing.html or Resources/Private/Partials/Cart/OrderForm/Address/Shipping.html partial.

Migration

plugin.tx_cart {
    settings {
        allowedCountries {
            de = Deutschland
            at = Österreich
            ch = Schweiz
        }
        defaultCountry = de
    }
}

plugin.tx_cart {
    settings {
        countries {
            preset = 1
            options {
                1 {
                    code = de
                    label = Deutschland
                }
                2 {
                    code = at
                    label = Österreich
                }
                3 {
                    code = ch
                    label = Schweiz
                }
            }
        }
    }
}

Description

Rendering the currency selector renders the default = 1 from TypoScript as an own option. Using a preset and an list of options like in shipping and payment configuration will fix this bug.

Affected Installations

All installations using an own configuration for plugin.tx_cart.setting.currencies or override the Resources/Private/Partials/Cart/CurrencyForm.html partial.

Migration

plugin.tx_cart {
    settings {
        currencies {
            default = 1
            1 {
                code = EUR
                sign = €
                translation = 1.00
            }
        }
    }
}

plugin.tx_cart {
    settings {
        currencies {
            preset = 1
            options {
                1 {
                    code = EUR
                    sign = €
                    translation = 1.00
                }
            }
        }
    }
}

Description

All fields which exists for the billing address and for the shipping address are now included within the validation array in TypoScript. The fields title, company, taxIdentificationNumber and country were not included. Including those fields makes it easier and especially more logic to manage the validation and visibility of those fields.

Affected Installations

By default the fields title, company and taxIdentificationNumber will not be rendered, the field country will be rendered and required.

Migration

See Validating and hiding fields how to manage the visibility and validation of address fields.

Description

The changeVariantDiscount Hooks have been removed. Cart will not provide a replacement.

Affected Installations

All installations that used the hooks to programmatically adjust the behavior of the extension are affected.

Migration

Override the BeVariant class by implementing the BeVariantInterface.

Description

Existing Hooks have been removed. They were replaced by EventListeners. The extension offered following hooks:

• showCartActionAfterCartWasLoaded in \Extcode\Cart\Controller\Cart\CartController
• AddToCartFinisher in \Extcode\Cart\Domain\Finisher\Form\AddToCartFinisher
• MailAttachmentHook in \Extcode\Cart\Service\MailHandler

Affected Installations

All installations that used the hooks to programmatically adjust the behavior of the extension are affected.

Migration

• showCartActionAfterCartWasLoaded in \Extcode\Cart\Controller\Cart\CartController now needs to listen to the event \Extcode\Cart\Event\Cart\BeforeShowCartEvent
• AddToCartFinisher in \Extcode\Cart\Domain\Finisher\Form\AddToCartFinisher now needs to listen to the event \Extcode\Cart\Event\Form\AddToCartFinisherEvent
• MailAttachmentHook in \Extcode\Cart\Service\MailHandler now needs to listen to the event \Extcode\Cart\Event\Mail\AttachmentEvent

Description

The language files contained a bigger amount of unused entries and their domains were not really clear. Some entries were renamed to clarify their usage in the backend.

Affected Installations

Installations which overwrite backend labels might be affected.

Migration

You need to check whether the key of your overwrite was changed and adapt it.

Description

The existing TitleTagViewHelper was removed because it stopped working after TYPO3 v10. The new ViewHelper adds the same functionality but its usage is different.

Affected Installations

The ViewHelper was not used in EXT:cart itself. But other extensions as e.g. EXT:cart_products used it. Overwrites and own implementations of templates which used <cart:titleTag> need adaption.

Migration

Migrate the old usage of the ViewHelper as shown below

<!-- OLD IMPLEMENTATION -->
<cart:format.nothing>
    <cart:titleTag>
        <f:format.htmlentitiesDecode>{product.title}</f:format.htmlentitiesDecode>
    </cart:titleTag>
</cart:format.nothing>

<!-- NEW IMPLEMENTATION -->
<cart:titleTag pageTitle="{product.title}" />

Description

The existing \Extcode\Cart\Utility\ParserUtility::parseTax() uses a TaxClassService which could be configured by a TypoScript Configuration. The change remove the method from the class and injecting the Extcode\Cart\Service\TaxClassServiceInterface by Dependency Injection.

Affected Installations

All installations where plugin.tx_cart.taxClasses.className is used to replace the default TaxClassService.

Migration

Remove the old configuration from TypoScript. Add an entry to your Services.yaml or Services.php and configure your implementation of the Extcode\Cart\Service\TaxClassServiceInterface for the $taxClassService constructor argument.

Description

The existing \Extcode\Cart\Utility\ParserUtility::parseServices() used a a TypoScript Configuration to allow to use an own implementation to parse and provide available payment and shipping methods or special options. The change removes the ParserUtility class and injecting the following services: - \Extcode\Cart\Service\PaymentMethodsServiceInterface, - \Extcode\Cart\Service\ShippingMethodsServiceInterface, - \Extcode\Cart\Service\SpecialOptionsServiceInterface instead.

Affected Installations

All installations where - plugin.tx_cart.payments.className, - plugin.tx_cart.shippings.className, - plugin.tx_cart.specials.className are used to replace the default services.

Migration

Remove the old configuration from TypoScript. Add an entry to your Services.yaml or Services.php and configure your implementation of the service interface for the constructor arguments.

Description

It is now possible to define names which will be used when sending emails. These names will be shown to the customer and shop owner when receiving mails. Before only the email address was shown.

Impact

Negative effects are not expected. No adding the names will just have the same result as before.

As with all the other mail settings those in the plugin take precedence.

Migration

See also the documentation for email addresses.

 plugin.tx_cart {
    mail {
        // Used for emails sent to the customer (=buyer)
        buyer {
            fromName = Your Brand name
            // the other settings as shown in the documentation
        }

        // Used for emails sent to the shop owner (=seller)
        seller {
            fromName = Cart TYPO3 System
            // the other settings as shown in the documentation
        }
    }
}

Description

When a customer wants to send an order the Classes/Event/ProcessOrderCheckStockEvent.php is called. This Event existed already before but with limited functionality. The purpose of this Event is to allow product extensions (e.g. EXT:cart_products) to cancel the order process if any product in the order is insufficient in stock. This means it's only working if stock handling is enabled.

With this feature the functionality of ProcessOrderCheckStockEvent is extended:

• EventListener can set a flag that not every product of the order that a customer wants to make are available ( setNotEveryProductAvailable()).
• EventListener can add custom messages to the Event, e.g. for every product which is not available.

The Classes/Controller/Cart/OrderController.php takes the flag and the messages into account: If the flag is true (= not every product is available) it will add the messages as flash messages queue and redirect back to the cart. This means the order form is rendered again with the flash messages. An example for an EventListener will be introduced in EXT:cart_products.

Impact

This change should not have any negative impact. Your product extensions can now implement an EventListener which listens to the ProcessOrderCheckStockEvent to add messages about products which are insufficient amount in your stock. An example for such a EventListener will be added to EXT:cart_products.

Description

Products can have several features like categories and tags or files and images and some more. To ease the domain models in the extcode/cart-books, extcode/cart-events, and extcode/cart-products the extcode/cart extension provides some Traits.

• \Extcode\Cart\Domain\Model\Product\CategoryTrait
• \Extcode\Cart\Domain\Model\Product\FileAndImageTrait
• \Extcode\Cart\Domain\Model\Product\MeasureTrait
• \Extcode\Cart\Domain\Model\Product\ServiceAttributeTrait
• \Extcode\Cart\Domain\Model\Product\StockTrait
• \Extcode\Cart\Domain\Model\Product\TagTrait

Impact

Negative effects are not expected. The traits can also be used in own product extensions. With the use it is to be made certain that the __construct method is not called and in the class, which uses appropriate Traits then the ObjectStorages must initialize themselves.

Description

The backend module was refactored. The dateformat of the date input fields can be set in TypoScript.

plugin.tx_cart {
    settings {
        backend {
           dateFormat = Y-m-d
        }
    }
}

Impact

Before this the dates in the backend were always in the format d.m.Y, now it

is Y-m-d by default. The change affect only the formatting in the backend, not the storage format.

Migration =========

To get the old formatting you need to overwrite the above shown TypoScript constants:

EXT:sitepackage/Configuration/TypoScript/constants.typoscript

plugin.tx_cart {
    settings {
        backend {
           dateFormat = d.m.Y
        }
    }
}

Copied!

Description

The view of the backend module were refactored. This has the following benefits:

• No inline CSS which avoid problems with Content-Security-Policies.
• Clearer design.
• Responsive design (old design was not usable on smartphones).
• Order tables with colors to improve the visibility of status of orders.
• Backend CSS reduced / updated to really used HTML.

Impact

Own overwrites might need adaption otherwise this change should not have any negative impact.

Important

Description

In the OrderForm.html partial the the value of the checkbox should not depend on the shippingSameAsBilling property of the shopping cart. This property should only be responsible for the checkbox.

Affected Installations

This affects all installations overriding the OrderForm.html.

Migration

Replace the fluid condition of the value attribute with the value 1.

Features

Deprecation

Description

An important feature, which was frequently requested, are coupons that allow a percentage discount. Now there is a first implementation. This introduces a new voucher type. Percentage vouchers are currently not combinable with other vouchers on the shopping cart, because with the currently available fixed voucher values, the order of calculation would be crucial.

Impact

The current implementation still requires the configuration of the tax class. This makes sense for vouchers with a fixed amount. For percentage discount vouchers, the tax is of course also calculated on a percentage basis. Nevertheless, a tax class must be selected in the backend, which is then ignored in the calculation.

Only with the next major release for TYPO3 v12 and v11, the breaking change can be made here and the tax class becomes an optional specification and can then also be handled accordingly in the TCA.

If only percentage vouchers are used in the store, there is the possibility to hide and preset the fields accordingly in the backend. In stores, in which there should be both types of vouchers, the editors who can create vouchers, are to be trained.

Sponsors

Liebman Design Import e.K. would like to offer customers percentage vouchers on toys after relaunching the shop with TYPO3 v11.

SEITENFORMATE, Agentur für Kommunikationsdesign would like to implement percentage discount vouchers for an event booking shop for special registered customers.

Description

In order to be able to implement custom voucher types, the voucher type selection will no longer contain a string, but the class that implements that voucher. This requires some changes to the \Extcode\Cart\Domain\Model\Cart\CouponInterface, which are not finalized at this point.

What is certain is that there will be a defined constructor method. Also the method getTax() will be dropped and instead there will be a method getTaxes() which has to return an array instead of a float value. For custom coupons implementing the \Extcode\Cart\Domain\Model\Cart\CartCouponInterface or overriding the existing implementation, adaptations have to be planned with the upgrade to version v9 for TYPO3 v12 and v11.

Furthermore there will be an upgrade wizard, which replaces the existing string "cartcoupon" in the coupon_type against the class \Extcode\Cart\Domain\Model\Cart\CouponFix.

Impact

Features

Description

Some customers have additional address data, which enables the supplier to deliver the shipment. To enable this directly, the new database field 'addition' for addresses was created and built into the partial. However, it is validated to Empty by default and is not output automatically. If you want to use it, you have to configure it via TypoScript. For more information check out the Validating and hiding fields documentation page.

Impact

No Impact.

Database compare required

The Feature adds a new column to the database. A database compare is required to add this new field.

Features

Description

Until now, the shopping cart and the ordering process were limited to one page. The new feature allows the ordering process to be stretched over several steps and so users can be guided through the ordering process. How many steps are used can be defined via a new TypoScript configuration variable. For each step, a template file must define the step. The extension brings an example of a 4-step checkout. For more information check out the Multi-Step Checkout documentation page.

Impact

No Impact.

Breaking Changes

Description

In TYPO3 v11 <f:paginate> has been removed and is implemented via the controller.

Affected Installations

All installations are affected by this change.

Migration

If the templates for the lists of orders in the frontend or backend have been overwritten, then these templates must also be adapted.

Description

The generation of order, invoice and delivery note numbers has been moved from Extcode\Cart\Utility\OrderUtility::class to its own EventListener. The generation is also no longer done via TypoScript and can also no longer be configured via TypoScript.

Affected Installations

All installations are affected by this change.

Migration

If the generation of order numbers via TypoScript has been configured individually (e.g. with prefix or suffix, offset, leading zeros), this configuration must be transferred to the registration of the service. On the Number Generator Configuration page is documented how this can be done. If other elements, such as the inclusion of or parts of the date, are used via TypoScript, this must be implemented via a separate EventListener.

Description

The configuration 'SplitUpProcessOrderCreateEvent' was removed. As a result, several events are now triggered one after the other when the order is placed in the frontend.

The current sequence of these events is:

• \Extcode\Cart\Event\Order\CreateEvent
• \Extcode\Cart\Event\Order\NumberGeneratorEvent
• \Extcode\Cart\Event\Order\FinishEvent
• \Extcode\Cart\Event\Order\PaymentEvent
• \Extcode\Cart\Event\Order\StockEvent

Thereby the \Extcode\Cart\Event\Order\NumberGeneratorEvent was added in this version and contains in this version the registered event cart--order--create--order-number which was previously contained in \Extcode\Cart\Event\Order\CreateEvent .

Affected Installations

This affects all installations that have not yet been switched via the FeatureToggle and have registered their own EventListeners on Extcode\Cart\Event\ProcessOrderCreateEvent. Furthermore, installations that have registered their own EventListeners on \Extcode\Cart\Event\Order\CreateEvent are affected.

Migration

In case the FeatureToggle was not activated, but no own EventListeners were registered, nothing has to be adjusted at all. The ordering process should be tested.

In case the FeatureToggle was not activated and own EventListeners were registered on Extcode\Cart\Event\ProcessOrderCreateEvent, the registered EventListeners are to be registered on the new events. The order process should be checked in any case.

In case the FeatureToggle was enabled and own EventListeners were registered to \Extcode\Cart\Event\Order\CreateEvent, check if these EventListeners must not be registered to \Extcode\Cart\Event\Order\NumberGeneratorEvent.

Features

Description

It is in the EventListeners

• ExtcodeCartEventOrderCreateEvent,
• ExtcodeCartEventOrderFinishEvent,
• ExtcodeCartEventOrderPaymentEvent,
• ExtcodeCartEventOrderStockEvent, and
• ExtcodeCartEventProcessOrderCreateEvent

possible to use the setSettings() method to change the settings for later EventListeners.

Impact

No Impact.

Features

Description

In germany and austria the tax for shipping is related to the products in cart. If you only have products with one tax class you are save, but if you sell books (reduced tax) and shirts (normal tax) the tax calculation for shipping use both tax classes. Percentage wise, the calculation of the tax is divided. The new version will add two options to TypoScript for taxClassId configuration. - taxClassId = -1 for simple calculation, where the tax rate of shipping is based on the highest tax rate in the shopping cart. - taxClassId = -2 option for the more complicated percentage calculation of the tax.

Impact

No Impact.

Affected Installations

No Installations are infected. There might be some issues on classes extending \Extcode\Cart\Domain\Model\Cart\Extra or \Extcode\Cart\Domain\Model\Cart\Service.

Features

Deprecation

Description

In order to better integrate the EventListener in connection with payment providers, the \Extcode\Cart\Event\ProcessOrderCreateEvent was split into several events. These implement a new EventInterface and also the \Psr\EventDispatcher\StoppableEventInterface.

The new events in the order of their dispatch:

• \Extcode\Cart\Event\Order\CreateEvent
• \Extcode\Cart\Event\Order\StockEvent
• \Extcode\Cart\Event\Order\PaymentEvent
• \Extcode\Cart\Event\Order\FinishEvent

The new events can be activated via a feature toggle in LocalConfiguration.php or AdditionalConfiguration.php:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['features']['SplitUpProcessOrderCreateEvent'] = true;

The cart extension itself currently registers \Extcode\Cart\EventListener\ProcessOrderCreate\Order and \Extcode\Cart\EventListener\ProcessOrderCreate\Order on \Extcode\Cart\Event\Order\CreateEvent. And the extension registers \Extcode\Cart\EventListener\ProcessOrderCreate\Email and \Extcode\Cart\EventListener\ProcessOrderCreate\ClearCart on \Extcode\Cart\Event\Order\FinishEvent.

The product extensions extcode/cart-products, extcode/cart-events, and extcode/cart-books will register the EventListeners to \Extcode\Cart\Event\Order\StockEvent.

The payment methods provider extensions should be registered to the \Extcode\Cart\Event\Order\PaymentEvent. These should return true for the isPropagationStopped() if the payment process cannot be completed immediately, to prevent sending emails and clearing the cart session directly. The emails and clearing cart is then the responsibility of the extension. Of course, the extension itself can send appropriate events and the EventListener from this extension can be registered to it.

Impact

If the feature toggle has been activated, the event \Extcode\Cart\Event\ProcessOrderCreateEvent will no longer be triggered. All EventListeners registered to this event must be registered to one of the new events.

Description

In order to better integrate the EventListener in connection with payment providers, the \Extcode\Cart\Event\ProcessOrderCreateEvent was split into several events. These implement a new EventInterface and also the \Psr\EventDispatcher\StoppableEventInterface.

The new events in the order of their dispatch:

• \Extcode\Cart\Event\Order\CreateEvent
• \Extcode\Cart\Event\Order\StockEvent
• \Extcode\Cart\Event\Order\PaymentEvent
• \Extcode\Cart\Event\Order\FinishEvent

The new events can be activated via a feature toggle in LocalConfiguration.php or AdditionalConfiguration.php:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['features']['SplitUpProcessOrderCreateEvent'] = true;

The cart extension itself currently registers \Extcode\Cart\EventListener\ProcessOrderCreate\Order and \Extcode\Cart\EventListener\ProcessOrderCreate\Order on \Extcode\Cart\Event\Order\CreateEvent. And the extension registers \Extcode\Cart\EventListener\ProcessOrderCreate\Email and \Extcode\Cart\EventListener\ProcessOrderCreate\ClearCart on \Extcode\Cart\Event\Order\FinishEvent.

The product extensions extcode/cart-products, extcode/cart-events, and extcode/cart-books will register the EventListeners to \Extcode\Cart\Event\Order\StockEvent.

The payment methods provider extensions should be registered to the \Extcode\Cart\Event\Order\PaymentEvent. These should return true for the isPropagationStopped() if the payment process cannot be completed immediately, to prevent sending emails and clearing the cart session directly. The emails and clearing cart is then the responsibility of the extension. Of course, the extension itself can send appropriate events and the EventListener from this extension can be registered to it.

Impact

If the feature toggle has been activated, the event \Extcode\Cart\Event\ProcessOrderCreateEvent will no longer be triggered. All EventListeners registered to this event must be registered to one of the new events.

Breaking Changes

Features

Description

The changeover from rendering an own standalone view to the FluidEmail class required adjustments in the email templates and partials.

Affected Installations

All installations that use their own templates and partials for the emails. All installations that use an own layout file for the emails.

Migration

To be able to use your own templates and parts, the folders where the files are located must be included via $GLOBALS['TYPO3_CONF_VARS']['MAIL']. The extension has included the following in the ext_localconf.php

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['templateRootPaths']['1588829280'] = 'EXT:cart/Resources/Private/Templates/';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['partialRootPaths']['1588829280'] = 'EXT:cart/Resources/Private/Partials/';

To ensure the correct order, the own key (UNIX timestamp) must be larger.

Furthermore you should compare your own templates and partials with those of the extension.

Description

Now that the extension has been changed to \TYPO3\CMS\Core\Mail\FluidEmail instead of \TYPO3\CMS\Core\Mail\MailMessage, the attachments have to be handled a bit differently. For this purpose, the first passed parameter and the return parameter have been changed to \TYPO3\CMS\Core\Mail\FluidEmail.