Migration Guide | CoreShop Upgrade from 2.2 to 3.0

[solverat]

Q	A
Bug report?	yes
Feature request?	no
BC Break report?	yes
RFC?	yes

This would be a great issue for discussion btw.

---

I'm going to publish my notes, which i gathered during the migration. Some steps are because of migration bugs, some of them are just notes which should be noted:

• I'll mark a Note with 💡
• I'll mark a Bug with 🪲

---

Variants

CoreShop 3 comes with a built-in variant system. There are some new properties in the project class, which are very generic: mainVariant, allowedAttributeGroups and attributes: If your object already comes with properties with the same name, you need to migrate them first!

Preparing

• 💡Make sure all your class definitions have set the generateTypeDeclarations flag set to true
• Remove methods from Interfaces (Otherwise you'll run into "..Class C** contains x methods.." ):
  • CoreShop\Component\Customer\Model\CustomerInterface:
    • (get|set)Company
  • CoreShop\Component\Customer\Model\CustomerAwareInterface:
    • (get|set)Customer
  • CoreShop\Component\Address\Model\DefaultAddressAwareInterface:
    • (get|set)DefaultAddress
  • CoreShop\Component\Core\Model\OrderInterface:
    • (get|set)NeedsRecalcuation
  • CoreShop\Component\Order\Model\OrderInterface:
    • (get|set)QuoteState
    • (get|set)SaleState
    • (get|set)QuoteNumber
  • CoreShop\Component\Taxation\Model\TaxItemInterface:
    • (get|set)TaxRate
  • CoreShop\Component\Core\Model\OrderItemInterface:
    • (get|set)UnitDefinition
  • CoreShop\Component\Pimcore\Slug\SluggableInterface:
    • (get|set)Slug
  • CoreShop\Component\Variant\Model\ProductVariantAwareInterface:
    • (get|set)MainVariant
    • (get|set)AllowedAttributeGroups
    • (get|set)Attributes
  • CoreShop\Component\Variant\Model\ProductVariantTrait:
    • getAttributes
• 💡Do core migration migrations
• 💡Set parent to "" in definition_CoreShopCart.php
• 💡Set parent to "" in definition_CoreShopCartItem.php
• 💡Set parent to "" in definition_CoreShopQuote.php
• 💡Set parent to "" in definition_CoreShopQuoteItem.php
• 💡Rebuild classes

Session Config

If you're using Offsite-Payments, make sure your cookie samesite setting is set to lax (#2168):

framework:
    session:
        cookie_samesite: 'lax'

Missing Migration Fields

• 🪲Field getNeedsRecalculation is missing in definition_CoreShopOrder.php
• 🪲Field unitdefinition is missing in definition_CoreShopOrderItem.php
• 🪲Field taxRate is missing in classes/fieldcollections/CoreShopTaxItem.php

Migration Issues

Version20200206155318

• ✅ 🪲 Use $user->setKey(Service::getValidKey($customer->getEmail(), 'object')); fixed via e3116c1

Version20200415153638

🪲If you're dealing with thousands of orders, this migration will fail because of memory issues. You need to add an GarbageCollector:

# [...]
$c = 0;
foreach ($batchList as $orderItem) {

    $c++;

    # [...]

    $xy->save();

    if ($c % 200 === 0) {
        \Pimcore::collectGarbage();
    }
}

Version20221118072640

🪲Same as in Version20200415153638

Version20200415154821

🪲Same as in Version20200415153638

---

Cart to Order Migration (Version20200415161210)

This is a heavy migration which I've cleared out. First, we have projects with hundreds of thousands of carts, so this migration would run forever. Second, there are some issues within the migration.

I would suggest moving this version to command.
However, if you want to migrate this version, there are some preparations:

Version Priority

Move Version to the end, otherwise the migration will fail because of missing fields:

• 🪲 rename Version20200415161210.php to Version20220824065815.php

• 💡Create messenger tablemessenger_messages (at least I had to do this?)

• 💡Create Cart and CartItem Model in App\CoreShop\Model (copy from an existing CS 2.2 project)

  • set parent to \App\CoreShop\Model\Cart in definition_CoreShopCart.php
  • set parent to \App\CoreShop\Model\CartItem in definition_CoreShopCartItem.php

---

Product

• 💡 Setter of mainProductId has been removed without any notes, see MainObjectId Setter  #2375

Layout Migration

• 💡Before running Version20220817144952.php, check if your definition has a layout called "numbers" (adjust, if not)
• 💡Before running Version20220503144151.php, check if your definition has a layout called "details"(adjust, if not)

Routes

• 💡🪲Change existing object link generator back to origin, they got changed during migration (product → @coreshop.object.link_generator.product, category → @coreshop.object.link_generator.category)

Security

• 🪲 After the user migration, all users are disabled. Run UPDATE objects SET o_published = 1 WHERE o_ClassName = "CoreShopUser"; TRUNCATE TABLE cache_items; to set them to published
• 💡Change password algorithms in CoreShopUser if required (based on your current installation)

Payment

• Make sure, your payment gateways are supporting CS3 (re-implement payum payment interface #2164)

Custom Grid Layouts

• Pimcore Bug: "locked" attribute is missing in every item. Hotfix: Change in DataObjectHelperController line 707: $config['locked'] ?? null
• Then open every grid layout and resave them

Templates

• 🪲Template Customer/settings.html.twig: email field has been removed (Because of it's corresponding Form CustomerType). Currently, it is not possible to change email address. Maybe add another template (e.g. change_email.html.twig)
• 🪲 Block Prefix in CarrierChoiceType has changed: CoreShopFrontend/Form/fields.html.twig: coreshop_checkout_carrier_choice_widget instead of coreshop_carrier_choice_widget
• 💡coreshop_path has been removed, use path or pimcore_object_path
• 💡Checkout/steps/address.html.twig and Checkout/steps/customer.html.twig have changed significantly!
  • There are also a lot of new Forms, make sure to adjust your extensions - if available
• 💡You may want to change item.getTotal() to item.getSubtotal(), see more about that here: Cart Item Adjustment Calculation #2190

Checkout

• 🪲 Revise (Restore Cart) not implemented (see Reimplement User Cart Revise Cancellation #2166)

Cart Processor

• There is a new Cart Subtotal Calculator. If you're dealing with custom Adjustments per Item, you may need to adjust your processor priority.

Cart Context

🪲 If you're using services with tag coreshop.context.cart: Unable to register coreshop.context.cart Services

AddressFormat

All addressFormat needs to be changed:

UPDATE coreshop_country SET addressFormat = '{{ company }}
{{ salutation }} {{ firstname }} {{ lastname }}
{{ street}} {{ number }}
{{ postcode }} {{ city }}
{{ country.name }}
{{ phoneNumber }}' WHERE addressFormat = '%Text(company);
%Text(salutation); %Text(firstname); %Text(lastname);
%Text(street); %Text(number);

%DataObject(country,{"method" : "getName"}); %Text(phone);'

Finalization

• Remove legacy base* base fields from CoreShopOrder and CoreShopOrderItem classes (Check if all your migrations were successful first!)
• Add CoreShopCoreBundle to SettingsStore:

INSERT INTO `settings_store` (`id`, `scope`, `data`, `type`)
VALUES
	('BUNDLE_INSTALLED__CoreShop\\Bundle\\CoreBundle\\CoreShopCoreBundle', 'pimcore', '1', 'string');

[Cruiser13]

Wow, thanks a bunch for writing all these steps down and sharing them @solverat! Will be helpful for our upcoming migrations.

[seybsen]

Am I missing an obvious migration step when I get the following error?

Error: Class Pimcore\Model\DataObject\CoreShopOrder contains 8 abstract methods and must therefore be declared abstract or implement the remaining methods (CoreShop\Component\Order\Model\OrderInterface::getSaleState, CoreShop\Component\Order\Model\OrderInterface::setSaleState, CoreShop\Component\Order\Model\OrderInterface::getQuoteState, ...)

Symfony\Component\ErrorHandler\Error\FatalError:
Error: Class Pimcore\Model\DataObject\CoreShopOrder contains 8 abstract methods and must therefore be declared abstract or implement the remaining methods (CoreShop\Component\Order\Model\OrderInterface::getSaleState, CoreShop\Component\Order\Model\OrderInterface::setSaleState, CoreShop\Component\Order\Model\OrderInterface::getQuoteState, ...)

  at /var/www/html/var/classes/DataObject/CoreShopOrder.php:87

I executed every single step you mentioned in "Preparing"

[dpfaffenbauer]

did you run bin/console pimcore:deployment:classes-rebuild?

[seybsen]

Yes, I ran that command as the last step ("Rebuild classes").

[solverat]

@seybsen I ran into the same issue (I had to remove all the interface definitions => they are not available before migrations have been dispatched). I updated my notes, see Remove methods from Interfaces in the "Preparing" section.

[solverat]

If you're facing further memory issues, you need to modify the migrations

CoreShop does not a very great job when it comes to precheck objects before migrating. Also, all statements will be submitted transactional, so if your migration files due memory issues, it will restart from scratch.

By adding this to the migration (and also adjust the foreach() by checking if a migrated value is already given), you could execute the migration multiple times without restarting from beginning.

    public function isTransactional(): bool
    {
        return false;
    }

[claudesimo1990]

Please, is it possible to do the interface customisation outside the vendor folders ? what is the right way to do the customisation. Because if I make the customizations directly in Vendor then after a Composer update or Install the customizations will be lost.

[dpfaffenbauer]

@claudesimo1990 you cannot change interfaces, you can extend them. thats the point of interfaces, it is a contract that has to be meet in order to work.

[dpfaffenbauer]

@solverat I converted it to a discussion and pinned it.